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.

Other optional accessories

All of these are off unless you set them. COGO’s core never reaches the network.

Variable	What it turns on
COGO_GITHUB_TOKEN	Evidence that lives in a repo (github://owner/repo@main/file.go:42, pinned to the blob SHA) and the built-in GitHub explorer. A read-only token is enough.
COGO_R2_*	Store artifacts on Cloudflare R2 instead of local disk (ACCOUNT_ID, ACCESS_KEY_ID, SECRET_ACCESS_KEY, BUCKET).
COGO_AUDIT_MAX	How many entries the MCP audit log keeps (5000 by default, 0 = unlimited).

Verify what you’re running

Every image is signed with cosign (keyless Sigstore) and ships SLSA build provenance, so you can prove it came out of this repository’s CI before trusting it with your vault:

cosign verify ghcr.io/diegoparras/cogo \
  --certificate-identity-regexp='https://github.com/diegoparras/cogo/.*' \
  --certificate-oidc-issuer=https://token.actions.githubusercontent.com

Read the documentation