Skip to main content

Docker

The easiest way to run Boxer is via the pre-built image published on DockerHub.

Prerequisites​

  • Docker installed and running
  • The host must support nested cgroup management (most Linux distributions with cgroup v2 do)

Download the production compose file and start the service:

# Replace "main" with the version tag you want to deploy, e.g. refs/tags/v1.0.0
curl -fsSL https://raw.githubusercontent.com/theonekeyg/boxer/main/docker-compose.prod.yml -o docker-compose.prod.yml
docker compose -f docker-compose.prod.yml up -d

The server will be available at http://localhost:8080.

Run with Docker​

docker run \
  --privileged \
  -p 8080:8080 \
  theonekeyg/boxer
Why --privileged?

Boxer requires three things that Docker's capability system cannot grant individually:

  • Writable cgroupfs - on startup, Boxer moves its init process into a child cgroup (/sys/fs/cgroup/init/) so that the root cgroup is empty and gVisor can configure cgroup.subtree_control to enforce CPU, memory, and PID limits per sandbox. Docker mounts /sys/fs/cgroup read-only for all non-privileged containers regardless of capabilities - only --privileged makes it writable.
  • Network namespaces - gVisor creates an isolated network namespace for each sandboxed execution, which requires CAP_NET_ADMIN.
  • gVisor systrap - gVisor intercepts guest syscalls via ptrace. Docker's default seccomp profile blocks several syscalls gVisor relies on (ptrace, process_vm_readv, process_vm_writev), so the profile must be lifted. --privileged disables seccomp and AppArmor automatically.

Verify​

curl http://localhost:8080/healthz

Configuration​

The image ships with a Docker-optimised config (see docker/config.json in the repository). To override it, mount your own config file.

Docker Compose​

Mount to the default path (no env var needed):

services:
  boxer:
    image: theonekeyg/boxer
    privileged: true
    ports:
      - "8080:8080"
    volumes:
      - /path/to/your/config.json:/etc/boxer/config.json:ro
      - boxer-data:/root/.boxer

volumes:
  boxer-data:

Or mount to a custom path and set BOXER_CONFIG:

services:
  boxer:
    image: theonekeyg/boxer
    privileged: true
    ports:
      - "8080:8080"
    environment:
      - BOXER_CONFIG=/my/config.json
    volumes:
      - /path/to/your/config.json:/my/config.json:ro
      - boxer-data:/root/.boxer

volumes:
  boxer-data:

Docker​

Mount to the default path:

docker run -d \
  --privileged \
  -p 8080:8080 \
  -v /path/to/your/config.json:/etc/boxer/config.json:ro \
  theonekeyg/boxer

Or mount to a custom path and set BOXER_CONFIG:

docker run -d \
  --privileged \
  -p 8080:8080 \
  -v /path/to/your/config.json:/my/config.json:ro \
  -e BOXER_CONFIG=/my/config.json \
  theonekeyg/boxer

See the Getting Started page for all available configuration fields.