Deployment
Openheim ships as a single binary with four subcommands. This guide covers running the server mode (openheim serve) in home-cloud and enterprise environments.
Subcommands
| Subcommand | Description |
|---|---|
openheim |
Interactive TUI (no subcommand) |
openheim acp |
ACP agent over stdin/stdout — for IDE extensions (Zed, Claude Code, etc.) |
openheim run "<prompt>" |
One-shot headless prompt, output to stdout |
openheim serve |
WebSocket + REST server |
openheim init |
Create a default ~/.openheim/config.toml |
~/.openheim is .openheim in the home directory of the user running openheim ($HOME; the user profile folder on Windows). Every subcommand takes --config <FILE> to use another config file; see Config and data locations.
Server mode is the primary deployment target for hosted and enterprise use.
Interactive TUI
Running openheim with no subcommand opens the interactive terminal UI. Type a message and press Enter to chat. Type :help to see all commands.
| Command | Description |
|---|---|
:help |
Show all commands |
:q / :quit |
Exit |
:new |
Start a new session (keeps the current model, mode and effort level) |
:sessions |
Browse and restore saved sessions (interactive picker) |
:config |
Show current configuration |
:models |
Open model picker (arrow keys + Enter to switch mid-session) |
:models <name> |
Switch to a model directly without opening the picker |
:mode |
Show the session's mode |
:mode <name> |
Switch mode: code (every tool) or architect (read-only tools) |
:effort |
Show the session's effort level |
:effort <level> |
Set the effort level: default (the provider's own default), low, medium or high. Kept through model switches. |
:mcp |
Show MCP server statuses |
:skills |
List available skills |
:theme |
Open theme color picker |
:theme <name> |
Apply a theme color directly and save it to config.toml |
Keyboard shortcuts: ↑/↓ scroll · PgUp/PgDn page · Ctrl+C cancel the running turn · Ctrl+C twice (within two seconds) quit · Esc close any overlay. Pasted text keeps its line breaks (shown as ↵ in the input bar) and is sent only when you press Enter.
Theme colors: white, gray, blue, cyan, magenta, green, yellow, red, pink
The selected theme is persisted to the config file in use (~/.openheim/config.toml, or the --config file) as theme_color under [tui].
Running the server
# Default: binds 0.0.0.0:1217
openheim serve
# Custom host/port
openheim serve --host 127.0.0.1 --port 8080
The server exposes:
ws://{host}:{port}/ws— WebSocket endpoint (ACP agent + filesystem sidecar)http://{host}:{port}/api/*— REST endpoints (config, models, skills, tools, mcp-servers, sessions)
The filesystem sidecar is sandboxed to the configured work_dir (see Configuration) — connected clients cannot read or write outside it.
Config and data locations
An openheim process uses two locations:
-
The config file,
~/.openheim/config.tomlby default.--config <FILE>names another one. -
The data directory, which holds everything openheim writes:
Path Contents system.mdThe agent's identity skills/Skills agents/Subagent profiles history/Saved conversations memory.dbLong-term memory, unless [memory].db_pathis setopenheim.logThe TUI's log It's the directory the config file's
data_dirkey names, or, without that key, the config file's own directory:~/.openheimby default, or wherever the--configfile is.
--config works with every subcommand, before or after it (openheim --config FILE run "…" and openheim run --config FILE "…" are the same). A relative path is taken from the directory openheim is started in. openheim doesn't expand ~ itself; write --config ~/agents/coder.toml with a space so your shell expands it, or use an absolute path.
openheim init writes the default config file and a system.md next to it, creating the directory if needed. Every other subcommand fails if the config file is missing; with --config, the error names the init command to run. If you then set data_dir, move system.md there, since that's where it's read from. :theme in the TUI saves to the config file in use.
Running several agents
Give each agent its own config file. Without a data_dir key, each agent's data lives next to its config, so agents in separate directories share nothing:
openheim --config ~/agents/coder/config.toml init
openheim --config ~/agents/research/config.toml init
# edit both config files
# Run both at once
openheim --config ~/agents/coder/config.toml
openheim --config ~/agents/research/config.toml serve --port 1218
To keep an agent's data apart from its config, for example a read-only config in /etc and data under /var/lib, set data_dir in the config:
# /etc/openheim/coder.toml
data_dir = "/var/lib/openheim/coder"
openheim --config /etc/openheim/coder.toml serve
Some settings are not tied to the config or data location, so check them when two agents run side by side:
- Ports.
openheim servebinds port 1217 by default. Give each server its own--port. [memory].db_path. An absolute path puts the memory database there instead of the data directory. Two configs with the samedb_pathshare one memory. Leave it unset to keep each agent's memory separate.work_dir. It's the directory the agent's tools may read and write, not where its data lives, and it defaults to the directory openheim was started in. Two agents started in the same directory work on the same files, and nothing coordinates their edits. Setwork_dirin each config to keep them apart.- Environment variables. Provider keys read from the environment (
ANTHROPIC_API_KEY,env_var = "…") andRUST_LOGcome from each process's own environment, so set them per process to give agents different keys.
Give each agent its own data directory too. Two agents whose config files sit in the same directory (and set no data_dir), or whose configs set the same data_dir, share one data directory.
Configuration
Openheim reads ~/.openheim/config.toml at startup, or the file --config names. In server deployments, place the config at the path the process user can read. See Configuration for the full reference.
API keys via environment variables
Provider API keys can be supplied as environment variables instead of being stored in the config file:
| Environment variable | Provider |
|---|---|
ANTHROPIC_API_KEY |
Anthropic |
OPENAI_API_KEY |
OpenAI |
GEMINI_API_KEY |
Google Gemini |
Any provider block in config.toml with env_var = "MY_VAR" reads from that variable at startup. This is the recommended approach for production — store secrets in your secret manager and inject them at runtime.
[providers.anthropic]
api_base = "https://api.anthropic.com/v1"
default_model = "claude-sonnet-4-6"
models = ["claude-sonnet-4-6", "claude-opus-4-7"]
env_var = "ANTHROPIC_API_KEY"
Logging
Openheim uses tracing with RUST_LOG for log level control:
RUST_LOG=info openheim serve
RUST_LOG=openheim=debug openheim serve # debug only openheim internals
Logs go to stderr, except in the TUI: once it's on screen, they're appended to openheim.log in the data directory (~/.openheim by default; see Config and data locations) instead.
Docker
The repo ships a multi-stage Dockerfile and a docker-compose.yml. The image runs as a non-root openheim user, and docker-entrypoint.sh generates a default config (openheim init) on first start if no config volume is mounted.
# Build and start with docker compose
docker compose up --build
# Or run manually
docker build -t openheim .
docker run -p 1217:1217 \
-e OPENAI_API_KEY=sk-your-key \
-v openheim-data:/home/openheim/.openheim \
openheim serve
Dockerfile (as shipped)
FROM rust:1.92-slim-bookworm AS builder
WORKDIR /workspace
RUN apt-get update && apt-get install -y pkg-config libssl-dev \
&& rm -rf /var/lib/apt/lists/*
COPY Cargo.toml Cargo.lock* ./
COPY src ./src
RUN cargo build --release
FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y ca-certificates libssl3 curl \
&& rm -rf /var/lib/apt/lists/*
COPY --from=builder /workspace/target/release/openheim /usr/local/bin/openheim
COPY docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
RUN chmod +x /usr/local/bin/docker-entrypoint.sh \
&& useradd -m -u 1000 openheim
USER openheim
EXPOSE 1217
ENTRYPOINT ["docker-entrypoint.sh"]
CMD ["openheim", "serve"]
docker-compose.yml (as shipped)
services:
openheim:
build: .
container_name: openheim-agent
ports:
- "1217:1217"
environment:
- RUST_LOG=info
# API keys are read from config.toml, but can also be set here
# and referenced via env_var in your config
- OPENAI_API_KEY=${OPENAI_API_KEY:-}
- ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY:-}
restart: unless-stopped
volumes:
# Config directory — mount your own config.toml here;
# a default config is generated on first run if not provided
- openheim-config:/home/openheim/.openheim
# Persistent workspace directory
- openheim-workspace:/workspace
volumes:
openheim-config:
driver: local
openheim-workspace:
driver: local
# Start
ANTHROPIC_API_KEY=sk-ant-... docker compose up -d
# View logs
docker compose logs -f openheim
systemd
Create /etc/systemd/system/openheim.service:
[Unit]
Description=Openheim LLM agent server
After=network.target
Wants=network-online.target
[Service]
Type=simple
User=openheim
Group=openheim
ExecStart=/usr/local/bin/openheim serve --host 127.0.0.1 --port 1217
Restart=on-failure
RestartSec=5s
# Secrets — set these in /etc/openheim/env or use a secret manager
EnvironmentFile=/etc/openheim/env
# Harden the process
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ReadWritePaths=/home/openheim/.openheim
[Install]
WantedBy=multi-user.target
/etc/openheim/env:
ANTHROPIC_API_KEY=sk-ant-...
RUST_LOG=warn
# Create the service user
useradd --system --home /home/openheim --create-home openheim
# Copy config
mkdir -p /home/openheim/.openheim
cp config.toml /home/openheim/.openheim/
chown -R openheim:openheim /home/openheim/.openheim
# Enable and start
systemctl daemon-reload
systemctl enable openheim
systemctl start openheim
systemctl status openheim
The service runs as the openheim user, so ~/.openheim is that user's /home/openheim/.openheim, not root's or yours. To keep the config in /etc and the data in /var/lib instead, set data_dir = "/var/lib/openheim" in /etc/openheim/config.toml, add --config /etc/openheim/config.toml to ExecStart, and set ReadWritePaths=/var/lib/openheim.
Reverse proxy
The WebSocket endpoint requires a proxy that supports connection upgrades. Both nginx and Caddy handle this without extra plugins.
nginx
server {
listen 443 ssl;
server_name openheim.example.com;
ssl_certificate /etc/letsencrypt/live/openheim.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/openheim.example.com/privkey.pem;
location / {
proxy_pass http://127.0.0.1:1217;
proxy_http_version 1.1;
# WebSocket upgrade headers
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# Keep long-running agent sessions alive
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
}
}
Caddy
openheim.example.com {
reverse_proxy localhost:1217
}
Caddy handles TLS and WebSocket upgrades automatically.
Enterprise considerations
Authentication
Openheim does not implement authentication itself. Add it at the reverse proxy layer:
- Basic auth (simple deployments): nginx
auth_basicdirective - OAuth2 / OIDC: oauth2-proxy in front of nginx/Caddy
- mTLS: configure client certificate verification in your proxy for service-to-service use
Network isolation
For environments where the agent should not reach arbitrary external hosts:
- Run in a network namespace or Docker network with explicit egress rules
- Allow only the LLM provider API endpoints and any MCP server URLs
- The agent calls outbound to: the configured LLM provider API, and any MCP server URLs defined in config
Multi-tenancy
Openheim is designed as a single-user or small-team server. For multi-tenant deployments, run a separate instance per tenant (separate config, history directory, and API key) behind a routing layer. Sharing a single instance across tenants is not supported — conversation history and skills are not access-controlled at the application level.
Data residency
Conversation history is written to history/ in the data directory (~/.openheim/history/ by default; see Config and data locations) as a pair of files per conversation: {uuid}.json (metadata, rewritten wholesale on each change) and {uuid}.jsonl (messages, appended one per line as the conversation grows). Back up the whole directory, not just *.json — the message content lives in the .jsonl files. For enterprises with strict data residency requirements, use a provider endpoint that runs in your region (Anthropic Bedrock, Azure OpenAI, self-hosted Ollama, etc.) and point openheim at it via an openai_compatible provider entry.