open-context open-context
October 27, 2026 · 7 min read

One open-context Docker Image, Three Ways to Run It

The official open-context Docker image, adityakarnam/open-context:latest, can run as an HTTP server with the full web UI, as an MCP stdio server for Claude Code and Claude Desktop, or as a one-off CLI conversion job — all from the exact same build. Which mode it runs depends entirely on the command you pass to docker run, because the image bundles the compiled server, MCP server, and CLI together in one dist/ folder.

Key takeaways

  • adityakarnam/open-context:latest is one multi-stage build — open-context does not ship three separate images for its three run modes.
  • The default command, node dist/server.js, starts the Express HTTP server that serves the built React UI and REST API on port 3000.
  • Overriding the command to node dist/mcp/index.js turns the identical image into a stdio MCP server for Claude Code or Claude Desktop — no rebuild required.
  • Overriding the command to node dist/index.js convert <file> runs the Commander.js CLI as a single batch job instead of a long-running process.
  • All three modes read and write the same /root/.opencontext volume, so preferences and saved context created in one mode are visible in the others.

Why one image, not three

open-context's Dockerfile has three stages. ui-builder runs npm ci and npm run build against ui/ to produce a static React bundle. server-builder runs npm ci and tsc against src/ to compile the HTTP server, the CLI, and the MCP server into one dist/ folder. The final stage starts from a clean node:25-slim and copies in only the two build outputs — the compiled dist/ and the built UI — leaving every build tool, dev dependency, and source file behind.

That's the standard multi-stage pattern: use multiple FROM statements in one Dockerfile, and copy only the finished artifacts from earlier stages into a minimal final stage, so the toolchain used to build the image never ships inside it (Docker's multi-stage builds guide). Because all three of open-context's run modes come from that same dist/ folder, there's nothing mode-specific to rebuild — the only thing that changes between them is the command the container starts with.

Mode 1 — HTTP server (the default)

With no command override, the image runs its CMD, node dist/server.js: an Express server that serves the built React dashboard and exposes the full REST API on port 3000.

docker run -p 3000:3000 \
  -v opencontext-data:/root/.opencontext \
  adityakarnam/open-context:latest

Open http://localhost:3000 and you get the import pipeline, preferences editor, context viewer, and database settings — the same UI a local npm run dev stack serves. Configuration is all environment variables: PORT for the listen port, OLLAMA_HOST for where to reach Ollama (it defaults to host.docker.internal:11434 so it can reach Ollama running on your host machine), and OPENCONTEXT_DB_URL or OPENCONTEXT_STORE_PATH to point the context store at one of the 15 BYODB backends instead of the default JSON file.

Mode 2 — MCP stdio server for Claude

Override the command to node dist/mcp/index.js and the same image becomes a stdio MCP server instead of an HTTP server:

docker run -i --rm \
  -v opencontext-data:/root/.opencontext \
  adityakarnam/open-context:latest \
  node dist/mcp/index.js

The -i flag matters here specifically because MCP speaks over stdio, not a network port — it keeps the container's standard input open so a client can exchange protocol messages with the process inside it. docker-compose.yml ships a dedicated mcp service that sets stdin_open: true for the same reason. This is the mode Claude Code and Claude Desktop use when you register open-context as an MCP server, exposing the six context tools — save_context, recall_context, list_contexts, search_contexts, update_context, and delete_context — directly to the model.

Pointing Claude Code at it is a config entry, not a running container you manage yourself:

{
  "mcpServers": {
    "open-context": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-v", "opencontext-data:/root/.opencontext",
               "adityakarnam/open-context:latest", "node", "dist/mcp/index.js"]
    }
  }
}

Claude Code starts and stops the container itself, once per session, using exactly that command.

Mode 3 — a one-off CLI conversion

The same image also contains the opencontext CLI entry point, dist/index.js. Override the command again to run a single ChatGPT export conversion and exit, rather than starting a server at all:

docker run --rm \
  -v "$(pwd)/chatgpt-export.zip:/data/export.zip:ro" \
  -v "$(pwd)/output:/data/output" \
  adityakarnam/open-context:latest \
  node dist/index.js convert /data/export.zip -o /data/output

This mode doesn't need the opencontext-data volume used by the other two — it's a batch job, not a long-running process, so the container exits once the conversion finishes. Instead you bind-mount the input ZIP and an output directory so the generated preferences.md, memory.md, and conversations/ files land back on your host. Flags like --skip-preferences and --ollama-host work exactly as they do outside Docker.

Keeping the default image small

Most of open-context's 15 database backends are optional peer dependencies, and the Dockerfile accepts a DB_DRIVERS build argument so the default image installs none of them — it still works out of the box with the built-in JSON file, in-memory, SQLite, and Cloudflare D1 backends, since D1 talks to Cloudflare's API over plain HTTP. If you want the context store on Postgres, MongoDB, or another driver-backed database, bake the driver in at build time instead of pulling it in at runtime:

docker build --build-arg DB_DRIVERS="pg" -t opencontext .
docker build --build-arg DB_DRIVERS="mongodb redis" -t opencontext .

One volume, shared across all three modes

Because every mode is the same image mounting the same path, /root/.opencontext/ is the one place state actually lives, regardless of which command started the container:

FileWritten by
preferences.jsonUI / HTTP server, CLI convert
preferences.md, memory.mdUI / HTTP server, CLI convert
contexts.jsonMCP server, HTTP server
config.jsonUI / HTTP server (saved database connection string, 0600 permissions)

Mount the same named volume into the HTTP server container and the MCP server container — exactly what docker compose up app mcp does — and context Claude saves through MCP shows up in the dashboard, and preferences you edit in the dashboard are what Claude reads back, without copying anything between them.

Run the UI, the MCP server, or a one-off conversion — same image, same volume.

Get started with open-context →

FAQ

Do I need three different Docker images for open-context?

No. There is one image, adityakarnam/open-context:latest, built from a single multi-stage Dockerfile. Which mode it runs — HTTP server, MCP stdio server, or CLI converter — depends only on the command you pass to docker run, not on a different build.

Can I run the HTTP server and the MCP server from open-context at the same time?

Yes. The repo's docker-compose.yml defines an app service (HTTP server) and an mcp service (stdio MCP server) built from the same image, and both can mount the same opencontext-data volume so they share preferences and context.

Why does open-context's MCP mode need the -i flag on docker run?

MCP servers communicate over stdio rather than a network port. The -i flag keeps the container's standard input open so Claude Code or Claude Desktop can exchange MCP protocol messages with the process inside the container.

How do I add a database driver like Postgres without bloating the default open-context image?

Build with a DB_DRIVERS build argument, for example docker build --build-arg DB_DRIVERS="pg" -t opencontext . The default build installs no optional drivers, so the image stays small and still works with the built-in JSON, SQLite, in-memory, and Cloudflare D1 backends.

Does the CLI conversion mode need the same persistent volume as the server and MCP modes?

Only if you also want its output to land in the shared context store. A one-off conversion typically bind-mounts an input ZIP and an output directory directly, since the container exits once the conversion finishes.