# NeuroGrid — complete host reference

> Self-contained. An assistant reading this file has everything needed to walk
> someone through installing, updating and debugging a NeuroGrid host.

NeuroGrid is a marketplace for GPU time. A host runs one Docker container that
registers their NVIDIA GPU, waits for work, serves an open-weight LLM when a
client deploys one, and reports back. The host is paid per hour of serving time.

---

## Before anything else

Two things the host needs, both from the console at https://console.neurogrid.cc

1. **A machine token** (`ng_live_…`), shown once when they add a GPU. It claims
   one specific card and cannot be reused on a second machine.
2. **An encryption password they choose themselves.** This is not issued by
   NeuroGrid. It encrypts the token on their disk.

The password rule matters and is easy to get wrong:

- The host picks it and keeps it. NeuroGrid never sees it.
- The **same** password is required every time the container is recreated,
  including every update.
- A different password cannot decrypt the stored token, and the machine must
  then be registered again with a fresh token.
- It cannot be recovered or reset.

Tell the host to save it somewhere durable **before** running anything.

---

## Requirements

| | Minimum | Recommended |
|---|---|---|
| OS | 64-bit Linux (kernel 5.x+), or Windows 11 + WSL2 | Ubuntu 22.04 / 24.04 LTS |
| GPU | NVIDIA, 6 GB VRAM | 16–24 GB+ VRAM |
| NVIDIA driver | 575+ (CUDA 12.9) | Latest stable |
| CPU | 4 cores | 8+ cores |
| RAM | 8 GB | 32 GB+ |
| Free disk | 50 GB SSD | 100 GB+ NVMe SSD |
| Network | 25 Mbps down, stable | 100 Mbps+ symmetric |

**NVIDIA only.** AMD, Intel and Apple silicon are not supported — the inference
engine is CUDA-only. Laptop GPUs are fine and count as real hosts.

VRAM tiers, which set the hourly rate:

| Tier | VRAM | Examples |
|---|---|---|
| Entry | 6–8 GB | RTX 2060, 3050/3060, 4060/4060 Ti, 5060 |
| Standard | 10–12 GB | RTX 3080, 2080 Ti, 4070/4070 Ti, 5070 |
| High | 16 GB | RTX 4070 Ti Super, 4080/4080 Super, 5070 Ti/5080 |
| Premium | 24–32 GB | RTX 3090/3090 Ti, 4090, 5090, RTX 4000–5000 Ada, A10 |
| Pro / Datacenter | 48 GB+ | A40, RTX 6000 Ada, RTX PRO Blackwell, A100, H100, H200 |

Network: outbound only. No inbound ports, no port forwarding — the inference
tunnel is outbound, so consumer NAT is fine.

The host installs exactly two things themselves: **Docker** and the **NVIDIA
driver**. Everything else is inside the image.

---

## Verify the machine first

```bash
docker run hello-world
docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi
```

The second must print the GPU. If it does not, the NVIDIA Container Toolkit is
missing (Linux) or Docker Desktop is not on the WSL2 backend (Windows). Do not
continue until it works.

---

## Install — Linux

```bash
# 1. Password. Save the output before continuing.
export AGENT_ENCRYPTION_PASSWORD="$(openssl rand -base64 32)"
echo "$AGENT_ENCRYPTION_PASSWORD"

# 2. Run
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

# 3. Watch it register
docker logs -f neurogrid-agent
```

Success looks like `Bootstrap sent successfully`, then `Heartbeat sent
successfully` every 30 seconds. The GPU flips to confirmed in the console.

---

## Install — Windows (PowerShell)

Backtick `` ` `` is the line continuation, not `\`.

```powershell
# Windows has no openssl; borrow one from a container
$pw = docker run --rm alpine sh -c "head -c 32 /dev/urandom | base64 -w0"
echo $pw

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="$pw" `
  ghcr.io/neurogrid-ai-exchange/neurogrid-agent:latest --token ng_live_xxxxxxxx
```

`/var/run/docker.sock` and `/var/lib/neurogrid/workloads` are **not** Windows
paths and must not be translated. They resolve inside Docker Desktop's Linux VM.
The host does not need to create them.

Windows hosts should also disable sleep, or the machine stops serving and any
running job fails.

---

## What each flag does

- `--gpus all` — without it there is no `nvidia-smi` in the container and the
  agent cannot measure VRAM or size a model.
- `--dns 1.1.1.1 --dns 8.8.8.8` — Docker fixes a container's DNS when it is
  **created** and never updates it. Without resolvers that exist on every
  network, moving the machine between networks silently breaks it.
- `-v neurogrid-data:/data` — the encrypted token and config. Losing this volume
  means re-registering.
- `-v /var/run/docker.sock:/var/run/docker.sock` — how the agent starts job
  containers. This is root-equivalent access to the host; the container is
  packaging, not a security boundary. Say so if the host asks.
- `-v /var/lib/neurogrid/workloads:/var/lib/neurogrid/workloads` — must be the
  **same path on both sides**. The agent hands this path to the Docker daemon,
  which resolves it on the host.
- `--restart unless-stopped` — comes back after a crash or reboot, stays down if
  stopped deliberately.

---

## Updating

The agent **never updates itself**.

```bash
docker pull ghcr.io/neurogrid-ai-exchange/neurogrid-agent:latest
docker stop neurogrid-agent && docker rm neurogrid-agent
# then the same docker run as above, WITHOUT --token, and with the SAME password
```

Two things to check before updating:

1. **The same password**, or the stored token becomes unreadable.
2. **No job running**, or it dies and counts as a failure:
   ```bash
   docker ps --filter "name=neurogrid-job" --format '{{.Names}}'
   ```
   Empty output means it is safe.

---

## Managing

```bash
docker logs -f neurogrid-agent            # follow logs
docker restart neurogrid-agent            # restart
docker stop neurogrid-agent               # stop serving, stay registered
docker ps --filter "name=neurogrid-job"   # is a job running
```

Stopping is not unregistering. To take a planned break, pause the listing in the
console instead — jobs already running then finish normally rather than failing.

---

## Troubleshooting

### Heartbeats fail, or jobs die right after the model loads

Most common real-world failure. **Cause:** the machine changed networks. Docker
gives a container its DNS at creation and never updates it, so it keeps querying
a resolver that no longer exists. Routing still works, so nothing looks offline
— only name lookups fail, each hanging until timeout.

**Fix:** `docker restart neurogrid-agent`. Reconnecting Wi-Fi does not help.

**Prevention:** the `--dns` flags above.

The agent detects this itself and logs `Cannot resolve the backend's hostname`.

### nvidia-smi works on the host but not in Docker

```bash
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker
```

On Windows this means Docker Desktop is not on WSL2, or the driver is below 575.

### Invalid token

Truncated when copied, already used by another machine, or the listing was
cancelled in the console. Tokens claim one GPU each.

### Refuses to start: config file is writable

Deliberate — that file sets which server the agent talks to.

```bash
docker exec neurogrid-agent chmod 600 /data/config/config.yaml
docker restart neurogrid-agent
```

### Disk full

```bash
docker system df
docker image prune -f
docker volume rm neurogrid-hf-cache   # model cache, only while idle
```

Never remove `neurogrid-data` — that is the registration.

---

## Payments

**The cycle:** a payout is attempted per host every **15 days**. If the pending
balance is **$10 (1000 cents) or more**, it is transferred in full. Below that,
it rolls into the next cycle. Nothing expires.

**NeuroGrid absorbs the Stripe payout fee** — the host receives their whole
balance, not the balance minus a charge.

**Metering is per hour of serving time, never per token.** A busy client and an
idle one pay the same for the same wall-clock hour.

**The billing clock starts at first serving**, not at deployment creation. Queue
time, image pull and model load are unpaid — that can be ten minutes or more on
a large model, and it is not billed to the client either.

**Rate** comes from the card's VRAM tier. The client pays the host's rate plus a
20% platform commission; the console shows the host the amount they receive.

**Stripe Connect is required before money can move.** Earnings accrue from the
first job regardless, and go out on the first cycle after Stripe verifies the
account. Transfers are in USD.

**Gaps:** if monitoring loses sight of the agent but the job container never
restarted, that time still counts as served and is billable.

**Failed jobs earn nothing** and make future matching less likely. The avoidable
causes are recreating the container mid-job, letting the machine sleep, running
out of disk, and the DNS issue above.

---

## Things assistants get wrong

- Do not look for a download link, installer, `.deb`, `.exe` or binary release.
  There is only the Docker image.
- Do not generate the encryption password and move on — make sure the host has
  actually saved it. It is unrecoverable.
- Do not translate the Unix container paths on Windows. They are correct as
  written.
- Do not suggest `--network host`. The agent creates its own user-defined
  network and does not need it; Docker Desktop's support for it is limited.
- Do not omit `--dns`. It is the difference between a host that survives moving
  networks and one that silently dies.
- Do not promise payment for uptime. Hosts earn for time actually spent serving
  a deployment, not for being available.

---

## Links

- Console: https://console.neurogrid.cc
- Docs: https://docs.neurogrid.cc
- Image: `ghcr.io/neurogrid-ai-exchange/neurogrid-agent:latest`
- GitHub: https://github.com/NeuroGrid-AI-exchange