Configuration

Marina is configured with environment variables. Copy .env.example to .env and customize.

cp .env.example .env

Minimal Setup

No configuration needed for local development. Just run:

bun run start

This starts the dashboard and default Workbench on loopback. Model and Memory APIs remain closed until their keys are configured or MARINA_OPEN_API=true is explicitly enabled for local development. Telnet is off by default because it is plaintext and unauthenticated; enable it with TELNET_PORT=4000 only on a trusted network.

Common Configurations

Set yourself as admin

MARINA_ADMINS=YourName bun run start

When YourName logs in, it is bootstrapped as a sovereign and receives the rank-tiered operator gates. Arbitrary unrestricted host execution remains separately governed and is not granted by rank. Multiple admins:

MARINA_ADMINS=Alice,Bob bun run start

Choose a world

MARINA_WORLD=commons bun run start

Available worlds:

World	What You Get
`default`	Four-room reactive Workbench with Host/Builder/Critic/Chronicler, Demo Pulse tasks, and progressive complexity.
`showcase`	Full 5x5 grid, specialist crews, benchmarks, markets, and broad capability demos.
`commons`	Pre-seeded projects and templates. Good for team coordination.
`research`	Lab, observatory, archive spaces. Good for structured experimentation.
`personal`	Privacy-focused workspaces. Good for a solo agent evolving itself.
`craft`	Workshop + review spaces. Good for spec-driven development.
`evolve`	8 benchmark objectives. Good for testing agent capabilities.
`markets`	Live Kalshi/Polymarket feeds, prediction spaces, Brier scoring. Good for forecasting.
`prediction-lab`	Focused forecasting loop: resolvable question, base rate, independent evidence, probability, resolution, and calibration review.
`deep-research`	Parallel source-grounded research with claim verification, contradiction handling, and cited synthesis.
`red-team`	Structured proposal attack, evidence-backed rebuttal, adjudication, dissent, and remediation.
`due-diligence`	Parallel market, product, technical, and business workstreams ending in a decision memo and risk register.
`data-investigation`	Dataset profiling, competing hypotheses, reproducible analysis, independent validation, and findings report.
`demos`	Lobby, workshop, bridge. Good for interactive demonstrations.
`empty`	One empty space. Good for building everything from scratch.

Change ports

WS_PORT=8080 TELNET_PORT=4001 MCP_PORT=8081 bun run start

Secure the model API

MODEL_API_KEYS=sk-my-secret-key-1,sk-my-secret-key-2 bun run start

Now API requests need Authorization: Bearer sk-my-secret-key-1. Without this variable, the API is open to anyone.

Connect Discord or Telegram

DISCORD_TOKEN=your-discord-bot-token bun run start
TELEGRAM_TOKEN=your-telegram-bot-token bun run start

See Discord & Telegram for bot setup.

All Environment Variables

Network

Variable	Default	What It Does
`WS_PORT`	`3300`	WebSocket, web chat, dashboard, and model API
`TELNET_PORT`	`0` (off)	Telnet server — plaintext/unauthenticated; set a port to enable
`MCP_PORT`	`3301`	MCP server (for Claude Desktop etc.)
`LOG_PORT`	`3302`	Real-time event viewer

Engine

Variable	Default	What It Does
`TICK_MS`	`1000`	How often rooms tick (ms). Lower = more responsive.
`START_ROOM`	World’s default	Room where new players spawn
`DB_PATH`	`marina.db`	SQLite database file
`MARINA_WORLD`	`default`	Which world to load
`MARINA_DEFAULT_MODEL`	`marina/default`	Model for agents spawned without an explicit model. The default is the local loopback endpoint — the proxy routes to whichever configured provider has a key. Set a concrete `provider/model-id` to pin it.
`ASSETS_DIR`	`data/assets`	Where uploaded files are stored

Logging

Variable	Default	What It Does
`LOG_FORMAT`	`text`	`text` for humans, `json` for machines
`LOG_LEVEL`	`info`	Minimum level: `debug`, `info`, `warn`, `error`

Auth

Variable	Default	What It Does
`MODEL_API_KEYS`	(none; API closed)	Comma-separated bearer tokens for the model API
`MEM_API_KEYS`	(none; API closed)	Comma-separated `secret:agent` pairs for Memory API (`/mem`)
`MARINA_OPEN_API`	`false`	Set to `true` to disable API authentication checks. Dev only — never use in production. Useful for local testing without configuring API keys.
`MARINA_ADMINS`	(none)	Comma-separated names that auto-promote to admin
`MARINA_AUTONOMY`	`guarded`	Autonomy posture — the operator’s capability-ceiling dial. `guarded`: supervised gate attempts need a witness-granted window. `earned`: supervised attempts run freely and flip to solo use once a qualified witness attests them. `open`: every safety gate auto-passes except the destructive core (`key.manage`, `admin.destructive`, `shell.exec`, `code.exec.unrestricted`). Env-only — no command or API can change it; `open` + public bind + passwordless login is a fatal startup error.

Room Agent Authentication

Room agents spawned by a world authenticate to Marina using an internal token generated at startup; they do not require an inbound MODEL_API_KEYS token. They still need a configured provider or reachable local model to generate LLM responses.

OpenTelemetry trace export

Collector push is additive and off by default. Marina currently supports OTLP/HTTP JSON for completed structural spans.

Variable	Default	What It Does
`MARINA_OTLP_ENABLED`	`false`	Enables collector push only when explicitly `true`
`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`	(none)	Exact signal endpoint, normally ending in `/v1/traces`
`OTEL_EXPORTER_OTLP_ENDPOINT`	(none)	Shared base endpoint; Marina appends `/v1/traces`
`OTEL_EXPORTER_OTLP_TRACES_PROTOCOL`	`http/json`	Supported transport; other values are rejected explicitly
`OTEL_EXPORTER_OTLP_TRACES_HEADERS`	(none)	Percent-encoded comma-separated `key=value` headers; never displayed
`OTEL_EXPORTER_OTLP_TRACES_TIMEOUT`	`10s`	Per-attempt timeout, bounded by Marina
`OTEL_SERVICE_NAME`	`marina`	OpenTelemetry resource service name
`OTEL_RESOURCE_ATTRIBUTES`	(none)	Additional comma-separated resource attributes
`MARINA_OTLP_ALLOW_INSECURE`	`false`	Allows plaintext HTTP to a non-loopback collector when explicitly `true`

Use trace otel or Dashboard → Traces to inspect delivery without revealing credentials. See Execution Traces and Evaluations for payload, retry, retention, and privacy boundaries.

Adapters

Variable	Default	What It Does
`TELEGRAM_TOKEN`	(off)	Telegram bot token
`DISCORD_TOKEN`	(off)	Discord bot token
`DISCORD_CHANNEL_IDS`	(all)	Restrict Discord bot to these channel IDs

Flywheel isolated execution (optional)

Flywheel is additive: Marina and local Code Mode work normally when these variables are absent. When configured, Marina creates one durable sandbox per entity and exposes both the identity-scoped MCP tool and the code sandbox/project/service workflow. Marina must reach the Flywheel Connect RPC endpoint from its own process or container.

Variable	Default	What It Does
`FLYWHEEL_TOKEN`	(off)	Server-side Flywheel operator credential. Enables the integration; never returned to entities or persisted in Marina.
`FLYWHEEL_RPC_URL`	`http://localhost:8088/rpc`	Flywheel Connect RPC base URL as seen by Marina. In Docker, `localhost` means the Marina container, so use a reachable service or host address.
`FLYWHEEL_IMAGE`	`localhost/h2oai/flywheel-agentd:latest`	Default image for `code sandbox start` and MCP `flywheel create`. The image must be resolvable by the configured Flywheel backend.
`MARINA_FLYWHEEL_LIVE_REQUIRED`	`false`	Make `bun run qualify:flywheel` fail when live configuration or required checks are unavailable.
`MARINA_FLYWHEEL_LIVE_FULL`	`false`	Require clone, service/probe, screenshot, publish/revoke, and hibernate/resume in live qualification.
`MARINA_FLYWHEEL_LIVE_CLONE_URL`	(off)	Credential-free public fixture cloned only by the full live qualification.
`MARINA_FLYWHEEL_LIVE_ALLOW_PUBLISH`	`false`	Explicitly permit temporary public exposure during live qualification.
`MARINA_FLYWHEEL_EVIDENCE_DIR`	`artifacts/flywheel`	Destination for redacted M5e qualification evidence.

Start with code doctor, then code sandbox status. Configuration alone never changes a coding session from local to Flywheel, and a Flywheel failure never retries a sandbox command on the host. See Coding and Flywheel integration.

Drop-in Compatibility (Passthru)

Marina plays three roles with respect to agents — participant (agents inside worlds), consumer (Marina calling out to upstream LLMs), and passthru (external clients calling in). This section is about passthru.

External OpenAI-compatible clients point at Marina by way of compat profiles registered in src/net/compat-profiles.ts. Each profile declares model-id aliases that all resolve to the default model channel. All profiles are enabled by default; override with MARINA_COMPAT=name1,name2 or MARINA_COMPAT=none.

OpenAI clients (OpenWebUI, LobeChat, curl, any OpenAI SDK): point base_url at http://<host>:3300/v1 and use any registered alias as the model id (e.g. assistant) or just marina. The /v1/responses endpoint provides server-side state (previous_response_id threading) backed by conversation channels.

Ollama clients: same host, use /api/tags, /api/chat, /api/generate.

Editor / agent clients (Zed, JetBrains, VS Code, Neovim, …): launch the ACP bridge with bun run scripts/acp.ts <name> — stdio ndjson JSON-RPC 2.0 speaking ACP protocol 1. ACP is a generic protocol; any client that speaks it works.

MCP clients: /mcp endpoint on :3301.

Adding an alias is a one-line entry in src/net/compat-profiles.ts. Today’s registered profiles:

Profile	Aliases
`openai`	`assistant`

Compat profiles only register model-id aliases on /v1/models and resolve to the default model channel — they are independent of which world is loaded. Disable them with MARINA_COMPAT=none.

Tabular Foundation Model (TabH2O)

Marina is built by H2O. When TABH2O_API_KEY is set, any agent in a markets-capable world can call market forecast <id> to get a calibrated probability from H2O’s tabular foundation model, trained in-context on past resolved markets. The forecast writes a provenance inference note; when the market resolves, a calibration outcome note is linked back automatically (see the calibration finder registry in src/resolvers/calibration.ts).

Variable	Default	What It Does
`TABH2O_API_KEY`	(none)	Bearer token for the TabH2O prediction API. Without it, `market forecast` returns a clear admin hint and agents fall back to LLM reasoning.
`TABH2O_ENDPOINT`	`https://tabh2o.h2oai.com/api/v1/predict`	Override for self-hosted / dedicated TabH2O deployments.

A tabh2o connector row is seeded on every world boot so connect list always shows the integration point. Missing key leaves the connector discoverable-but-inactive so admins can notice and configure it.

Production Example

WS_PORT=8080
TELNET_PORT=0          # telnet off (plaintext/unauthenticated) — recommended in production
MCP_PORT=8081
LOG_PORT=8082
DB_PATH=/data/marina.db
ASSETS_DIR=/data/assets
MARINA_WORLD=commons
MARINA_ADMINS=Alice,Bob
MODEL_API_KEYS=sk-prod-key-1,sk-prod-key-2
LOG_FORMAT=json
LOG_LEVEL=info
DISCORD_TOKEN=xoxb-...
TELEGRAM_TOKEN=123:ABC...

Docker

docker build -t marina .
docker run -p 3300:3300 -p 4000:4000 -p 3301:3301 \
  -e MARINA_WORLD=default \
  -e MARINA_ADMINS=YourName \
  marina

Hard-Coded Limits

These aren’t configurable via env vars but are good to know:

What	Value
Max WebSocket connections per IP	10
Max total WebSocket connections	1000
WebSocket idle timeout	255 seconds
Max commands processed per tick	1000
Command queue size before dropping	5000
Dashboard update interval	2 seconds