Install COGO

COGO is one container (or one binary). The only two things that matter: mount a volume at /vault so your notes survive updates, and — on a server — set a token.

The golden security rule

On a server, COGO refuses to start without a token (so nobody walks into your vault). Generate a long one and keep it — we’ll call it YOUR-TOKEN:

openssl rand -hex 32

COGO_ALLOW_INSECURE=1 exists for local, loopback-only runs — never use it on a server.

On your machine (local, 2 minutes)

With Docker Desktop installed:

docker run -d --name cogo -p 127.0.0.1:8095:8080 \
  -v cogo-vault:/vault -e COGO_ALLOW_INSECURE=1 \
  ghcr.io/diegoparras/cogo

Open http://localhost:8095. Done — you see your vault painted by confidence, capture and edit notes, all from the browser.

• -p 127.0.0.1:8095:8080 publishes it only on your machine — nobody on your network sees it.
• -v cogo-vault:/vault keeps your notes in a volume so they are not deleted.
• -e COGO_ALLOW_INSECURE=1 means “I know it’s local, don’t ask for a token”. Local only.

Without Docker — a single static binary, no runtime:

cogo serve -http 127.0.0.1:8080 -vault ./vault

On a server with EasyPanel (recommended)

EasyPanel doesn’t get along with docker-compose — don’t use the “Compose” type. Use the App type, which is simpler and adds HTTPS on its own.

1. In your EasyPanel project, + Add Service → App, name it cogo.
2. Source — either GitHub (repo diegoparras/cogo, branch main, Build = Dockerfile; always works), or Docker Image ghcr.io/diegoparras/cogo:latest (requires the package to be public).
3. Environment:

   COGO_MCP_TOKEN=YOUR-TOKEN
   COOKIE_SECURE=1

   (COGO_VAULT=/vault is already the default.)
4. Mounts → Add Mount — type Volume, name cogo-vault, mount path /vault. Skip this and every update wipes your notes.
5. Domains → Add Domain — your domain, port 8080 (COGO’s internal port). EasyPanel issues the HTTPS certificate itself. Health check path, if asked: /healthz.
6. Deploy, open your domain, and paste YOUR-TOKEN when the viewer asks for it.

If the app crashes on start, you forgot COGO_MCP_TOKEN — COGO refuses, on purpose, to sit on the internet unprotected.

On a VPS by hand

The safest shape (bank grade): don’t expose the port at all — bind it to loopback and reach it through a tunnel.

# on the VPS:
docker run -d --name cogo -p 127.0.0.1:8080:8080 \
  -v cogo-vault:/vault -e COGO_MCP_TOKEN=YOUR-TOKEN \
  ghcr.io/diegoparras/cogo

# on your machine (SSH tunnel):
ssh -N -L 8080:127.0.0.1:8080 user@your-vps

Open http://localhost:8080. The hardened-deployment detail (tunnel/VPN, TLS via proxy, limits) is in docs/seguridad.md.

Connect Claude Code (MCP)

Local — the simplest: no network, each session starts its own COGO. In a .mcp.json:

{ "mcpServers": { "cogo": { "command": "cogo", "args": ["serve", "-vault", "./vault"] } } }

Remote — over HTTP, with your token in the header:

{
  "mcpServers": {
    "cogo": {
      "type": "http",
      "url": "https://your-domain/mcp",
      "headers": { "Authorization": "Bearer YOUR-TOKEN" }
    }
  }
}

From there, in any session you ask for pack "<topic>" and get colored context, or capture a finding. What Claude learns today, Cursor reads tomorrow: the same vault.

Updating

• EasyPanel: hit Deploy (or Rebuild) again. Your notes stay, thanks to the /vault volume.
• Plain Docker: docker pull ghcr.io/diegoparras/cogo and recreate the container with the same -v cogo-vault:/vault.

Optional: an AI model

COGO works perfectly without a model. If you want it to detect contradictions between notes and sharpen the Guard, open the viewer → menu → Settings · AI model and connect a local (Ollama) or remote (OpenRouter, DeepSeek) model. Token spend shows in the same menu.

Read the documentation