Environment variables

Every NGRAM_* and platform variable.

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

Blender execution

Variable	Default	Purpose
NGRAM_BLENDER_EXECUTABLE	blender on PATH	Executable name or full path on the selected execution host. A per-call executable overrides it.

Set this on the computer running the execution backend, not the model provider or display browser. Projects live under .ngram/blender/ in the execution workspace. See Blender for setup and persistence for backups.

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)