Quickstart

$ quickstart · 3 min read

This is the operator path — installing and running capsol for yourself or your team. It walks you from nothing to a working setup: capsol running, one capsule created, and an AI agent (like Claude or Cursor) connected and reading it.

Just want to use a capsule someone else runs? You don’t need to install anything — skip to Connect a client.

A capsule is just a shared box of context that your agents read and write. Let’s make one.

1. Start capsol

The fastest way is Docker. Run this in a terminal:

docker run -p 4000:8080 ghcr.io/arcadeai-labs/capsol-v2:latest

Prefer to run it from source instead?

git clone https://github.com/arcadeai-labs/capsol-v2.git
cd capsol-v2
npm ci
npm run build
CAPSOL_SECRET_KEY="$(openssl rand -hex 32)" PORT=4000 npm start

Either way, capsol is now running locally.

2. Get your admin key

The first run prints an admin key to the terminal and saves a copy to ~/.capsol/admin.key. You’ll paste it into the dashboard to unlock it.

If you scrolled past it, read it back any time:

cat ~/.capsol/admin.key

Keep this key private — it unlocks the dashboard.

3. Open the dashboard

Visit http://localhost:4000 ↗ in your browser, then paste the admin key to sign in. This is your home base for creating capsules and approving who can connect.

4. Create a capsule

Click Create capsule, give it a name and an optional description, and open it. That’s it — you now have a capsule with its own stable URL.

You can leave it empty for now, or add a first entry to give your agent something to read.

5. Add an entry (optional)

Inside the capsule, add an entry under one of the built-in schemes — these are just labelled drawers for different kinds of content:

• docs:// — reference docs
• guidance:// — patterns and conventions
• notes:// — notes and findings
• config:// — config references
• api-data:// — JSON schemas and data
• skills:// — reusable prompts

For example, create docs://welcome with a sentence or two. Your agent will be able to read it in the next step.

6. Connect an agent

Every capsule has one MCP URL — a stable address you paste into an AI client:

http://localhost:4000/mcp/<capsule-id>

Copy it from the capsule page, then paste it into any MCP-capable client — Claude Code, Claude Desktop, Cursor, Zed, VS Code Copilot, Codex, Windsurf, or ChatGPT (Pro and above).

The client handles sign-in automatically: it discovers the server, registers itself, and asks the person to sign in. No credentials ever go in the URL — the URL is just an address, and the access token travels safely in the background.

7. Approve the connection

Back in the dashboard, you’ll see a pending access request. Approve it. This human-in-the-loop step is deliberate: nothing connects to your capsule until a person says yes.

8. Watch the agent read it

Ask your agent to look at the capsule — for example, “read the welcome doc” or “list what’s in this capsule.” It will pull the entry you added (or report that the capsule is empty) and stay in sync from here on. Anything any connected agent writes, every other agent sees.

You’re done. One capsule, one URL, an agent connected and reading.

Where next

• Concepts — the mental model: capsules, schemes, tools, and sharing.
• Dashboard — your day-to-day controls.
• Connect a client — exact setup for each client.
• Connect your agents — putting capsules to work in real agent workflows.
• Deploy — run capsol beyond your laptop.