面向 LLM
这个网站上的所有内容，被压缩成一个 Markdown 文件，你可以把它交给 AI 助手，让它帮你完成主机的配置。
把它粘贴进 ChatGPT、Claude、Copilot——任何工具都行——然后让它带你一步步完 成安装。这份文件是写给模型读的，而不是给人浏览的：完整、自成一体，并且结 尾专门列出了助手在这里实际会犯的错误，让它在问题传到你这里之前先自己改正 过来。
如果你的助手可以浏览网页，这样就够了：
阅读 https://docs.neurogrid.cc/llms-full.txt，帮我在这台机器上
配置一个 NeuroGrid 主机。
否则，复制下面的内容。
llms-full.txt
# 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 \
--log-driver json-file \
--log-opt max-size=10m \
--log-opt max-file=3 \
--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 `
--log-driver json-file `
--log-opt max-size=10m `
--log-opt max-file=3 `
--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 USD (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.
---
## nrgrd — the terminal client
nrgrd is for people *using* inference, not for hosts. It is a terminal coding
agent that connects to any OpenAI-compatible endpoint, including a NeuroGrid
deployment. It is published on PyPI as `nrgrd`
(https://pypi.org/project/nrgrd/), runs on macOS, Linux and Windows, and needs
Python 3.11 or newer.
Install, preferably with uv, which also downloads a suitable Python:
```bash
uv tool install nrgrd # or: pipx install nrgrd
nrgrd --version
```
First run: `cd` into a project and run `nrgrd`. It asks for the deployment's
endpoint URL and API key (from the console), then picks the model automatically
when the endpoint serves only one. The key is stored in the OS credential store.
Update with `uv tool upgrade nrgrd`; remove with `uv tool uninstall nrgrd`.
Windows with OneDrive (common on work laptops) can fail with
`incompatible hardlinks (os error 396)`. Fix:
```powershell
uv tool uninstall nrgrd
uv tool install nrgrd --link-mode=copy
```
Other install problems: `nrgrd` not found → `uv tool update-shell` (or
`pipx ensurepath`) and a new terminal. `externally-managed-environment` → use uv
or pipx instead of system pip.
---
## NeuroChat — the browser chat app
NeuroChat is for people *using* inference, not for hosts. It is a chat app at
https://chat.neurogrid.cc that connects to any OpenAI-compatible endpoint,
including a NeuroGrid deployment. No account, nothing to install.
**NeuroGrid does not store NeuroChat data.** Chats, attachments, connections
(endpoint URLs and API keys), MCP servers and settings are saved only in a
SQLite database inside the user's browser (OPFS). Consequences:
- No sync between devices or browsers.
- Clearing the browser's site data deletes the chats permanently. NeuroGrid
cannot recover them.
- Private windows, or a second NeuroChat tab, run in memory and save nothing.
- Temporary chats are never saved.
- The only backup is a download: chat menu → Share… → Markdown or JSON.
What leaves the browser: messages and the API key go to the endpoint the user
connected; MCP tool calls go to the MCP servers they added, after approval;
model names go to Hugging Face for icons and capabilities. Speech-to-text
(Whisper) and voice mode (Kokoro) run in the browser; audio is never uploaded.
Optional proxy: a connection can be set to "Route through NeuroChat proxy" for
endpoints that block browser requests (CORS). The proxy forwards the request
without storing or logging messages or keys, and only to `*.neurogrid.cc` and
`*.trycloudflare.com` over HTTPS.
Setup: Settings → Connections → endpoint URL and API key from the console →
Test → Add → pick a model.
---
## Things assistants get wrong
- Do not look for a download link, installer, `.deb`, `.exe` or binary release
for the agent. There is only the Docker image. (nrgrd, the separate terminal
client, is the one thing that installs from PyPI.)
- 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 tell a NeuroChat user their chats are backed up, synced or
recoverable by NeuroGrid. They exist only in that browser.
- 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`
- nrgrd on PyPI: https://pypi.org/project/nrgrd/
- NeuroChat: https://chat.neurogrid.cc
- GitHub: https://github.com/NeuroGrid-AI-exchange
也可以直接使用原始文件，如果你更想链接而不是粘贴： llms-full.txt · llms.txt（简短索引，遵循 llms.txt 规范）
这个文件是英文的
llms-full.txt 是写给 AI 助手读的，而助手理解英文完全没有问题——所以它保
持单一语言，没有和网站其他部分一起翻译。