Docker

Run DorkOS as a container. The official image bundles Node.js, the DorkOS CLI, and the built client — no host dependencies beyond Docker.

Quick Start

docker run -d --name dorkos \
  -p 4242:4242 \
  -e ANTHROPIC_API_KEY=your-key-here \
  -v dorkos-data:/root/.dork \
  ghcr.io/dork-labs/dorkos:latest

This runs DorkOS in the background (-d), maps port 4242 on your machine to the container, passes your API key, and creates a named volume so your data survives container restarts.

Open http://localhost:4242.

Image Versioning

Every release publishes the image with multiple tags:

For production deployments, pin to an exact version:

docker pull ghcr.io/dork-labs/dorkos:0.12.0

The latest tag always points to the most recent non-prerelease version. Pre-release tags (e.g., 0.13.0-beta.1) are available by exact version but do not update latest.

Multi-Platform Support

The image is built for both linux/amd64 and linux/arm64. Docker automatically pulls the correct architecture for your machine:

• Intel/AMD servers and desktops: linux/amd64
• Apple Silicon (M1/M2/M3) via Docker Desktop: linux/arm64
• ARM servers (AWS Graviton, Ampere): linux/arm64

No configuration is needed — docker pull selects the right platform automatically.

Supply Chain Verification

Every published image includes a SLSA provenance attestation, verifying it was built from the expected source commit in the dork-labs/dorkos repository. Verify any image with the GitHub CLI:

gh attestation verify oci://ghcr.io/dork-labs/dorkos:0.12.0 --owner dork-labs

This confirms the image was built by GitHub Actions from the official repository — not from a fork or local machine.

Configuration

Pass environment variables with -e or an env file. All standard environment variables are supported.

Custom port

Two things need to agree: the port DorkOS listens on inside the container (--port), and the port Docker maps from the host (-p). Both sides of -p host:container should match the --port value:

docker run -d --name dorkos \
  -p 8080:8080 \
  -e ANTHROPIC_API_KEY=your-key-here \
  -v dorkos-data:/root/.dork \
  ghcr.io/dork-labs/dorkos:latest --port 8080

Environment file

Keep secrets out of your shell history:

ANTHROPIC_API_KEY=your-key-here
NODE_ENV=production

docker run -d --name dorkos \
  -p 4242:4242 \
  --env-file .env.dorkos \
  -v dorkos-data:/root/.dork \
  ghcr.io/dork-labs/dorkos:latest

Persistent Data

DorkOS stores configuration, session transcripts, agent registrations, and the SQLite database in ~/.dork/ inside the container. Without a volume mount, all of this is lost when the container is removed. Mount a named volume or host directory to persist data across container restarts and upgrades.

docker run -d --name dorkos \
  -p 4242:4242 \
  -e ANTHROPIC_API_KEY=your-key-here \
  -v dorkos-data:/root/.dork \
  ghcr.io/dork-labs/dorkos:latest

mkdir -p ~/.dork
docker run -d --name dorkos \
  -p 4242:4242 \
  -e ANTHROPIC_API_KEY=your-key-here \
  -v ~/.dork:/root/.dork \
  ghcr.io/dork-labs/dorkos:latest

Mounting a project directory

By default, agents running inside the container can only see the container's own filesystem — they have no access to your code on the host machine. To let agents read and write files in one of your projects, bind-mount the project directory into the container and tell DorkOS to use it as the default working directory:

docker run -d --name dorkos \
  -p 4242:4242 \
  -e ANTHROPIC_API_KEY=your-key-here \
  -e DORKOS_DEFAULT_CWD=/workspace \
  -e DORKOS_BOUNDARY=/workspace \
  -v dorkos-data:/root/.dork \
  -v ~/projects/my-app:/workspace \
  ghcr.io/dork-labs/dorkos:latest

Docker Compose

The docker run commands above work fine for trying DorkOS out, but they're unwieldy to maintain — you end up with long shell commands that are easy to mistype and hard to version control. Docker Compose captures the full configuration in a declarative file, making it reproducible, easy to update, and simple to tear down with docker compose down.

services:
  dorkos:
    image: ghcr.io/dork-labs/dorkos:latest
    container_name: dorkos
    restart: unless-stopped
    ports:
      - "4242:4242"
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - NODE_ENV=production
    volumes:
      - dorkos-data:/root/.dork
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:4242/api/health"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s

volumes:
  dorkos-data:

docker compose up -d

With a reverse proxy

The standalone Compose setup above serves DorkOS over plain HTTP on port 4242. That's fine for local use, but if you're exposing DorkOS over the internet — on a VPS, a home server with a domain, or any machine where others will connect — you need HTTPS. Browsers will block mixed content, credentials travel in the clear, and SSE streams are vulnerable to interception without TLS.

A reverse proxy sits in front of DorkOS, terminates TLS, and forwards requests. Caddy is the simplest option because it obtains and renews Let's Encrypt certificates automatically — no manual cert management. It also handles the SSE-specific buffering settings that DorkOS requires.

Add Caddy to the Compose file for automatic HTTPS:

services:
  dorkos:
    image: ghcr.io/dork-labs/dorkos:latest
    container_name: dorkos
    restart: unless-stopped
    expose:
      - "4242"
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - NODE_ENV=production
    volumes:
      - dorkos-data:/root/.dork
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:4242/api/health"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s

  caddy:
    image: caddy:2-alpine
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy-data:/data
      - caddy-config:/config

volumes:
  dorkos-data:
  caddy-data:
  caddy-config:

dorkos.example.com {
    reverse_proxy dorkos:4242 {
        flush_interval -1
    }
}

Health Check

curl http://localhost:4242/api/health
# { "status": "ok", "version": "0.8.0", "uptime": 12345 }

The health endpoint is unauthenticated and suitable for load balancer or container orchestrator use.

Building from Source

The official image from the container registry is the easiest path. Build from source if you need to run unreleased changes, test a fork, or include local modifications:

git clone https://github.com/dork-labs/dorkos.git
cd dorkos
pnpm install
pnpm docker:build

docker run -d --name dorkos \
  -p 4242:4242 \
  -e ANTHROPIC_API_KEY=your-key-here \
  -v dorkos-data:/root/.dork \
  dorkos:latest

From published npm (no clone needed)

If you want a custom Docker image but don't need local code changes, you can build one that installs a published version directly from npm. This is useful when the official container image isn't available or you need to customize the base image:

docker build -f Dockerfile.run \
  --build-arg INSTALL_MODE=npm \
  --build-arg DORKOS_VERSION=latest \
  -t dorkos:npm .

Updating

docker pull ghcr.io/dork-labs/dorkos:latest

docker stop dorkos && docker rm dorkos
docker run -d --name dorkos \
  -p 4242:4242 \
  -e ANTHROPIC_API_KEY=your-key-here \
  -v dorkos-data:/root/.dork \
  ghcr.io/dork-labs/dorkos:latest

docker compose pull
docker compose up -d

Data in the dorkos-data volume persists across updates.

Troubleshooting

docker logs dorkos

Next Steps