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:

uv run ngram setup --profile hybrid

For hosted inference, configure the provider directly on the worker using the hosted guide. 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:

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 to back up the complete Entity.

Connect spatial and verify

After the worker is running:

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.