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:latestis 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.jsturns 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/.opencontextvolume, 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:
| File | Written by |
|---|---|
preferences.json | UI / HTTP server, CLI convert |
preferences.md, memory.md | UI / HTTP server, CLI convert |
contexts.json | MCP server, HTTP server |
config.json | UI / 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.