Gateway configuration
Runtime variables, proxy boundaries, provider credentials, and deployment roles.
These settings belong to the gateway installation, not the official Jian website. The desktop creates its own local runtime configuration; do not replace it with a server .env.
Required server settings
| Variable | Purpose |
|---|---|
DATABASE_URL | PostgreSQL connection used by the gateway and its job queue |
JIAN_API_TOKEN | Owner bearer token; at least 32 characters |
JIAN_ACTIVE_KEY_ID | Keyring entry used for new encrypted vault values |
JIAN_MASTER_KEYS | JSON object mapping key IDs to base64-encoded 32-byte encryption keys |
make setup writes suitable local values. Keep old keyring entries until credentials encrypted with them have been re-encrypted or rotated. Simply changing the active key does not decrypt values written with a missing key.
In Compose, POSTGRES_PASSWORD initializes the database account and is used to construct the gateway's connection URL. Compose deliberately does not reuse the development DATABASE_URL pointing at localhost.
Process and public address
| Variable | Default / behavior |
|---|---|
HOST | 127.0.0.1 for the source server; Compose overrides it to 0.0.0.0 inside the private container network |
PORT | Gateway HTTP port 4310 |
JIAN_ROLE | all, api, or worker; default all |
JIAN_TIME_ZONE | Optional IANA zone for current-time context and schedule defaults |
JIAN_PUBLIC_URL | Optional externally reachable gateway base URL for browser sign-in callbacks |
JIAN_TRUSTED_PROXIES | Comma-separated trusted proxy addresses/ranges; empty trusts no forwarded client identity |
JIAN_WORKSPACES | Workspace root when explicitly configured; preserve it with filesystem backups |
A worker-role process does not expose the normal API listener. Server roles share database state, but commands still execute on the host that processes the work. If you split roles across machines, plan workspace consistency and access to integrations separately.
The published Compose file forwards a fixed set of environment variables. Adding a variable to .env does not automatically inject it into a container unless Compose references it. For an explicit public URL, add an override such as:
# compose.override.yaml
services:
gateway:
environment:
JIAN_PUBLIC_URL: https://jian.example.comApply configuration changes by recreating the relevant service. A shell export in your SSH session does not modify an already-running container.
Web and image selection
| Variable | Location and meaning |
|---|---|
JIAN_GATEWAY_URL | Web service's upstream gateway address; Compose uses http://gateway:4310 |
JIAN_BIND_ADDRESS | Compose host binding for the web port; default 127.0.0.1 |
JIAN_BIND_PORT | Compose published web port; default 4310 |
JIAN_VERSION | Matching gateway/web image tag in Compose; default latest |
Pin a release tag when reproducible rollout and rollback are important. Updating just one of the web/gateway images can leave the panel and API on incompatible contracts.
Network policy
JIAN_ALLOW_PRIVATE_ORIGINS is an explicit host-admin allowlist for private integration/provider origins. Use exact origins including scheme and port. Metadata destinations remain blocked; this is not a switch to disable network validation globally.
Local desktop mode separately permits loopback model and MCP services. Server mode does not mean a model URL pointing at 127.0.0.1 reaches your laptop.
JIAN_TRUSTED_PROXIES controls which upstreams may assert client IP and scheme. Compose defaults to uniquelocal because its web service reaches the gateway over a private network. Match this trust to your actual topology; a public arbitrary sender must not be able to choose its own trusted forwarding identity.
Environment-backed providers
Supported conventional variables include OPENAI_API_KEY, ANTHROPIC_API_KEY, ANTHROPIC_API_TOKEN, and GEMINI_API_TOKEN. Custom provider references use JIAN_PROVIDER_*; MCP environment references use JIAN_MCP_*.
These are alternatives for deployments that manage secrets outside the panel. Variables must reach the gateway process. Keep real secrets out of examples, source control, and logs.
Optional instrumentation
JIAN_CAVEMAN_ENABLED and JIAN_CAVEMAN_PROXY_URL configure the optional Caveman proxy path. The published image can start its bundled record-only listener when enabled. It is optional infrastructure, not a prerequisite for agents, memory, or learning.
Implementation reference
Server environment validation, environment example, and Compose environment mapping.