> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ngram.space/llms.txt
> Use this file to discover all available pages before exploring further.

# Run a persistent worker

> Deploy the Entity on Railway, with durable state and a hosted or private inference route.

A deployed worker keeps the Entity available when your terminal is closed. Its inference can come from a hosted API or a private gateway on another machine.

## Choose the inference route

| Route   | Worker connects to                   | Operational dependency                           |
| ------- | ------------------------------------ | ------------------------------------------------ |
| Hosted  | Your configured API provider         | Provider availability and credentials            |
| Private | Your authenticated inference gateway | Gateway, tunnel, and model host remain available |

The advanced hybrid setup wizard coordinates the home-gateway path:

```bash theme={"theme":"github-light-default"}
uv run ngram setup --profile hybrid
```

For hosted inference, configure the provider directly on the worker using the [hosted guide](/deployment/hosted-inference-testing). A hosted route does not require a home gateway.

## Configure the Railway service

Connect the application repository and use its supplied deployment configuration. Configure one worker service with:

```dotenv theme={"theme":"github-light-default"}
NGRAM_ENTITY=rook
NGRAM_DEPLOYMENT_MODE=hybrid_railway
NGRAM_EXECUTION_WORKSPACE_DIR=/app/data
```

Provide `DATABASE_URL` from your private Postgres service. Attach a persistent volume at `/app/data`. Add the provider and messaging credentials as private service variables.

For a private inference route, also set `NGRAM_INFERENCE_PROVIDER=remote_gateway`, the reachable `NGRAM_INFERENCE_BASE_URL`, and `NGRAM_INFERENCE_GATEWAY_TOKEN`. That token must match the gateway host's `INFERENCE_GATEWAY_TOKEN`.

## Service roles

The checked-in `railway.json` chooses a process from service variables:

| Setting                             | Process                 |
| ----------------------------------- | ----------------------- |
| `NGRAM_ENTITY` with no special role | `ngram worker <Entity>` |
| `NGRAM_RAILWAY_ROLE=api`            | HTTP health service     |
| `NGRAM_RAILWAY_ROLE=hands`          | Execution RPC service   |

The health service does not run the Entity. Stopping it does not stop a separate worker. Only configure the optional hands service if you intend to use a remote execution backend.

## Persistent Python environment on the volume

`docker/entrypoint-railway.sh` prepares the workspace, places the runtime home and caches on it, and manages a volume-backed virtual environment. It installs the declared extras when the dependency stamp changes.

`NGRAM_SKIP_VOLUME_VENV=1` uses the image's Python environment instead while retaining the persistent home and cache layout. Use that option only with an image that already contains the required dependencies.

The database and mounted disk serve different purposes. Follow the [persistence guide](/deployment/persistence) to back up the complete Entity.

## Connect spatial and verify

After the worker is running:

```bash theme={"theme":"github-light-default"}
uv run ngram ar setup rook --target railway
```

Review the selected service and private shell configuration. The pairing tool supports `--no-deploy` when you want to write configuration without triggering a redeploy.

Verify a short conversation, a memory operation, and an actual spatial action separately. Watch the worker logs for provider and storage errors. When finished testing, use inference pause or stop the worker; shutting the browser does not stop server-side activity.