Skip to main content

Install on Linux

Three commands, start to finish.

1. Check the machine is ready​

# Docker is installed and you can use it without sudo
docker run hello-world

# The NVIDIA driver is installed and Docker can see the GPU
docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi

The second command must print your card. If it fails, the driver or the NVIDIA Container Toolkit is missing — that is the one piece you have to install yourself.

2. Choose a password and keep it​

This encrypts your stored token. Generate one and save it somewhere you will still have it in six months.

export AGENT_ENCRYPTION_PASSWORD="$(openssl rand -base64 32)"
echo "$AGENT_ENCRYPTION_PASSWORD"   # write this down now

3. Run it​

docker run -d --name neurogrid-agent \
  --gpus all --restart unless-stopped \
  --dns 1.1.1.1 --dns 8.8.8.8 \
  -v neurogrid-data:/data \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /var/lib/neurogrid/workloads:/var/lib/neurogrid/workloads \
  -e AGENT_ENCRYPTION_PASSWORD="$AGENT_ENCRYPTION_PASSWORD" \
  ghcr.io/neurogrid-ai-exchange/neurogrid-agent:latest --token ng_live_xxxxxxxx

Replace ng_live_xxxxxxxx with the token from the console. That is the whole install — the image is pulled automatically if you do not have it.

Watch it come up:

docker logs -f neurogrid-agent

You are looking for Bootstrap sent successfully, then Heartbeat sent successfully every 30 seconds. Your GPU turns confirmed in the console at the same moment.

--token is not needed again. Pass it a second time and it is ignored in favour of the stored one.

What each flag is for​

FlagWhy it cannot be dropped
--gpus allWithout it there is no nvidia-smi in the container, so the agent cannot measure VRAM or size a model
--dns 1.1.1.1 --dns 8.8.8.8Docker fixes a container's DNS when it is created and never updates it. Without resolvers that exist on every network, moving this machine between networks silently breaks it — see Troubleshooting
-v neurogrid-data:/dataHolds the encrypted token and your config, so upgrades keep the host registered
-v /var/run/docker.sockHow the agent starts job containers. This is root-equivalent access to the host — the container is packaging, not a security boundary
-v /var/lib/neurogrid/workloadsJob workspaces, at the same path on both sides on purpose: the agent hands this path to the Docker daemon, which resolves it on the host
--restart unless-stoppedSurvives a crash and comes back with the machine, but stays down if you stopped it deliberately

With Docker Compose​

Worth it once you are past testing — it keeps the flags in a file instead of your shell history.

curl -fLO https://raw.githubusercontent.com/NeuroGrid-AI-exchange/neurogrid-agent/main/docker-compose.yml
export AGENT_ENCRYPTION_PASSWORD="$(openssl rand -base64 32)"

docker compose run --rm agent --register-only --token ng_live_xxxxxxxx
docker compose up -d

--register-only exits as soon as registration succeeds instead of continuing into the daemon. Worth a separate step because up -d runs detached: a failed registration would otherwise be a restart loop with the reason buried in the logs, rather than a non-zero exit you see immediately.

Where things live​

Path
Token and configthe neurogrid-data volume, at /data inside the container
Logsdocker logs neurogrid-agent
Job workspaces/var/lib/neurogrid/workloads on the host

Nothing is written to your home directory.

Next​