Configuration

OpalServe loads its configuration through cosmiconfig. Environment variables override file values. Where the file lives, what each option does, and how the three modes differ, all on this page.

Where the config lives

OpalServe searches in this order, taking the first match:

1. opalserve.config.{ts,js,mjs,cjs}
2. opalserve.config.json
3. .opalserverc{,.json,.yaml}
4. opalserve key inside package.json
5. ~/.opalserve/config.json (the global fallback the wizard writes to)

Override the search with --config <path>:

opalserve start --config ./my-config.json

Operating modes

OpalServe runs in one of three modes. The mode is stored at the top of the config; switching modes is a one-line edit plus a restart.

Local mode

Single developer. Everything runs on your machine. No auth.

{
  "mode": "local",
  "servers": [],
  "gateway": { "port": 3456 },
  "storage": { "path": "~/.opalserve/data.db" }
}

Team server mode

For the host machine. Centralized OpalServe; teammates connect via team-client. Auth is mandatory.

{
  "mode": "team-server",
  "servers": [
    {
      "name": "github",
      "transport": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-github"],
        "env": { "GITHUB_TOKEN": "ghp_xxx" }
      }
    }
  ],
  "gateway": { "port": 3456, "host": "0.0.0.0" },
  "auth": {
    "enabled": true,
    "jwtSecret": "your-secure-random-secret",
    "apiKeys": true,
    "sessionTtl": 86400
  },
  "team": {
    "name": "Acme Engineering",
    "maxUsers": 50,
    "allowSignup": false,
    "defaultRole": "developer"
  },
  "storage": { "path": "/var/lib/opalserve/data.db" },
  "rateLimiting": { "enabled": true, "windowMs": 60000, "maxRequests": 100 },
  "logging": { "level": "info" }
}

Team client mode

For each developer's laptop. Connects to a team server using either an API key or a JWT obtained via opalserve login.

{
  "mode": "team-client",
  "teamServer": {
    "url": "https://opalserve.internal.company.com",
    "apiKey": "osk_abc123..."
  },
  "gateway": { "port": 3456 }
}

Environment variables

Variables override file values. Set them in your shell, your CI environment, or your container runtime.

Variable	Default	Purpose
OPALSERVE_API_KEY_SECRET	auto-generated 64-char hex	HMAC secret for API key hashing
OPALSERVE_CORS_ORIGINS	http://localhost:*	Comma-separated extra CORS origins
OPALSERVE_LINK_COMMAND	npx -y opalserve mcp	Command spawned by linked editors
OPALSERVE_NO_BROWSER	unset	Skip auto-opening the dashboard on start
OPENAI_API_KEY	unset	Team Brain LLM provider (when provider: openai)
ANTHROPIC_API_KEY	unset	Team Brain LLM provider (when provider: anthropic)
OLLAMA_BASE_URL	unset	Team Brain LLM provider (when provider: ollama)

Run opalserve doctor to see which variables are set and which are required by your current config.

Storage

The on-disk database is SQLite via sql.js. The default path is ~/.opalserve/data.db in local mode and /var/lib/opalserve/data.db for the recommended team server install.

To back up: stop the server, copy the file, restart. There is no online backup mode in v3.4.

Rate limiting

In team-server mode, rate limits live under rateLimiting. The defaults, 100 requests per minute per IP, are designed for typical team sizes (5–50 developers). Per-user overrides exist via opalserve admin limits.

Logging

Backed by pino. Set logging.level to trace, debug, info (default), warn, error, or fatal. Outputs as line-delimited JSON; pipe through pino-pretty for human-readable terminal output during development.