Self-hosting Ork

Run the API, worker, web app, database and bot computers on a machine you control.

The signed-in product is a long-running API, a Graphile Worker, Postgres, and a computer provider (Docker supervisor, E2B, Daytona, CreateOS, or Boat). It is not a static site. The marketing site in apps/www can be hosted separately.

What you need

• Docker Engine 26 or newer with the Compose plugin, curl and OpenSSL.
• A registered Ork Accounts client for this installation (Accounts sign-in).
• A model: an OpenRouter key, a connection added in the app after signup, or a model server you run yourself (models).
• For a public host, a domain and TLS (production deployment).

Linux server setup

In Ork setup, sign in to Accounts and choose the self-hosted option. Connect an existing server by its HTTPS address, or run the displayed command in a terminal on your Linux server. The installer asks for the domain there, installs into ~/orkbot and pins its files to one source revision.

Point the domain’s public DNS records at the server first. Inbound TCP 80 and 443 must reach it. The installer supports amd64 and arm64, installs missing prerequisites on Debian or Ubuntu from the distribution and Docker’s official package repositories, and uses sudo when needed. It keeps existing Docker daemon, firewall and SSH configuration. A conflicting Docker package or an older Engine needs an operator-managed update.

The one-use code expires after 15 minutes. After checking the host, the installer redeems it for the chosen HTTPS address. Accounts registers the installation’s client and admits its owner. The client secret stays in .env with mode 600. A separate credential in .orkbot-installation.json, also mode 600, reports installation progress for up to an hour. Keep the copied command private while its code is valid.

For an installer already downloaded from the same pinned source, a code can be supplied on stdin instead of a command argument:

bash install-images.sh --server --code-stdin

Paste the code and press Enter. ORKBOT_INSTALL_CODE is also accepted. The installer configures Caddy HTTPS, public origins and restricted Docker-computer egress. It stops if those firewall rules cannot be applied. Local Docker computers are the default. Models and remote computer providers remain optional settings in .env.

If an existing proxy owns ports 80 or 443, the installer asks whether to use it. Route the public HTTPS origin to 127.0.0.1:5173 and keep the proxy’s current TLS configuration. For unattended setup, pass --url https://server.example.com and --external-proxy. Do not publish the API or supervisor ports. Automatic Caddy setup requires ports 80 and 443 to be free.

Success is reported only after the public certificate, API health and Accounts sign-in are ready. Ork then connects to the server automatically. You can also open its HTTPS address and sign in with the same Accounts account. Creating a workspace does not grant server-administration permissions.

Rerunning from the same directory preserves credentials, database volumes and bot files. A configured installation resumes without redeeming another code. After an interrupted redeem whose response was lost, request a new code. The installer never retries redemption. Keep the same URL and proxy mode. Updating the installed files is a separate operator step covered in Upgrading.

If an image pull is denied, the installer keeps its credentials; rerun without a code after fixing registry access. Official packages must allow public pulls. An operator can use a reachable registry mirror, or preload the images and add --pull-never. The restricted-network guide covers those paths. Secrets and data backups are covered in the secrets checklist and backup guide.

Published images (no checkout)

Pull Postgres and ghcr.io/orkbot-run/ork/app into any empty folder. No clone or image build. Requires Docker Engine 26+ (API 1.45+ for bot home volume subpaths), the Compose plugin, curl, and OpenSSL.

mkdir -p orkbot && cd orkbot &&
curl -fsSLO https://raw.githubusercontent.com/orkbot-run/ork/main/infra/compose/install-images.sh &&
bash install-images.sh --prepare-only

The installer downloads docker-compose.images.yml and .env.images.example, then creates .env with random secrets. Configure Accounts next. Set OIDC_ISSUER=https://api.orkbot.run and OIDC_CLIENT_ID to your registered client ID in .env, then follow Accounts sign-in for the callback and client secret settings. Choose the public URL here too.

bash install-images.sh

The installer requires this exact issuer and a non-empty client ID before pulling images or changing services. If this check fails, your existing .env stays intact. On later runs, the installer keeps your settings and fills any missing upgrade secrets after checking the Accounts configuration, so existing secrets keep their values. See Self-host secrets checklist for backup and recovery. Flags may be combined in either order: --prepare-only, --local.

SANDBOX_PROVIDER defaults to docker. The images Compose file runs a sandbox supervisor (from the app image, on the internal network only) and pulls ghcr.io/orkbot-run/ork/computer. Signup and local Docker computers work without an E2B account. Optional remote providers: set SANDBOX_PROVIDER to e2b, novita, daytona, createos, or boat and add the matching API key. The published-images Compose stack requires SANDBOX_SUPERVISOR_TOKEN for every provider; leave it empty and compose up fails closed.

Optional: set OPENROUTER_API_KEY or connect a model in the UI after signup. Other providers, local models and approvals are covered in models.

The example defaults to edge (main builds). Every publish is multi-arch (amd64 + arm64), so arm64 hosts need no special tag. Do not assume latest is present until a stable release exists.

Open http://127.0.0.1:5173. Signup never grants server-administration permissions. Put TLS in front of :5173 for a public host and set the three public origins to that HTTPS URL.

Images Compose binds web to loopback (127.0.0.1:5173). Terminate TLS on the host and proxy there. Vite preview same-origin-proxies /api and /rpc, so do not expose :3100. Set BETTER_AUTH_URL, WEB_ORIGIN, and API_URL to that same HTTPS origin, and set ORKBOT_HOST to its hostname (for example, app.example.com). Cookies and CORS follow those origins.

app.example.com {
	reverse_proxy 127.0.0.1:5173
}

Open Agent computer on a bot, or send a message that uses the desktop, to see the local Docker computer. For in-stack Caddy plus remote E2B computers, use the production Compose path and infra/compose/Caddyfile.prod instead of this host proxy.

Restricted networks / mirror downloads

If the installer, Compose downloads, or image pulls are blocked, use the restricted-network guide for mirror settings and local files.

Docker Compose (single machine)

1. Copy .env.example to .env and set POSTGRES_PASSWORD and POSTGRES_APP_PASSWORD (openssl rand -hex 16 each), plus BETTER_AUTH_SECRET, ENCRYPTION_KEY, and SCREEN_PROXY_SECRET to independent long random strings (32+ characters; 64 hex for ENCRYPTION_KEY). Docker sandboxes also need a dedicated SANDBOX_SUPERVISOR_TOKEN. Keep existing ENCRYPTION_KEY values so stored credentials stay decryptable.
2. Configure the registered Ork Accounts client in .env using Accounts sign-in. OIDC_ISSUER must be https://api.orkbot.run, and OIDC_CLIENT_ID is required. Set optional model or integration keys as needed.
3. Build the computer image: pnpm sandbox:build (Compose also builds it via the computer service).
4. docker compose --env-file .env -f infra/compose/docker-compose.yml up --build
5. Open the web origin (http://127.0.0.1:5173 by default). Signup never grants server-administration permissions.

On Windows, if an older clone with core.autocrlf=true leaves the computer pane hung on boot (bash\r in sandbox logs): from a clean worktree, set git config core.autocrlf false, run git add --renormalize . && git checkout -- ., then rebuild with pnpm sandbox:build.

Compose runs Postgres, the sandbox supervisor (Docker socket), API, worker, and a Vite preview of the web app. Bot computers are sibling containers (orkbot/computer:local) on separate per-bot networks; only the supervisor and screen proxy join each one. The API process does not get an unrestricted Docker socket; the supervisor owns the lifecycle.

Postgres stays on the Compose network only (not published on the host), matching the images compose. Credentials come from .env (POSTGRES_PASSWORD is required). Prefer a URI-safe value (openssl rand -hex 16); characters such as @ : / ? # % break the interpolated DATABASE_URL inside Compose. Official Postgres images set user, password, and database only on first volume init, so an existing database volume keeps its original identity: keep those values in .env, or change them in place with ALTER ROLE / rename. Recreate the volume only after a backup (or when the data is disposable); docker compose down -v deletes all Postgres state. For host-side clients (pnpm db:migrate, GUI tools), add infra/compose/docker-compose.postgres-host.yml so Postgres is published on loopback 127.0.0.1:5433, or use docker compose --env-file .env -f infra/compose/docker-compose.yml exec postgres sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB"'. Do not publish Postgres on a public interface.

Local (source checkout)

Same as the README quick start: .env from .env.example, pnpm sandbox:build, pnpm dev, then the URL it prints (http://127.0.0.1:5173 by default, or http://localhost:5173 — both loopback hosts are trusted). Tauri: pnpm --filter @orkbot/desktop dev while that stack is up, choosing Existing instance with that address. The desktop app’s This computer option instead installs and runs the published images itself with Docker Compose (see Published images), using port 45173 by default so it can run alongside pnpm dev. If that port is occupied, the app selects and remembers another loopback port. The managed API gets a Docker-assigned loopback port; all desktop traffic uses the web origin.

For source development in WSL, keep the checkout and data directory in the Linux filesystem (for example, ~/orkbot), and run pnpm dev as your normal user. The host-run supervisor matches bot container UID/GID to that user. If Docker Desktop container IPs are unreachable, set SANDBOX_CONTROL_VIA_LOOPBACK=true in .env; this publishes the token-protected control service on a random loopback port. Leave this unset for the Compose-hosted supervisor.

Compose bot homes mount only their own subdirectory of the application volume using Docker volume semantics. Docker’s internal volume paths are never used as host bind mounts.

Configure and operate

• Configuration: how settings reach each service, run limits, the database and outbound proxies.
• Secrets: the required keys and how to keep them.
• Sign-in and accounts: who can sign up, email, SSO, passkeys and passwords.
• Models: model providers, local models, approvals, media generation and voice.
• Tools and integrations: web search, memory, MCP servers, messaging apps, cloud coding agents and payments.
• Computer providers and Docker computers: where bot computers run and how they are limited.
• Storage and encryption: content encryption, object storage and upload limits.
• Production deployment: a public single-VM install with automatic HTTPS.
• Backup and restore and upgrading.
• Logs and monitoring: logs, error reports, traces, security events and alerts.
• Audit log: who did what in each organization, retention, export and SIEM forwarding.
• Apps and clients: mobile and desktop apps, push, client updates and web page settings.
• Billing: optional Stripe plans and model credits.
• Restricted networks: mirrors when downloads are blocked.

Reporting a problem

Attach a diagnostics report to a self-host issue:

docker compose -f docker-compose.images.yml exec api node dist/cli/diagnostics.js

From a checkout, use -f infra/compose/docker-compose.yml (or the production file) instead. The report lists the revision, which features are on, migration status, each bot’s MCP servers with their health, and the latest runs. It prints no secrets, settings values, names, addresses, paths or message content; servers, bots and runs appear only as short hashes.

When a user asks their bot to report a bug or send feedback, the report is saved on your server in the feedback_reports table, with the chat, bot and run it came from. Nothing is sent to the Ork project.