Single-User Docker

Running Superagent as a Docker container is the recommended approach for headless servers, remote access, and environments where you want to manage Superagent alongside other containerized services.

In single-user mode, there is no login screen -- the app is open to anyone who can reach the port. This is appropriate when you are the only user, or when network-level access controls (VPN, firewall, reverse proxy with authentication) restrict who can connect.

When to choose this option

• You want to run Superagent on a remote server or NAS and access it from a browser.
• You prefer headless, always-on operation without a desktop environment.
• You are a single user or rely on network-level access control.
• You want to manage Superagent with Docker Compose alongside other 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

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

ghcr.io/skillfulagents/superagent:main

Available tags:

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

Quick start

Create a .env file with your 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 your browser to http://localhost:47891 (or your server's IP address).

Docker Compose reference

Here is a complete docker-compose.yml with all 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 Superagent 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 Superagent
      # 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

How it works

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

This means:

• Agent containers run as peers alongside the Superagent container on the host.
• Agent containers publish ports on the host's network interface.
• The Superagent container must use network_mode: host so it can reach those ports via 127.0.0.1.

Volume persistence

All Superagent state is stored in the data directory (~/.superagent by default). This includes:

Important: The host path and the SUPERAGENT_DATA_DIR value must be the same path. Superagent 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

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

Port configuration

The default port is 47891. Since the container uses host networking, the port is exposed directly on the host. To change it, set the PORT environment variable:

environment:
  - PORT=8080

Then access Superagent at http://your-server:8080.

Updating

To update to the latest version:

docker compose pull
docker compose up -d

Your data is preserved in the mounted volume. The SQLite database schema is migrated automatically on startup when needed.

To pin a specific version instead of tracking main:

image: ghcr.io/skillfulagents/superagent:0.3.30

Building from source

If you prefer to build the image locally:

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

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

Next steps

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