Skip to content

Configuration ​

Portolan reads one JSON file, portolan.config.json. Every option has a default, so an empty file is valid. The file is read by the portolan CLI; the server and compiler libraries take typed options directly.

Where the file is found ​

  1. --config <path> on the command.
  2. PORTOLAN_CONFIG in the environment.
  3. ./portolan.config.json.

A missing file means the defaults. A file that is not a JSON object, or an option with the wrong type, is an error with the file path and the key.

Unknown keys are ignored, so a config written for a newer CLI still loads in an older one.

Options ​

KeyTypeDefaultUsed byMeaning
sitestring"site"init, compile, export-skillsSite name; init writes policies/<site>.json and maps/<site>/.
mapsstring"maps"serve, initDirectory containing maps/<site>/v<n>.json.
skillsstring"skills"export-skills, initOutput directory for portolan-<site> skills.
policiesstring"policies"initDirectory containing <site>.json egress policies.
databasestring"portolan.db"serveSQLite path. :memory: gives an ephemeral store.
hoststring"127.0.0.1"serveListen address.
portinteger ≥ 04200serveListen port. 0 asks the OS for one.
baseUrlstringunsetcompile, verifyLive site origin, used when --base-url is not passed.
chromestringunsetcompile, verifyChrome binary. Unset means CHROME_PATH, then the usual install paths.
headlessbooleantruecompile, verifyRun Chromium headless. --headed overrides it to false.
sessionTtlMsinteger ≥ 11800000 (30 min)serveIdle time after which a session is closed.
maxOpenSessionsinteger ≥ 1100serveA create at the cap returns 429 session_limit.
cleanupIntervalMsinteger ≥ 160000 (60 s)serveHow often the expiry sweep runs.
recoverSessionsbooleantrueserveClose sessions left open by a previous process at startup.
logLeveldebug | info | warn | error"info"serveStructured log threshold.

Example ​

json
{
  "site": "store",
  "maps": "maps",
  "skills": "skills",
  "policies": "policies",
  "database": "portolan.db",
  "host": "127.0.0.1",
  "port": 4200,
  "headless": true,
  "sessionTtlMs": 1800000,
  "maxOpenSessions": 100,
  "cleanupIntervalMs": 60000,
  "recoverSessions": true,
  "logLevel": "info"
}

portolan init writes this file with the defaults for the chosen site.

Precedence ​

A command flag beats the config file, which beats the default. For example, portolan serve --port 5000 listens on 5000 even when the file says 4200.

Environment ​

These are read in addition to the config file:

VariableDefaultMeaning
PORTOLAN_CONFIG./portolan.config.jsonConfig file, when --config is absent.
CHROME_PATHauto-detectChrome binary, when chrome is unset.
PORTOLAN_INSTANCE_IDunsetStable id used to reap a hard-killed predecessor's browsers.
PORTOLAN_AUTH_TOKENunsetBearer token for serve; required for a non-loopback bind unless PORTOLAN_ALLOW_REMOTE=1.
PORTOLAN_ALLOW_REMOTEunset1 opts a non-loopback bind in without a token.
PORTOLAN_<SITE>_<KEY>unsetSite-scoped credential, e.g. PORTOLAN_STORE_API_KEY.
ANTHROPIC_API_KEYunsetAnthropic provider for compile and repair.
OPENAI_API_KEYunsetOpenAI provider for compile and repair.
GEMINI_API_KEYunsetGemini provider.
OLLAMA_HOSTunsetLocal Ollama endpoint.
DATABASE_PATHportolan.dbUsed by start.ts (the bare server process), not portolan serve.
PORT / HOST4200 / 127.0.0.1Used by start.ts, not portolan serve.

portolan doctor reports which provider variables are set without printing their values.

Not in the config file ​

These are programmatic options, passed to createServer by a host:

OptionDefaultMeaning
storerequiredA SessionStore. The server never creates or closes it.
mapsunsetA MapStore; enables GET /v1/sites/:site/health and the MCP surface.
executornotReadyExecutorThe op executor.
canaryunsetA CanaryScheduler, started and stopped with the server.
browsersnew registryBrowserRegistry for session-owned engines.
substrateFactoryunsetCreates the browser substrate for view, act, and read.
ledgerthe store's SQLite ledgerThe write idempotency ledger.
loggerfalseFastify's request log.
logunsetA structured Logger for lifecycle events.

They are not config keys because they are live objects, not data: a config file cannot name a function or a database handle.

Released under Apache-2.0 · MIT · CC-BY-4.0