// guides · 03

Self-hosting and production

In dev the posture is friendly (won't break your machine). Before you expose the agent (Telegram, API, Paperclip), you turn on real isolation and run conformance in…

Open in full documentation GitHub

Docker

docker build -f deploy/Dockerfile -t okami-agent .
docker compose -f deploy/docker-compose.yml run --rm okami doctor
docker compose -f deploy/docker-compose.yml run --rm okami \
  task "create hello.txt" -e file_exists:hello.txt

For an LMStudio on the host machine, point api_base at http://host.docker.internal:PORT/v1 (in okami.local.yaml, not versioned).

Sandbox: dev → hardened

run_shell and background processes run under a sandbox policy. There are two backends, because the guarantee is genuinely different:

backend	guarantees
local	fences: cwd, sanitized env, timeout, output cap, optional rlimits (does NOT confine FS/network)
docker	real isolation: only the workspace mounted, --network none, non-root, --cap-drop ALL, read-only rootfs
auto	docker if present; otherwise falls back to local

okami.yaml

sandbox:
  profile: hardened          # dev | hardened | hardened-strict
  backend: docker            # local | docker | auto
  mode: workspace-write      # read-only | workspace-write | yolo
  network: false
  timeout: 60
  egress_allow: [api.github.com]   # outbound allowlist (filtering proxy)
  require_isolation: true    # exposed WITHOUT docker → run_shell DISABLED (doesn't degrade)

HTTP API

okami serve requires OKAMI_API_TOKEN (fail-closed) and binds 127.0.0.1 by default. --host 0.0.0.0 exposes it to the network — only with a token and, ideally, behind a TLS proxy.

okami config set OKAMI_API_TOKEN <token>
okami serve --host 0.0.0.0 --port 8765

Gateway as a service

By default okami gateway runs in the background, writes the PID/log to .okami/ and returns the terminal. For a real service, run --foreground under systemd/supervisor.

okami gateway              # background; --status / --stop
okami gateway --foreground # foreground (live logs) — run under systemd

GA checklist

okami policy check --strict passes (production posture; exposed without Docker FAILS).
OKAMI_API_TOKEN set; ingress via allow_chats (never allow_all).
sandbox.require_isolation: true (or profile: hardened-strict).
Secrets only in ~/.okami/.env (0600); nothing literal in versioned YAML.
okami doctor --lint with no failures; okami clean --deep scheduled in cron.

okami policy check --strict   # GA readiness gate
okami doctor --lint           # posture lint (pass/warn/fail)

Security & policyThe full security model.Variables & filesOKAMI_API_TOKEN, .env and .okami/.

Open this page in the interactive docs