Quick start

Install, configure, and connect cyrnel to your AI tools

Prerequisites

• Docker with Compose plugin

Download & run

mkdir cyrnel
cd cyrnel
curl -O https://raw.githubusercontent.com/actelos/cyrnel/main/docker-compose.yml
docker compose up

This pulls pre-built images from GitHub Container Registry and starts three services:

Service	Port	Purpose
API	9371	Core HTTP server
Web UI	9372	Dashboard for managing cyrnel
MCP	9373	MCP server for AI agent integration

First pull may take a minute. Subsequent starts are instant.

Configuration

Set environment variables by creating a .env file alongside docker-compose.yml:

CYRNEL_API_KEY=sk-your-key-here
CYRNEL_SECRETS_KEY=your-base64-32-byte-key

Key variables

Variable	Default	What it does
CYRNEL_API_KEY	(unauthenticated)	Bearer token required on every API request
CYRNEL_SECRETS_KEY	(required)	AES-256-GCM key for encrypting service secrets
CYRNEL_SECRETS_PREVIOUS_KEYS	(optional)	Comma-separated old keys for rotation fallback
CYRNEL_DB_URL	file:/data/cyrnel.db	Database connection (SQLite by default)
LOG_LEVEL	info	trace, debug, info, warn, error, fatal, silent

You must set CYRNEL_SECRETS_KEY before storing any service secrets. The shipped default is a block of zero bytes, equivalent to no encryption. Generate a real key:

openssl rand -base64 32

Full reference

All available variables are documented in the per-service example env files:

• API variables
• MCP variables
• Web variables

Using the MCP Server

The MCP server exposes cyrnel’s tools so your AI agent can discover services, inspect tool schemas, create and run processes, and read results.

Each agent below shows two connection methods:

• HTTP: point the agent at the Docker MCP server (localhost:9373)
• stdio: run the MCP server as a Docker child process

Claude Desktop

Open claude_desktop_config.json (Claude → Settings → Developer → Edit Config).

HTTP:

{
  "mcpServers": {
    "cyrnel": {
      "type": "url",
      "url": "http://localhost:9373"
    }
  }
}

For Docker Desktop on macOS/Windows, use host.docker.internal:

{
  "mcpServers": {
    "cyrnel": {
      "type": "url",
      "url": "http://host.docker.internal:9373"
    }
  }
}

stdio:

{
  "mcpServers": {
    "cyrnel": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT=stdio", "-e", "CYRNEL_API_URL=http://host.docker.internal:9371", "ghcr.io/actelos/cyrnel/mcp:latest"]
    }
  }
}

Claude Code

Add to ~/.claude/settings.json or .mcp.json in your project root.

HTTP:

{
  "mcpServers": {
    "cyrnel": {
      "type": "http",
      "url": "http://localhost:9373"
    }
  }
}

stdio:

{
  "mcpServers": {
    "cyrnel": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT=stdio", "-e", "CYRNEL_API_URL=http://host.docker.internal:9371", "ghcr.io/actelos/cyrnel/mcp:latest"]
    }
  }
}

Or use the CLI wizard:

claude mcp add cyrnel -- docker run -i --rm -e MCP_TRANSPORT=stdio -e CYRNEL_API_URL=http://host.docker.internal:9371 ghcr.io/actelos/cyrnel/mcp:latest

opencode

Add to your opencode.json.

HTTP (remote):

{
  "mcp": {
    "cyrnel": {
      "type": "remote",
      "url": "http://localhost:9373",
      "enabled": true
    }
  }
}

stdio (local):

{
  "mcp": {
    "cyrnel": {
      "type": "local",
      "command": ["docker", "run", "-i", "--rm", "-e", "MCP_TRANSPORT=stdio", "-e", "CYRNEL_API_URL=http://host.docker.internal:9371", "ghcr.io/actelos/cyrnel/mcp:latest"],
      "enabled": true
    }
  }
}

Cursor

HTTP: In Cursor settings (Cursor → Settings → Features → MCP Servers), add:

Name: cyrnel
Type: http
URL: http://localhost:9373

stdio: Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "cyrnel": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT=stdio", "-e", "CYRNEL_API_URL=http://host.docker.internal:9371", "ghcr.io/actelos/cyrnel/mcp:latest"]
    }
  }
}

VS Code

Add to your workspace .vscode/mcp.json.

HTTP:

{
  "servers": {
    "cyrnel": {
      "type": "http",
      "url": "http://localhost:9373"
    }
  }
}

Restart VS Code, tools appear in Copilot Chat.

stdio:

{
  "servers": {
    "cyrnel": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT=stdio", "-e", "CYRNEL_API_URL=http://host.docker.internal:9371", "ghcr.io/actelos/cyrnel/mcp:latest"]
    }
  }
}

Pi Agent

Pi uses a TypeScript extension system for MCP. Add the server config to your Pi extensions or config file.

HTTP:

{
  "mcpServers": {
    "cyrnel": {
      "type": "http",
      "url": "http://localhost:9373"
    }
  }
}

stdio:

{
  "mcpServers": {
    "cyrnel": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT=stdio", "-e", "CYRNEL_API_URL=http://host.docker.internal:9371", "ghcr.io/actelos/cyrnel/mcp:latest"]
    }
  }
}

openclaw

Configure directly via the CLI.

HTTP:

openclaw config set mcpServers.cyrnel.type http
openclaw config set mcpServers.cyrnel.url http://localhost:9373

stdio:

openclaw config set mcpServers.cyrnel.command docker
openclaw config set mcpServers.cyrnel.args '["run", "-i", "--rm", "-e", "MCP_TRANSPORT=stdio", "-e", "CYRNEL_API_URL=http://host.docker.internal:9371", "ghcr.io/actelos/cyrnel/mcp:latest"]'

Codex CLI

Add to ~/.codex/config.toml.

HTTP:

[mcp_servers.cyrnel]
url = "http://localhost:9373"

stdio:

[mcp_servers.cyrnel]
command = "docker"
args = ["run", "-i", "--rm", "-e", "MCP_TRANSPORT=stdio", "-e", "CYRNEL_API_URL=http://host.docker.internal:9371", "ghcr.io/actelos/cyrnel/mcp:latest"]

Or use the CLI:

codex mcp add cyrnel -- docker run -i --rm -e MCP_TRANSPORT=stdio -e CYRNEL_API_URL=http://host.docker.internal:9371 ghcr.io/actelos/cyrnel/mcp:latest

Windsurf

Windsurf stores MCP config at ~/.codeium/windsurf/mcp_config.json.

HTTP:

Windsurf uses serverUrl (not url) for remote HTTP servers.

{
  "mcpServers": {
    "cyrnel": {
      "serverUrl": "http://localhost:9373"
    }
  }
}

stdio:

{
  "mcpServers": {
    "cyrnel": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT=stdio", "-e", "CYRNEL_API_URL=http://host.docker.internal:9371", "ghcr.io/actelos/cyrnel/mcp:latest"]
    }
  }
}

Antigravity

Antigravity stores MCP config at ~/.gemini/config/mcp_config.json.

HTTP:

{
  "mcpServers": {
    "cyrnel": {
      "serverUrl": "http://localhost:9373"
    }
  }
}

stdio:

{
  "mcpServers": {
    "cyrnel": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT=stdio", "-e", "CYRNEL_API_URL=http://host.docker.internal:9371", "ghcr.io/actelos/cyrnel/mcp:latest"]
    }
  }
}

GitHub CLI

The gh CLI can connect to MCP servers via its MCP extension support.

HTTP:

{
  "mcpServers": {
    "cyrnel": {
      "type": "url",
      "url": "http://localhost:9373"
    }
  }
}

stdio:

{
  "mcpServers": {
    "cyrnel": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT=stdio", "-e", "CYRNEL_API_URL=http://host.docker.internal:9371", "ghcr.io/actelos/cyrnel/mcp:latest"]
    }
  }
}

Gemini CLI

Add to ~/.gemini/settings.json.

HTTP:

{
  "mcpServers": {
    "cyrnel": {
      "url": "http://localhost:9373"
    }
  }
}

stdio:

{
  "mcpServers": {
    "cyrnel": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT=stdio", "-e", "CYRNEL_API_URL=http://host.docker.internal:9371", "ghcr.io/actelos/cyrnel/mcp:latest"]
    }
  }
}

Verify with /mcp list after restarting Gemini CLI.

The MCP server requires the API to be running and reachable. In the Docker setup this is handled automatically, the MCP container connects to the API container over the internal Docker network.