Environment variables - ngram

Set variables in .env at the repo root (gitignored, loaded automatically) or as system/Railway env vars.

Platform tokens

Variable	Purpose
`TELEGRAM_TOKEN`	Telegram bot token (must match `token_env` in entity YAML)
`DISCORD_TOKEN`	Discord bot token
`NGRAM_TELEGRAM_ALLOWED_USER_IDS`	Comma-separated Telegram user allowlist. Merged with YAML `allowed_user_ids`; preferred for real IDs.
`NGRAM_TELEGRAM_OPERATOR_IDS`	Comma-separated Telegram user IDs for `/privacy` operators. Merged with YAML `operator_user_ids`.

Deployment

Variable	Default	Purpose
`NGRAM_DEPLOYMENT_MODE`	`local`	`local` or `hybrid_railway`
`NGRAM_INFERENCE_PROVIDER`	derived	`local`, `remote_gateway` (home tunnel gateway), `openrouter`, or `venice` (hosted OpenAI-compatible APIs for optional harness testing). See Hosted inference (testing).
`NGRAM_INFERENCE_BASE_URL`	—	Gateway: tunnel root URL (no path). Hosted presets: optional override; otherwise defaults are baked in per provider. Must always be the root before `/v1`.
`NGRAM_INFERENCE_TIMEOUT`	`120`	Inference request timeout (seconds)
`NGRAM_INFERENCE_GATEWAY_TOKEN`	—	Bearer token for `remote_gateway` (home inference gateway)
`NGRAM_CF_ACCESS_CLIENT_ID`	—	Cloudflare Access service-token client ID for the home gateway
`NGRAM_CF_ACCESS_CLIENT_SECRET`	—	Cloudflare Access service-token secret for the home gateway
`NGRAM_INFERENCE_API_KEY_ENV`	—	Env var name for the Bearer token (gateway or hosted, depending on provider)
`NGRAM_INFERENCE_PASS_NUM_CTX`	—	`true` / `false`: send Ollama-style `options.num_ctx` on chat. Use `false` for strict OpenAI-compatible hosts (OpenRouter, Venice, etc.).
`OPENROUTER_API_KEY`	—	Bearer key when `NGRAM_INFERENCE_PROVIDER=openrouter` (unless overridden via `NGRAM_INFERENCE_API_KEY_ENV` / YAML).
`VENICE_API_KEY`	—	Bearer key when `NGRAM_INFERENCE_PROVIDER=venice` (unless overridden).
`NGRAM_TIMEZONE`	—	IANA timezone (e.g. `America/New_York`)

| NGRAM_INFERENCE_MODEL | — | Runtime chat model override for both reflex and deliberate cognition. Used by the hosted Quest lab. | | NGRAM_EMBEDDING_MODEL | — | Runtime embedding model override. It must emit the configured memory width (768 by default). |

Ollama

Variable	Default	Purpose
`OLLAMA_HOST`	`http://127.0.0.1:11434`	Override Ollama URL

Database

Variable	Purpose
`DATABASE_URL`	Postgres connection string. When set, all structured memory uses Postgres instead of SQLite.

Execution

Variable	Default	Purpose
`NGRAM_EXECUTION_RPC_URL`	—	Remote execution host URL
`NGRAM_EXECUTION_RPC_TOKEN`	—	Bearer token for execution RPC
`NGRAM_EXECUTION_WORKSPACE_DIR`	—	Pin workspace root (e.g. `/app/data` on Railway). Also anchors the persistent venv (`$WORKSPACE/.venv`) and `HOME` for Railway entrypoint.
`NGRAM_SKIP_VOLUME_VENV`	`0`	Set to `1` to use the image Python instead of `$WORKSPACE/.venv` (debug only).
`NGRAM_VOLUME_HOME`	`$WORKSPACE/.home`	Override `HOME` on the volume (pip / Playwright caches).
`NGRAM_EXECUTION_REQUIRE_RAILWAY`	`false`	Block all local execution when not on Railway

Home gateway

Variable	Default	Purpose
`NGRAM_PYTHON`	—	Optional full path to `python3` for `scripts/gateway.sh` when the interpreter on `PATH` is not the one with ngram installed (common on macOS with multiple Pythons).
`INFERENCE_GATEWAY_TOKEN`	—	Bearer token (must match worker’s `NGRAM_INFERENCE_GATEWAY_TOKEN`)
`OLLAMA_BASE_URL`	`http://127.0.0.1:11434`	Upstream Ollama URL
`INFERENCE_GATEWAY_HOST`	`127.0.0.1`	Gateway listen address
`INFERENCE_GATEWAY_PORT`	`8010`	Gateway listen port
`INFERENCE_GATEWAY_BACKEND_TIMEOUT`	`120`	Timeout for Ollama requests
`INFERENCE_GATEWAY_MAX_BODY_BYTES`	`8000000`	Max request body size
`CF_ACCESS_TEAM_DOMAIN`	—	Cloudflare Access HTTPS team domain used as JWT issuer
`CF_ACCESS_AUD`	—	Cloudflare Access application audience tag
`INFERENCE_GATEWAY_REQUIRE_CF_ACCESS`	`false`	Validate Access JWTs on Cloudflare-originated requests; the tunnel launcher forces `true`
`INFERENCE_GATEWAY_RATE_LIMIT_WINDOW_SECONDS`	`60`	Origin rate-limit window
`INFERENCE_GATEWAY_RATE_LIMIT_UNAUTHENTICATED`	`10`	Unauthenticated requests per caller/window
`INFERENCE_GATEWAY_RATE_LIMIT_AUTHENTICATED`	`90`	Authenticated requests per caller/window
`INFERENCE_GATEWAY_RATE_LIMIT_GLOBAL`	`180`	Global authenticated requests/window

WebXR lab

Variable	Purpose
`NGRAM_AR_HOST`	WebXR bind address; the lab defaults to loopback and sets `0.0.0.0` only for an explicit `--lan` run
`NGRAM_AR_PORT`	WebXR HTTPS port (default `3000`)
`NGRAM_AR_SURFACE_TOKEN`	Random secret that bootstraps the protected browser session; generated by `ngram lab setup`
`NGRAM_AR_ENTITY_BRIDGE_HOST`	Entity bridge bind; the lab requires loopback
`NGRAM_AR_ENTITY_BRIDGE_PORT`	Entity bridge port (default `7878`)
`NGRAM_AR_ENTITY_BRIDGE_TOKEN`	Independent bearer credential shared only with the paired shell
`NGRAM_AR_PERSON_ID`	Cross-surface human identity used for relationship continuity

Object storage

Variable	Purpose
`NGRAM_ATTACHMENTS_BACKEND`	`local_disk` or `object_s3_compat`
`NGRAM_S3_ENDPOINT_URL`	S3-compatible endpoint
`NGRAM_S3_BUCKET`	Bucket name
`NGRAM_S3_ACCESS_KEY`	Access key
`NGRAM_S3_SECRET_KEY`	Secret key

Optional tools

Variable	Purpose
`FIRECRAWL_API_KEY`	Firecrawl key for enhanced web search/scrape
`FAL_API_KEY`	Fal key for image generation
`HOME_ASSISTANT_URL`	Home Assistant API URL for IoT tools
`HOME_ASSISTANT_TOKEN`	Home Assistant Long-Lived Access Token
`MASTODON_URL`	Mastodon instance URL for social broadcast tools
`MASTODON_ACCESS_TOKEN`	Mastodon access token
`X_API_KEY`	X (Twitter) API Key
`X_API_SECRET`	X (Twitter) API Secret
`X_ACCESS_TOKEN`	X (Twitter) Access Token
`X_ACCESS_SECRET`	X (Twitter) Access Secret

Railway

Variable	Purpose
`NGRAM_ENTITY`	Entity name to run (e.g. `canary`)
`NGRAM_RAILWAY_ROLE`	`worker` or `api`
`PORT`	API listen port (default `8080`)

⌘I