Self-improving AI Employees for everyone
Docker (self-hosting)
One container runs the whole app. uvicorn serves the API, the WebSocket and the built UI on one port, and the backend spawns the Temporal dev server, the bun code sidecar and plugin daemons itself when it needs them. There is no Redis; the cache falls back to SQLite.
This Compose recipe is a single-machine installation. Multi-machine Browser AI Agent deployment requires shared PostgreSQL, external Temporal, shared storage and stable browser-owner routing; adding replicas to this local recipe does not supply those prerequisites. Follow Browser deployment and offline migration before scaling it. Approved 1Password credentials also require a verified CLI and authorization available to the actual container backend. Desktop authorization from an unrelated host terminal is insufficient.
| File | Role |
|---|---|
docker/Dockerfile |
Two stages. The build stage runs the canonical build, the same two commands CI runs (bun install --frozen-lockfile, then bun run build). The runtime stage keeps only what the backend reads at run time, and optional tools come back through the EXTRAS build argument. |
docker/entrypoint.sh |
Writes the server secrets on first start, then runs uvicorn directly, the way the desktop shell does. |
docker-compose.yml |
One service, one named volume, the port published on this machine only. |
Quick start
From the repository root:
docker compose up -d --build
Open http://localhost:5678. The app requires a login: the first account you register becomes the owner, and registration closes after that. To create the owner at first start instead, uncomment OPENCOMPANY_OWNER_EMAIL and OPENCOMPANY_OWNER_PASSWORD in docker-compose.yml. The password needs at least 8 characters; a shorter one is only logged as an error, and the app then waits for you to register in the browser. The seed runs only while no account exists, so changing these values later does not change the owner's password. The port is published on 127.0.0.1 only; see Serving other machines to open it up.
docker compose ps reports the container as healthy once /health/ready answers, meaning the database is up and the Temporal workers have started. docker compose logs -f follows the backend log.
Optional tools (EXTRAS)
The default image has no browser, git or uv. Add them through the EXTRAS build argument in docker-compose.yml (for example EXTRAS: "browser git"), then run docker compose up -d --build.
| Extra | Installs | Needed by |
|---|---|---|
browser |
Chromium, fonts, Xvfb, uv | The current Browser node needs uv to install its pinned browser-use CLI; Chromium can be selected explicitly as described below |
git |
git | The Claude Code and Codex agent nodes, which work in git worktrees |
Without the browser extra, the runtime image has no uv for the Browser node's tool installer or system Chromium and its libraries. The default BROWSER_RUNTIME=system needs an installed Chrome/Edge/Chromium executable and never falls back to a download. Use BROWSER_RUNTIME=testing only when pinned Chrome for Testing is intended. Without the git extra, Claude Code and Codex tasks can fail with working_directory_not_git_repo.
The current runtime is documented in browser.md, with live viewing and control in browser_workspace.md. browserHarness is retired; browser-use is a dependency of the single browser node, not a second workflow node.
Where state lives
Everything the app keeps is in the opencompany-selfhost_data volume, mounted at /data. The compose project is named opencompany-selfhost so it never mixes with another compose project called opencompany.
| Path | Contents |
|---|---|
opencompany.env |
The secrets generated on first start, plus any settings you add |
workflow.db, credentials.db, temporal.db |
App data, encrypted credentials, Temporal history |
packages/ |
The Temporal CLI and the tools plugins install on first use |
workspaces/ |
Per-workflow files |
claude/, whatsapp/ |
Claude Code login, WhatsApp session |
home/ |
$HOME: gh, stripe, cf and codex logins, bun and uv caches |
opencompany.env holds API_KEY_ENCRYPTION_KEY, the key that decrypts credentials.db. Back the two up together and keep the file private. If the key changes, stored credentials can no longer be decrypted.
An image that pins a new Temporal server minor (server/config/temporal_cli.json) deletes temporal.db and the old CLI on its first start. Every deployment then shows Failed, and its owner resets and starts it (see TEMPORAL_ARCHITECTURE.md).
Back up /data while the container is stopped. temporal.db runs in SQLite's WAL mode, so recent commits live in a -wal file next to it until SQLite folds them back in: a copy taken while the app runs needs the -wal and -shm files too, and a -wal file must never be deleted. SQLite needs working file locks, so keep /data on the named volume or a local disk, never NFS or SMB.
Configuration
Settings resolve in this order, the later one winning: .env.template (baked into the image), then /data/opencompany.env, then the container environment (environment: in docker-compose.yml). To change a setting, add a KEY=value line to /data/opencompany.env or an entry under environment:, then restart the container.
A secret you pass under environment: before the first start is written into /data/opencompany.env instead of a random one, so removing it from docker-compose.yml later changes nothing.
The image sets these on top of the template:
| Variable | Value | Why |
|---|---|---|
DATA_DIR |
/data |
All state on the volume |
OPENCOMPANY_ENV_FILE |
/data/opencompany.env |
Secrets and your settings on the volume |
HOME |
/data/home |
CLI logins and caches survive upgrades |
DEPLOYMENT_MODE |
self_hosted |
Server posture: full Temporal concurrency, API docs not public |
VITE_AUTH_ENABLED |
true |
Login required |
NODEJS_EXECUTOR_HOST |
127.0.0.1 |
The code sidecar binds IPv4 loopback, which exists even where container IPv6 is off |
NODEJS_USER_PACKAGES_DIR |
/data/nodejs-user-packages |
Packages installed for code nodes persist |
BROWSER_RUNTIME |
system |
Use the image's installed browser; no testing-browser fallback |
BROWSER_FAMILY |
chromium |
Discover Chromium supplied by the browser extra through PATH |
BROWSER_HEADLESS |
true |
Render inside the workspace without a desktop window |
PYTHONUNBUFFERED |
1 |
Log lines reach docker compose logs as they are written |
Browser runtime configuration: the Dockerfile sets BROWSER_RUNTIME=system, BROWSER_FAMILY=chromium and BROWSER_HEADLESS=true in every image, not only with the browser extra; without that extra there is no Chromium, so a Browser node fails clearly instead of downloading one. These are the image defaults; compose environment: can override them. The headless image setting matches the application default: render in the workspace without a desktop window. Chromium is resolved through PATH at startup; the image does not pin an executable path. The former AGENT_BROWSER_EXECUTABLE_PATH has been removed from the Dockerfile and is not read by this runtime. BROWSER_RUNTIME=testing is the only mode that downloads pinned Chrome for Testing; it is never a missing-browser fallback. Validate the built image and Linux libraries before deployment.
The image has no Node. It links /usr/local/bin/node to bun, so the plugin CLIs whose entry scripts start #!/usr/bin/env node (vercel, cf) run on bun, as in the official oven/bun images. Browser automation installs browser-use through uv instead.
With the browser extra: Chrome refuses to run as root with its sandbox on, so the image adds --no-sandbox through a drop-in, /etc/chromium.d/no-sandbox. Debian's launcher reads flags only from that directory and ignores a CHROMIUM_FLAGS environment variable. Debian's own dev-shm drop-in already adds --disable-dev-shm-usage when Docker's /dev/shm is small.
Those drop-ins apply to Debian's Chromium launcher. OpenCompany supplies its runtime launch flags and detects sandbox/shared-memory constraints. The image already sets BROWSER_HEADLESS=true for displayless operation; do not rely on the former agent-browser/Xvfb startup path.
Leave HOST and PORT at their template values. The backend uses HOST to reach itself; the published bind comes from the entrypoint's --host 0.0.0.0. PORT is repeated in the Dockerfile's EXPOSE and the compose mapping, which do not follow a change made in /data/opencompany.env. Publish only the app port: the code sidecar, the WhatsApp bridge and Temporal listen on internal ports without authentication.
Serving other machines
Compose publishes the app on 127.0.0.1 only, so only this machine reaches it. To serve other machines, drop the 127.0.0.1: prefix from the ports: mapping, put a TLS proxy in front, and set JWT_COOKIE_SECURE=true. Until you do, the log warns at every start that the session cookie travels over plain HTTP.
The proxy should also refuse /ws/internal. That is where the backend's Temporal workers call back in; it skips the login check and runs any node a message names, shell included. The handshake requires a token derived from SECRET_KEY (see authentication.md), and the workers reach it inside the container, so blocking it at the proxy costs nothing and adds a second layer. Keep Host intact through the proxy, or list the public origin in CORS_ORIGINS: every WebSocket handshake refuses an Origin that is neither the request's own host nor listed there. Compose keeps the 127.0.0.1 mapping by default because login is off until you turn it on.
Upgrading
git pull
docker compose up -d --build
The volume keeps all state. An upgrade does not refresh the tools downloaded into /data/packages; delete a tool's directory there and the app fetches the current version the next time it needs it.
Stopping
docker compose stop gives the backend up to 120 seconds to drain its Temporal workers and record a clean shutdown. If the container is killed before that, the next start treats it as a crash and pauses the running deployments; resume them from the canvas.
With plain docker run, pass --init and --stop-timeout 120 to get the same behaviour.
Limitations
- Temporal Web UI. The dev server binds loopback inside the container, so its UI is not reachable from outside.
- Claude Code login. The login button in the credentials panel waits for a browser callback on the container's own localhost, so it cannot finish. Log in from an interactive shell in the container (
docker compose exec opencompany sh) withCLAUDE_CONFIG_DIR=/data/claudeset, or supplyANTHROPIC_API_KEYthroughenvironment:. Codex has no login button at all; run its login from the same shell. - Owner-checked panels under login. The image always requires a login, and the editor saves workflows through a REST route that records the placeholder owner
ownerrather than the logged-in account. The Canvas, Memory, Context and dataSource panels check that owner, so they can refuse the logged-in user for such a workflow.company deployVMs, which also require a login, behave the same. - Browser image integration. The image selects system Chromium with
BROWSER_FAMILY=chromiumand enablesBROWSER_HEADLESS=truefor displayless operation. The default system mode fails clearly when no installed browser exists. Testing mode is a separate opt-in download. Both modes install the pinned browser-use CLI with uv. Validate selected-browser version/profile compatibility and Linux libraries in the built image; adding the extra alone is not an end-to-end browser check. - Agent nodes need the
gitextra and a git repository. Claude Code and Codex agents work in git worktrees, and the image contains no.git. Rungit initin a workflow's workspace and make a first commit before pointing an agent at it. Set a commit identity once from a shell in the container (git config --global user.name ...anduser.email ...); it is stored in/data/homeand survives upgrades. - Bind mounts. A bind mount works in place of the named volume, but the Temporal CLI is then downloaded on first start (a new named volume receives the copy baked into the image), and the directory must allow executables, symlinks and Unix sockets. Prefer the named volume on Windows and macOS hosts.
- Memory. Give the container at least 1 GB. At idle the backend holds about 180 MB of process memory and the Temporal dev server about 115 MB;
docker statsshows up to about 450 MiB because it also counts the page cache of the code they run. - Disk. The image is about 1.3 GB, and the
browserextra adds about 1.2 GB. A build needs room for its layers on top of that. On Docker Desktop they land on the drive that holds Docker's disk image, which is C: on Windows unless you move it (Settings > Resources > Advanced > Disk image location). A build that fills that drive makes Docker's filesystem read-only and takes down every running container. - Built and tested on linux/amd64.
Optional external services
- Redis:
REDIS_ENABLED=trueandREDIS_URL=redis://<host>:6379. - A Temporal cluster:
TEMPORAL_SERVER_ADDRESS=<host>:7233. With a non-loopback address the backend connects to it instead of spawning its own dev server.
Maintaining the image
No CI job builds the image. What keeps it in step with the rest of the repo:
- Toolchain pins. The
oven/buntag must match the rootpackage.jsonpackageManager(what CI's setup-bun reads), and theghcr.io/astral-sh/uvtag must matchdesktop/runtimes.json(the desktop bundle).test_docker_image_pins_match_the_bun_and_uv_pinsincli/tests/test_release_pipeline_config.pyfails when one moves without the other. - The port.
EXPOSEand the container side of the compose mapping repeatPORTfrom.env.template;test_docker_port_matches_the_template_portin the same file fails when the template changes without them. - Line endings.
.gitattributespins LF for*.shanddocker/Dockerfile, so a Windows checkout builds the same image. A CRLF entrypoint fails undershat the first line. - The build context. Docker does not read
.gitignore. When you add a local state directory or a secret file pattern to.gitignore, add it to.dockerignoretoo, orCOPY . .bakes it into the image. - Build steps. The build stage runs the same two commands as CI (
bun install --frozen-lockfile,bun run build), thenuv sync --frozen --no-dev --extra docs: the committedserver/uv.lock, without the contributor tools, with thedocsextracompany buildalso installs. A new build step belongs incompany build, not in the Dockerfile, so every channel gets it. Step[6/6]fetches the Temporal CLI intoDATA_DIR, which is why a new named volume starts with it. - The runtime file list. The runtime stage copies only what
core/approot.pyreads:server/,client/dist,.env.template,package.json,.opencompany/workflowsand the entrypoint. A new path the backend reads outsideserver/needs aCOPYline there. - Optional tools. A system package that only some nodes need goes into an
EXTRASentry, not the default image.
Why the container doesn't run company serve
company serve needs the CLI's own venv and the root node_modules, and reads only <app>/.env (it ignores OPENCOMPANY_ENV_FILE). Its supervisor would also add a second shutdown deadline: it tree-kills the backend after backend_shutdown_grace_seconds (cli/_common.py; 125 s with the template's Temporal settings), independently of compose's stop_grace_period. The entrypoint runs the uvicorn command the desktop shell uses instead; see desktop_host_contract.md for the backend's side of that contract.