Docker

Prerequisites

You need Docker Engine 24+ and Docker Compose v2 on the host. Qoc does not require Kubernetes or any cloud-specific runtime.

Your workspace directory (the folder containing desk.toml) is mounted into the container as a volume. All workspace files — entities/, snapshots/, orders/, research/ — live on your host disk, not inside the container image.

Minimal compose file

services:
  qoc:
    image: ghcr.io/qoc-app/qoc:0.73.0
    restart: unless-stopped
    environment:
      QOC_WORKSPACE: /workspace
      QOC_AUTH_TOKEN_FILE: /run/secrets/auth_token
      EQ_API_KEY:     ${EQ_API_KEY}
      EQ_API_SECRET:  ${EQ_API_SECRET}
      CX_API_KEY:     ${CX_API_KEY}
      CX_API_SECRET:  ${CX_API_SECRET}
    volumes:
      - ./:/workspace
      - qoc_state:/var/lib/qoc
    ports:
      - "127.0.0.1:7070:7070"
    secrets:
      - auth_token

secrets:
  auth_token:
    file: ./secrets/auth_token.txt

volumes:
  qoc_state:

Starting Qoc

1. 1

   Generate an auth token

   Run qoc init --token-file ./secrets/auth_token.txt to create a random 256-bit token. This token gates access to the local API and the remote tunnel.

2. 2

   Set environment variables

   Create a .env file next to the compose file with your venue credentials (EQ_API_KEY, EQ_API_SECRET, etc.). Docker Compose loads it automatically.

3. 3

   Bring the stack up

   Run docker compose up -d. The container starts, loads desk.toml from /workspace, connects configured venues, and begins the agent loop.

4. 4

   Verify with qoc status

   Run qoc status from the host. The CLI connects to http://127.0.0.1:7070 (or your configured tunnel URL) and prints connector health, UTA buying power, and pending orders.

qoc up inside the container

docker compose exec qoc qoc up --workspace /workspace --log-level debug

Volumes

The workspace mount (./:/workspace) is the only volume that needs to be backed up. It contains all agent decisions, orders, snapshots, and research. The qoc_state named volume holds connector session state and is reconstructed automatically from credentials on restart.

Do not mount the workspace as read-only — the agent writes proposed orders and snapshots during normal operation.

Related topics