Self-Hosting

Single-User Docker

Run Gamut as a Docker container for headless, always-on operation and remote access. Single-user mode has no login screen, so anyone who can reach the port can use the app.

When to choose this option

Gamut runs on a remote server or NAS and is accessed from a browser.
Headless, always-on operation without a desktop environment.
A single user, or network-level access control (VPN, firewall, authenticating reverse proxy) restricting who can connect.
Gamut managed with Docker Compose alongside other containerized services.

For multi-user deployments with built-in authentication, see Auth Mode.

Prerequisites

Docker Engine (or Docker Desktop) with Docker Compose v2.
An Anthropic API key from the Anthropic Console.

Published image

Gamut publishes pre-built container images to the GitHub Container Registry:

ghcr.io/skillfulagents/superagent:main

Available tags:

Tag	Description
`main`	Latest build from the main branch (single-user mode).
`main-auth`	Latest build with authentication enabled. See Auth Mode.
`0.4.8`	Pinned release version (single-user).
`0.4.8-auth`	Pinned release version with auth.
`0.4`	Latest patch in the 0.4.x line (single-user).
`0.4-auth`	Latest patch in the 0.4.x line with auth.

Images are built for both linux/amd64 and linux/arm64.

Quick start

Create a .env file with the API key:

ANTHROPIC_API_KEY=sk-ant-...

Create a docker-compose.yml:

services:
  superagent:
    image: ghcr.io/skillfulagents/superagent:main
    network_mode: host
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ${HOME}/.superagent:${HOME}/.superagent
    environment:
      - SUPERAGENT_DATA_DIR=${HOME}/.superagent
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - PORT=47891

Start the container:

docker compose up -d

Open http://localhost:47891 (or the server's IP address) in a browser.

Docker Compose reference

A complete docker-compose.yml with the common options:

services:
  superagent:
    image: ghcr.io/skillfulagents/superagent:main
    restart: unless-stopped
 
    # Host networking is required. Agent containers publish ports on the
    # host, and the main Gamut container connects to them via
    # 127.0.0.1. Without host networking, 127.0.0.1 inside the main
    # container would be its own loopback, not the host's.
    network_mode: host
 
    volumes:
      # Docker-outside-of-Docker: mount the Docker socket so Gamut
      # can create sibling containers for each agent.
      - /var/run/docker.sock:/var/run/docker.sock
 
      # Persistent data directory. The path inside the container must
      # match the host path so that bind-mounted agent workspaces
      # resolve correctly when passed to sibling containers.
      - ${HOME}/.superagent:${HOME}/.superagent
 
    environment:
      - SUPERAGENT_DATA_DIR=${HOME}/.superagent
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - PORT=47891

Gamut uses Docker-outside-of-Docker (DooD) to manage agent containers. Instead of running a Docker daemon inside itself, the main container mounts the host's Docker socket (/var/run/docker.sock) and issues commands to the host daemon, creating sibling containers on the host.

Agent containers run as peers of the Gamut container and publish ports on the host's network interface.
The Gamut container needs network_mode: host to reach those ports via 127.0.0.1.

Volume persistence

All Gamut state lives in the data directory (~/.superagent by default):

Path	Contents
`superagent.db`	SQLite database (agents, sessions, scheduled tasks, audit logs, settings).
`agents/`	Per-agent directories containing workspaces, message history (JSONL), and downloads.
`settings.json`	Application configuration (container runtime, resource limits, API keys).
`.auth-secret`	Auto-generated secret for session signing (auth mode only).

Important: The host path and the SUPERAGENT_DATA_DIR value must be the same path. Gamut passes this path to agent containers as a bind mount, and those containers run on the host, so the path must be valid on the host filesystem.

To use a custom data directory:

volumes:
  - /data/superagent:/data/superagent
environment:
  - SUPERAGENT_DATA_DIR=/data/superagent

Environment variables

Variable	Required	Default	Description
`ANTHROPIC_API_KEY`	Yes	None	The API key agents use to call Claude.
`SUPERAGENT_DATA_DIR`	No	`~/.superagent`	Path to the persistent data directory.
`PORT`	No	`47891`	Port the web server listens on.

Additional API keys for optional integrations (Composio, Browserbase, OpenAI, Deepgram, and others) can be configured in Settings after the container is running.

Port configuration

The default port is 47891. With host networking, the port is exposed directly on the host. To change it, set PORT:

environment:
  - PORT=8080

Then open http://your-server:8080.

Updating

To update to the latest version:

docker compose pull
docker compose up -d

Data persists in the mounted volume, and the SQLite schema migrates automatically on startup when needed.

To pin a specific version instead of tracking main:

image: ghcr.io/skillfulagents/superagent:0.4.8

Building from source

To build the image locally:

git clone https://github.com/SkillfulAgents/Gamut.git
cd Gamut
docker compose build
docker compose up -d

The repository's docker-compose.yml includes a build section that builds from the local Dockerfile.

Next steps

Auth Mode (Multi-User): Add authentication for team deployments.
Electron Desktop App: Run Gamut as a native desktop application instead.