Pico Engine environment variables

The pico-engine process reads configuration from environment variables when it starts (via the pico-engine CLI). Set these in your shell, process manager, or container definition before launching the engine.

Most installs only need PORT, PICO_ENGINE_HOME, and PICO_ENGINE_BASE_URL. The others control registration policy and localhost access to the internal HTTP API.

Variables

`PORT`

Default: 3000
Purpose: TCP port the HTTP server listens on.
Notes: The engine binds on all interfaces for that port. Use a reverse proxy (nginx, Caddy, etc.) for TLS and hostname routing; setting PICO_ENGINE_BASE_URL alone does not enable HTTPS.

`PICO_ENGINE_HOME`

Default: ~/.pico-engine/
Purpose: Directory for persistent engine data: LevelDB database, log file (pico-engine.log), and ruleset cache.
Notes: Use a dedicated path in production and back it up before upgrades. Docker images often set this to something like /var/pico-image and mount a volume there.

`PICO_ENGINE_BASE_URL`

Default: http://localhost:<PORT> (derived from PORT if unset)
Purpose: Public URL clients use to reach this engine — scheme, host, and port, no trailing path.
Used for: WebAuthn / passkey relying-party origin, invite links, and OAuth redirect base.
Notes: Must match what users type in the browser (including https:// behind a reverse proxy). Mismatch causes passkey registration or login to fail.

`PICO_ENGINE_ALLOW_SELF_SIGNUP`

Default: off (unset or any value other than true / 1)
Purpose: Controls whether new accounts can register after the first bootstrap account exists.
When off: Only the first account (bootstrap), legacy mesh claim, or a valid invite link can create a new account.
When on: Set to true or 1 to allow anyone to register additional accounts and root picos.
Notes: Invites still work when self-signup is off. Useful for private or single-tenant deployments.

`PICO_ENGINE_ALLOW_LOCALHOST_C`

Default: on (localhost bypass enabled)
Purpose: Controls whether requests to /c/* from localhost require a passkey session cookie.
Default behavior: Requests from 127.0.0.1, ::1, or localhost may call /c/* without signing in. This supports in-engine KRL HTTP loops (ctx:event, event, etc.) that POST to http://localhost:…/c/….
To disable: Set to 0 to require a passkey session for /c/* even from localhost.
Security note: With the default, any process on the same machine can call /c/* without authentication. Use 0 on shared dev hosts or when testing external-auth behavior. External /sky/* access is governed separately by OAuth (see OAuth mesh documentation).

Quick reference

Variable	Default	Set to enable / change

Variable	Default	Set to enable / change
`PORT`	`3000`	Any positive integer
`PICO_ENGINE_HOME`	`~/.pico-engine/`	Absolute path to data directory
`PICO_ENGINE_BASE_URL`	`http://localhost:<PORT>`	Public URL, e.g. `https://engine.example.com`
`PICO_ENGINE_ALLOW_SELF_SIGNUP`	off	`true` or `1` for open registration
`PICO_ENGINE_ALLOW_LOCALHOST_C`	on	`0` to require session on `/c/*` from localhost

Example

export PORT=3000
export PICO_ENGINE_HOME=/var/lib/pico-engine
export PICO_ENGINE_BASE_URL=https://engine.example.com
export PICO_ENGINE_ALLOW_SELF_SIGNUP=false
export PICO_ENGINE_ALLOW_LOCALHOST_C=0

pico-engine

Run pico-engine --help for a short summary of these variables on the installed CLI.

Not operator-configured

NODE_ENV — Used internally (e.g. test log formatting). Do not set in production unless you know why; the engine test suite sets NODE_ENV=test automatically.