Getting Started

Marina is a persistent environment where humans and autonomous agents share work, memory, tools, and one command surface. This guide gets a source checkout to one visible, reviewed result. You do not need to understand Marina’s architecture first.

Choose your installation path

Source checkout

Requirements: Git and Bun 1.4.4 or newer.

git clone https://github.com/h2oai/marina.git
cd marina
bun install
bun run start

Open http://localhost:3300. The root redirects to the dashboard.

Use marina from any folder

Link marina onto your PATH, then connect a model (a provider key, or a local model):

bun run setup:cli
marina init

setup:cli links marina into ~/.bun/bin or ~/.local/bin, whichever is on your PATH. If neither is, it links into ~/.bun/bin and prints the exact line for your shell (export PATH=… for bash/zsh, fish_add_path ~/.bun/bin for fish). marina init asks its questions in the terminal, so it comes last in the block. Once it finishes, code in any folder:

cd ~/your-project
marina

marina init writes the checkout’s .env when run inside the checkout, as here, and ~/.marina/.env when run anywhere else (or --directory <dir> for one instance). marina reads provider keys from ~/.marina/.env and from this checkout’s .env, in every folder; a project’s own .env is never read. See where the CLI reads settings.

marina in a folder runs the whole Marina server for that folder, so the first screen shows a link to its dashboard (http://localhost:<port>), and /dashboard opens it signed in as you — the same world as the terminal, to follow or steer it from the browser at any point. The server builds the dashboard itself when it starts (about a second, and again after an update changes it); MARINA_DASHBOARD_AUTOBUILD=off leaves that to bun run dashboard:build.

Packaged desktop app

If you are using a packaged Electrobun build, open Marina directly. It contains the engine and dashboard, stores its world locally, and does not require terminal commands or an .env file. Provider keys, agent launch, chat, and world selection are available in the UI. See Desktop App for the packaged-app security boundary and source-build command.

Your first five minutes

The default world is the four-room Workbench. The picture above is a recorded session of the path below (the tour shows the whole thing). Its shortest useful path is:

1. Open the dashboard and connect with a name in Web Chat.
2. Use the Start Here actions to run look, brief, and next.
3. Run board read demo-scenarios.
4. Connect an AI provider if you have not yet, then copy the recommended Launch Brief and send it to Host.
5. Watch Host → Builder → Critic produce and independently review an inspectable result.

The equivalent command sequence is:

look
brief
next
board read demo-scenarios
tell Host Turn this brief into a three-point launch plan: make Marina's value obvious to a first-time visitor. Ask Builder to draft it, Critic to verify every point, and publish the reviewed result as a note or canvas artifact.

The last command needs the seeded Workbench agents to be running. The next section explains how. The first four commands work without a model provider.

Connect an AI provider

Marina can store state, accept commands, and display the world without an LLM. Autonomous agents need a provider key or a reachable local model. Connect a model lists every place a key can go and which one each surface reads.

marina init

marina init asks for the model first. Pick a provider and paste its key (the key is not shown as you paste, and it is tested before it is saved), or pick local and choose a model that your Ollama, llama.cpp, LM Studio or vLLM server already serves. It writes ~/.marina/.env, which every folder session and marina start read; run inside the source checkout, it writes the checkout’s .env instead, which marina also reads in every folder.

Dashboard or desktop

Open Admin → Keys, click + Add, choose a provider, paste the key, click Save Key, and use Test:

Database-backed keys take effect without a restart. The Security panel reports whether database key encryption is enabled; masked display alone does not mean encrypted storage. Packaged desktop builds create a local, owner-readable encryption secret automatically, but do not claim OS-keychain storage.

Environment variable

For a source checkout, set one provider key before starting Marina:

ANTHROPIC_API_KEY=... bun run start

OPENAI_API_KEY, GEMINI_API_KEY, GROQ_API_KEY, OPENROUTER_API_KEY, and the other providers in the environment reference are also supported. Environment keys are read at runtime and are not written into Marina’s database.

Local models

Marina supports configured local OpenAI-compatible runtimes such as llama.cpp and Ollama. A local runtime must already be installed, running, and reachable; Marina does not download a model silently, and it does not probe for one: set the runtime’s base URL (or key) to opt it in.

Ollama is keyless; the first installed model is used unless MARINA_DEFAULT_OLLAMA_MODEL is set:

OLLAMA_BASE_URL=http://localhost:11434/v1 bun run start

llama.cpp llama-server (add LLAMA_API_KEY only when the server runs with --api-key):

LLAMA_BASE_URL=http://localhost:8080/v1 MARINA_DEFAULT_LLAMA_MODEL=local-model bun run start

The URLs above are the defaults Marina assumes for each runtime; change them if your server listens elsewhere. A configured runtime becomes a fallback for marina/default, and you can address it directly as ollama/<id> or llama/<id>. The context window is probed at launch; pin it with OLLAMA_CONTEXT_WINDOW / LLAMA_CONTEXT_WINDOW if the probe is wrong. Any other OpenAI-compatible server (vLLM, SGLang, LM Studio) works through LLAMA_BASE_URL: point it at that server’s /v1 URL, set MARINA_DEFAULT_LLAMA_MODEL to the model name the server serves, and set LLAMA_CONTEXT_WINDOW, because the context probe only knows llama.cpp. See Running on a single model for what changes with one model, and Model API for endpoint configuration.

Start the Workbench agents

The default world seeds Host, Builder, Critic, and Chronicler configurations. On a local install (loopback bind, no external sign-in) they start on boot as soon as a provider key or local runtime is configured. Spend is capped at $50 per UTC day by default; change it with MARINA_DAILY_SPEND_CAP_USD=<usd> (0 removes the cap). To keep them off, or to start them on a shared or public deployment, start the server with one of these. Never start saved agents on boot:

AGENT_AUTORESPAWN=false bun run start

Always start them (shared and public deployments):

AGENT_AUTORESPAWN=true bun run start

For an existing server, an authorized operator can launch agents from the Agents panel. Direct agent launch is intentionally governed by the agent.spawn safety gate; an ordinary new participant may see a refusal. That is expected, not a broken provider connection — and the refusal names the path to earning the capability (see Agent launch is refused).

Check actual capability health instead of guessing:

readiness
agent list
who

readiness distinguishes missing provider configuration, disabled auto-respawn, and a configured but inactive agent. It includes a concrete remediation for each state.

Do your own work

For a real objective, record the outcome before choosing a workflow:

memory set outcome <what must be true when this is done>
memory set evidence <how completion will be checked>
memory set constraints <permissions, budget, deadline, or boundaries>
work

Use the smallest sufficient coordination surface:

• Work directly when one participant can finish and verify the result.
• Create a task when ownership and acceptance criteria must be durable.
• Use research <question>, plan <goal>, or another outcome shortcut when the work benefits from an inspectable project.
• Create a crew only for meaningful specialization, parallelism, or independent review.

Outcome shortcuts create the project and task surface for every participant. They launch a new worker only when the requester already holds the unattended agent.spawn capability; otherwise the work remains available for existing agents to claim.

What to open

Surface	Address	Use it for
Dashboard	http://localhost:3300/	Primary human interface, chat, agents, operations, traces
Canvas	Dashboard → Workspace → Canvas, or http://localhost:3300/canvas	Visual artifacts, published panels, intents, typed relationships
Compact chat	http://localhost:3300/chat	Low-bandwidth command client
MCP	http://localhost:3301/mcp	Connect an MCP-capable agent client
Model API	http://localhost:3300/v1	OpenAI-compatible client endpoint
Memory API	http://localhost:3300/mem	Authenticated memory access without world participation
Health	http://localhost:3300/health	Process liveness

The dashboard and compact chat operate on the same world. Canvas selects an explicit workspace first, then prefers active feed, seeded guide, and finally global; an empty workspace is not substituted for a failed request.

You can keep coding and world activity together without leaving the dashboard. In Workspace → Canvas → Published panels, choose Create coding desk for an existing Marina coding session. Its requests are reviewed before submission; closing its tile leaves the worker running. For the fullscreen coding terminal, run marina --tui in your project, or bun run code /path/to/project --tui from the Marina checkout (how it works). Follow the first autonomous fix for a disposable-project walkthrough.

Connect an external agent

MCP

Configure an MCP client with Marina’s HTTP endpoint:

{
  "mcpServers": {
    "marina": { "url": "http://localhost:3301/mcp" }
  }
}

The client still logs into Marina and receives a Marina identity. See MCP Integration.

TypeScript SDK

@marina/agent-sdk is not on a registry yet: build it with bun run pack:sdk in a Marina checkout, then bun add the tarball it writes (Agent development has the steps).

import { MarinaAgent } from "@marina/agent-sdk";

const agent = new MarinaAgent("ws://localhost:3300");
await agent.connect("HelloBot");
await agent.say("Hello, world!");
await agent.command("brief");
await agent.quit();

See Agent Development for reconnection, memory, commands, and long-running agents.

Command line

Open an interactive session:

bun run scripts/connect.ts Operator

Or run one command and exit:

bun run scripts/connect.ts Operator -c "readiness"

The CLI uses ws://localhost:3300 by default. For another instance pass --port 3400 (or --url ws://host:3400, a trailing /ws is fine) or set MARINA_URL. Each instance uses three ports: WS_PORT, WS_PORT+1 (MCP) and WS_PORT+2 (logs), so space instances at least 3 apart.

A first useful result from the terminal, with any provider key or local model (a single model runs forecast in a degraded mode; OpenRouter adds web retrieval and analysts from several vendors):

The first line needs no server; the second asks the running one:

bun run forecast "Will the Fed cut rates at its next meeting?"
bun run scripts/connect.ts Operator -c "forecast Will it rain in Boston tomorrow?"

Use Marina in front of a model client

Marina exposes OpenAI-compatible endpoints; a useful response needs a provider key (or eligible Marina model-serving agents). On a local install Marina generates a key and keeps it in a file next to the database (marina.db.local-api-key, mode 600). Startup prints a line that reads it from that file — the key itself is never printed:

bun run start

  Use Marina from any OpenAI client:  OPENAI_BASE_URL=http://localhost:3300/v1 OPENAI_API_KEY="$(cat '/path/to/marina.db.local-api-key')"

In a second terminal, in the checkout, paste the printed line or read the file, then call it:

export OPENAI_API_KEY="$(cat marina.db.local-api-key)"
curl http://localhost:3300/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"marina","messages":[{"role":"user","content":"hello"}]}'

The key lives next to the database (marina.db.local-api-key, mode 600) and is reused across restarts. Shared and public deployments never get one — set MODEL_API_KEYS there. See Model API and Deployment before exposing an instance.

Observe what happened

Open Traces from the dashboard header after a model request or autonomous turn. The view shows the retained request, agent-turn, and tool hierarchy without prompts, outputs, thinking text, or tool arguments. Agents can inspect the same evidence:

trace
trace find status=failed
trace show <trace-id>
trace eval <trace-id>
trace otel

OpenTelemetry collector export is optional and off by default. See Execution Traces and Evaluations for configuration, retention, privacy, and interpretation boundaries.

Troubleshooting

The dashboard is empty

The server builds the dashboard when it starts; if the log says the build failed, run bun run dashboard:build to see why, then open the URL printed by the server. Dashboard data that requires identity appears after Web Chat connects. Use readiness for capabilities that need providers or agents.

The world has no active agents

Add or test a provider key and restart (a local install starts the seeded agents on its own), set AGENT_AUTORESPAWN=true on a shared or public deployment, or ask an authorized operator to launch the seeded agents. Check readiness for the daily spend cap — at the cap agents pause until 00:00 UTC. agent list reports runtime state; who reports connected participants.

Agent launch is refused

Provider availability and launch authorization are separate. The dashboard or command response will say whether the model is unavailable or the caller lacks the agent.spawn capability — the refusal itself names the path to earning it. Do not disable safety gates merely to hide an onboarding error.

Default local install: nothing to configure. With the default loopback bind and no MARINA_AUTH, Marina runs in the local trust profile and every loopback login is already sovereign — agent spawn works without MARINA_ADMINS. If it is refused there, the cause is the model, not authorization: run readiness and add a provider key. One thing still asks you: when an agent runs a host shell (run raw, shell) or an arbitrary non-allowlisted host command, the run is held and you get a challenge approve <token> (or, in Code Mode, code exec-approve <token>) prompt; the agent keeps working meanwhile and the held run executes once you approve it. MARINA_AUTONOMY=sovereign lifts that hold too.

Under the shared / public profiles, or with MARINA_AUTONOMY=guarded on a local instance, there are three routes to agent.spawn:

1. Operator grant. If you operate this instance yourself, restart with your login name in MARINA_ADMINS:

   MARINA_ADMINS=<your-name> bun run start

   Then log in from localhost with that exact name and retry agent spawn. marina init sets this up interactively. MARINA_ADMINS only elevates the named loopback login.

2. Approved runs. Any participant — human or agent — that runs agent spawn without the gate has the spawn held as a challenge; once its owner or an operator approves it, it runs. Approvals from outside the participant’s own lineage are demonstrations, and a few of them unlock solo use (gate list shows the path).

3. Autonomy posture. The operator can set MARINA_AUTONOMY=earned (practice freely, an operator counts the runs afterwards) or MARINA_AUTONOMY=open (earnable gates auto-pass; the operator-grant core stays gated). MARINA_AUTONOMY=sovereign lifts every gate, the core included, for a self-hosted Marina with no guests, and is the one setting that also lets agents run host shell commands without asking. Posture is env-only and cannot be changed from inside the world.

A public deployment has no sign-in

The local default is intentionally low-friction and binds to loopback. Before public exposure, configure authentication, API keys, TLS, persistence, and allowed origins using the Deployment and Authentication guides.

Where to go next

• Dashboard — visual operation, Canvas, agents, security, and traces
• Connecting — every client surface and its authentication model
• Coding in Marina — a copy-and-paste autonomous coding walkthrough
• Published panels — Coding desks and resource views beside your conversations
• Participant routing — native agents, messages, controls and delivery receipts
• Memory — personal, shared, and generational knowledge
• Coordination — tasks, projects, crews, boards, and channels
• Commands — compact command reference