Skip to main content
The local shape keeps every component on one machine:
Compose runs Druks, Postgres, Redis, Drukbox, the secrets exchange, and the secrets proxy. The Drukbox service holds the Docker socket of the host. Its docker provider starts sandboxes as sibling containers on the host daemon. Agent work stays in these isolated containers. It does not run in the Druks process.

​
Prerequisites

  • Docker with the Compose plugin
  • Sufficient local Docker capacity for Postgres, Redis, Druks, Drukbox, and short-lived sandbox containers.
You need no Tailscale account or remote VM provider. The image registry provides Druks service and sandbox images for both linux/amd64 and linux/arm64.

​
macOS: enable host networking first

The Compose services use network_mode: host. On macOS, Docker Desktop needs host networking for the dashboard and health endpoint at 127.0.0.1:8001. Docker Desktop 4.34 or later supports this feature. Before you run the installer:
  1. Open Docker Desktop and sign in to your Docker account.
  2. Open Settings → Resources → Network.
  3. Select Enable host networking.
  4. Select Apply & restart.
See Docker’s host networking guide for the platform requirements and limitations.

​
1. Install the local Druks profile

docker is the default provider. Thus, the bare command selects the local shape. DRUKS_PROVIDER=docker makes the same selection explicit. The local shape needs no authored values, so the first run goes all the way:
  • The installer writes ~/druks/druks.toml with [sandbox].provider = "docker".
  • It creates ~/druks/.env with DEFAULT_HOST_PROVIDER=docker.
  • It creates ~/.config/druks/harnesses for optional harness configuration.
  • It generates the database password and the stored-secret key.
  • It pulls images and applies migrations.
  • It starts Druks, Postgres, Redis, Drukbox, the secrets exchange, and the secrets proxy. Drukbox listens on 127.0.0.1:8780. The exchange listens on 127.0.0.1:8781. The proxy listens on 172.17.0.1:8880, where sandbox containers reach it.
  • It uses COMPOSE_FILE=compose.yaml:compose.override.yaml and COMPOSE_PROFILES=proxy, without Caddy or the janitor.
Drukbox controls sandboxes through the mounted /var/run/docker.sock. The installer records the group ID of the socket in .env. This value gives the non-root service user access to the socket. Drukbox keeps its schema in a drukbox database in the same Postgres instance. It does not require a separate data store. A sandbox holds a placeholder for each credential and sends its HTTPS through the secrets proxy. See the secrets exchange and the secrets proxy. For the bundled software_factory app, connect its GitHub App after startup. Use Settings → Connections → Services in the dashboard. Create the app there, or paste the credentials of an existing GitHub App. See the GitHub connection. If an existing installation runs Drukbox through make dev, finish or cancel the local runs. Stop the host process. Then run the installer again. The Compose service starts with a new sandbox registry.

​
2. Make sure that the first system operates

Success means the Compose services are up and the health endpoint returns {"status":"ok"}. The dashboard is at http://127.0.0.1:8001.

​
3. Connect agent harnesses

Open Settings → Providers in the dashboard. Connect the providers for your selected harnesses with a subscription or API key, as each provider supports. Druks stores the credentials in Postgres and sends fresh credentials to each sandbox. It does not use host CLI login files. The local profile uses [identity].mode = "none". It has no browser authentication and exactly one operator account. A new installation shows its setup page until the first subscription connection completes. That connection creates the operator account from the provider-verified email. Protect database access and backups as credential data. The secrets_key envelope protects every secret in the vault, subscriptions included. Agent calls refuse before provisioning if their selected harness is not connected. druks doctor reports the connection and token expiry for every registered harness. Build the sandbox images, then run the complete preflight. Build them again after every re-run of the installer:
Each configured check must be green. You can run this command before you connect the harnesses. In that state, each disconnected harness reports a credential error. To prove the full sandbox path rather than only Drukbox’s control-plane health:
This creates and deletes a real sandbox container.

​
4. Connect a browser profile

Installed apps declare the browser profiles they use. To save a login:
  1. Open Settings → Connections → Browser.
  2. Find the profile for the site.
  3. Choose Log in. Druks opens a headed browser in a disposable browser sandbox.
  4. Authenticate on the site.
  5. Choose Save. Druks closes the browser and stores its encrypted profile. It marks the profile as ready.
When a site expires the login, the profile becomes stale. Choose Reconnect. Druks creates a new login window from the saved state. Authenticate again. Then save the replacement profile. Cancel deletes the disposable sandbox without a change to the saved state. A web-process restart also deletes open login windows. After Druks returns, open the window again. To examine the complete path, save the profile. Then run an app workflow that borrows it. Make sure that its browser opens the authenticated site. A saved login window always stores profile_dir. This rule also applies to a profile that came from Playwright storage_state.

​
5. Exercise an app

Druks does not invent a generic domain job. An installed app supplies the workflow and its trigger. In the bundled distribution, software_factory is the reference app. Register a project in its dashboard. Use its configured ticket or GitHub trigger. To run without Linear or Jira, select druks in Software Factory → Settings and use the board on this appliance. GitHub is still required for pull requests. See ticketing integrations. The run appears on the subject page and in Activity. Agent-call pages stream transcript and artifact data. If you develop a different app, install that distribution into a development Druks environment and invoke its documented trigger or Workflow.start() path. See writing an app.

​
Sandbox image

[sandbox].image selects the image Drukbox starts. The shipped ghcr.io/czpython/druks/sandbox:latest image contains the non-root druks user plus Git, GitHub CLI, Node, and the supported agent CLIs. If you change the sandbox, build the image from the repository:
Set the image in ~/druks/druks.toml, then re-run the installer:
A local build needs no registry. After the installer, run docker compose exec web druks sandboxes build to refresh the image and its templates. See Update / redeploy for template reuse and cleanup. Existing hosts keep their original image.

​
Webhook caveat

GitHub, Linear, and Jira cannot connect to a loopback listener. Dashboard-initiated actions work locally, including Software Factory’s druks board, which needs no tracker credentials. Provider-driven Linear and Jira flows need an HTTPS tunnel forwarding to 127.0.0.1:8001. Connect Linear or Jira under Settings → Connections → Services when you use those trackers, and keep the exact public paths:
The tunnel must preserve request bodies and signature headers. Do not expose the rest of the local dashboard without adding an authentication edge. Phone calls need the tunnel too. Twilio posts each call to /_external/twilio/calls/ on 127.0.0.1:8001, and it streams the call’s audio to /_calls/*, which must go to the calls server on 127.0.0.1:8002 with the WebSocket upgrade. For changing Druks itself, use the host-run development topology in Development rather than repeatedly rebuilding the production image.