Docker install

The official image ships from GitHub Container Registry with a pre-baked embedding model, Sigstore keyless signatures, SLSA provenance, and a CycloneDX SBOM. No first-run download. No account required.

Pull and run

docker run -d \\
  --name okto-pulse \\
  -p 127.0.0.1:8100:8100 \\
  -p 127.0.0.1:8101:8101 \\
  -e HOST=0.0.0.0 \\
  -e MCP_HOST=0.0.0.0 \\
  -e DATA_DIR=/data \\
  -e KG_BASE_DIR=/data \\
  -v okto-pulse-data:/data \\
  ghcr.io/oktolabsai/okto-pulse:latest

Open http://localhost:8100 once the container starts. The board is ready.

Why `MCP_HOST=0.0.0.0` is required

Without MCP_HOST=0.0.0.0, the MCP server binds to 127.0.0.1 inside the container — a loopback address unreachable from your host even with -p 8101:8101 published. Your agent will time out trying to connect.Always set MCP_HOST=0.0.0.0 when running in Docker. The published port binding (127.0.0.1:8101:8101) ensures the MCP port is visible only to your machine, not your LAN — so setting 0.0.0.0 inside the container is safe.

The same applies to HOST=0.0.0.0 for the web board and API on port 8100.

Connect your agent

After the container starts, generate .mcp.json and copy it to your project directory:

docker exec okto-pulse okto-pulse init --agents
docker cp okto-pulse:/app/.mcp.json ./.mcp.json

Add .mcp.json to .gitignore — it contains a scoped agent API key. To generate config for one agent only (Claude Code, for example):

docker exec okto-pulse okto-pulse init --agents claude
docker cp okto-pulse:/app/.mcp.json ./.mcp.json

Get the API key directly if you need it for manual MCP client config:

docker exec okto-pulse okto-pulse api-key

Environment variables

Variable	Container default	Purpose
`HOST`	`0.0.0.0`	API + UI uvicorn bind host. Must be `0.0.0.0` inside a container.
`MCP_HOST`	`0.0.0.0`	MCP uvicorn bind host. Must be `0.0.0.0` inside a container.
`DATA_DIR`	`/data`	Root for the SQLite database and uploads. Mount a volume here.
`KG_BASE_DIR`	`/data`	Root for per-board knowledge graphs. Set to the same path as `DATA_DIR`.
`HF_HOME`	`/opt/hf-cache`	Sentence-transformers cache. Pre-warmed at build time — do not mount over this path.
`MCP_TRACE_ENABLED`	unset	Set to `1` to record every MCP tool call to `${MCP_TRACE_DIR}/session_*.jsonl`.
`MCP_TRACE_DIR`	`/data/mcp_traces`	Trace output directory when `MCP_TRACE_ENABLED=1`.

Data persistence

The container writes all state to /data:

/data/
  data/pulse.db            SQLite database (boards, specs, cards, decisions)
  boards/{id}/graph.lbug   per-board knowledge graph
  uploads/                 card file attachments
  global/discovery.lbug    cross-board discovery index
  mcp_traces/              MCP call traces (when MCP_TRACE_ENABLED=1)

Use a named volume (survives container replacement):

docker volume create okto-pulse-data
docker run -d \\
  --name okto-pulse \\
  -p 127.0.0.1:8100:8100 \\
  -p 127.0.0.1:8101:8101 \\
  -e HOST=0.0.0.0 \\
  -e MCP_HOST=0.0.0.0 \\
  -e DATA_DIR=/data \\
  -e KG_BASE_DIR=/data \\
  -v okto-pulse-data:/data \\
  ghcr.io/oktolabsai/okto-pulse:latest

Or a host path (easier to inspect and back up):

docker run -d \\
  --name okto-pulse \\
  -p 127.0.0.1:8100:8100 \\
  -p 127.0.0.1:8101:8101 \\
  -e HOST=0.0.0.0 \\
  -e MCP_HOST=0.0.0.0 \\
  -e DATA_DIR=/data \\
  -e KG_BASE_DIR=/data \\
  -v /your/host/path:/data \\
  ghcr.io/oktolabsai/okto-pulse:latest

Do not mount over /opt/hf-cache. The embedding model is pre-baked into the image and the container starts offline-capable. Mounting over it forces a re-download.

Docker Compose

Two compose files ship with the okto-pulse repo.

Pinned release (recommended)

docker-compose.prod.yml installs a pinned version from PyPI. Clone only the okto-pulse repo — no sibling repo needed.

git clone https://github.com/OktoLabsAI/okto-pulse
cd okto-pulse
docker compose -f docker-compose.prod.yml build
docker compose -f docker-compose.prod.yml up -d
docker compose -f docker-compose.prod.yml logs -f

Export .mcp.json after first boot:

docker compose -f docker-compose.prod.yml exec okto-pulse okto-pulse init --agents
docker compose -f docker-compose.prod.yml cp okto-pulse:/app/.mcp.json ./.mcp.json

Build from source

docker-compose.yml builds wheels from local source. Use this when modifying okto-pulse-core or okto-pulse. Both repos must be cloned as siblings:

OktoLabsAI/
  okto-pulse/
  okto-pulse-core/

cd okto-pulse
docker compose build
docker compose up -d
docker compose logs -f

Export .mcp.json:

docker compose exec okto-pulse okto-pulse init --agents
docker compose cp okto-pulse:/app/.mcp.json ./.mcp.json

LAN access

Both compose files bind to 127.0.0.1 by default — the container is reachable from your machine only. To allow LAN access, change the ports mapping in the compose file:

ports:
  - "0.0.0.0:8100:8100"
  - "0.0.0.0:8101:8101"

Put the host behind a reverse proxy with authentication before exposing to a LAN. The MCP API key is the only auth layer Pulse provides.

Updating

docker pull ghcr.io/oktolabsai/okto-pulse:latest
docker stop okto-pulse && docker rm okto-pulse
# re-run the same docker run command — the named volume persists

With compose:

docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d

Verify

docker exec okto-pulse okto-pulse status
curl -s http://localhost:8100/api/v1/kg/settings

Get started

Concepts

Configuration

Reference

Permissions & Agents

Guides

KG Operations

Operations

Help

Docker

Docker install

Pull and run

Why `MCP_HOST=0.0.0.0` is required

Connect your agent

Environment variables

Data persistence

Docker Compose

Pinned release (recommended)

Build from source

LAN access

Updating

Verify

Next steps

Connect your agent

First workflow

​Docker install

​Pull and run

​Why MCP_HOST=0.0.0.0 is required

​Connect your agent

​Environment variables

​Data persistence

​Docker Compose

​Pinned release (recommended)

​Build from source

​LAN access

​Updating

​Verify

​Next steps

Connect your agent

First workflow

Docker install

Pull and run

Why `MCP_HOST=0.0.0.0` is required

Connect your agent

Environment variables

Data persistence

Docker Compose

Pinned release (recommended)

Build from source

LAN access

Updating

Verify

Next steps