Install · Docker

Run the daemon in one container.

Docker is the same AgentX daemon as the Linux packages — system mode in a box. One container, one enrollment, many agents inside. Works on Mac, Windows, and Linux with Docker Desktop or Docker Engine. Your work stays on volumes you mount. The Hub image ships the daemon and AgentX CLI; on first start it downloads Claude Code, Codex, and Grok CLI into the data volume (needs network — we do not redistribute those binaries in the image).

~ hub.docker.com/r/agentxhq/agentx-daemon · tag latest · console on 127.0.0.1:3333 · linux/amd64 today

Native packages (Linux & Mac) instead →

01 / 05

Prerequisites

What you need before you start.

Docker. Docker Desktop on Mac or Windows, or Docker Engine on Linux. You need permission to pull images and publish a local port.
An AgentX account. Create one free so you can claim the daemon.
Network on first start. The container installs Claude Code, Codex, and Grok CLI into /var/lib/agentx/tools the first time it runs (and reuses them on later starts). Skip with -e AGENTX_SKIP_CLI_INSTALL=1 if you bring your own. Model keys stay yours.
Architecture. Hub currently publishes linux/amd64. On Apple Silicon, Docker Desktop can run that image via emulation; a native arm64 multi-arch image is planned.

02 / 05

Install with Docker

Same image. Pick your host OS.

The container is always Linux. On Mac and Windows, Docker Desktop runs that Linux image for you. Commands below pull agentxhq/agentx-daemon:latest for a first smoke on the default console port. Pin a version tag when you want a fixed build.

macOS · Docker Desktop

Install Docker Desktop for Mac, start it, and wait until the engine is running. Today’s Hub image is linux/amd64 — Intel Macs run it natively; Apple Silicon runs it through Docker’s emulation until we publish multi-arch.

1 · Pull

docker pull agentxhq/agentx-daemon:latest

2 · Run

docker run -d --name agentx --restart unless-stopped \
  -p 127.0.0.1:3333:3333 \
  -v agentx-data:/var/lib/agentx \
  -v agentx-root:/root \
  -v agentx-home:/home \
  agentxhq/agentx-daemon:latest

Three named volumes: daemon database, root home (agent workspaces), and /home for Unix users you add later.

3 · Open the console

open http://127.0.0.1:3333/console

Or open http://127.0.0.1:3333/console in the browser. Logs: docker logs -f agentx.

Windows · Docker Desktop

Install Docker Desktop for Windows with the WSL 2 backend enabled. Use PowerShell or Windows Terminal once Docker reports running.

1 · Pull

docker pull agentxhq/agentx-daemon:latest

2 · Run

docker run -d --name agentx --restart unless-stopped `
  -p 127.0.0.1:3333:3333 `
  -v agentx-data:/var/lib/agentx `
  -v agentx-root:/root `
  -v agentx-home:/home `
  agentxhq/agentx-daemon:latest

Backticks are PowerShell line continuations. In cmd.exe use a single line, or ^ continuations.

3 · Open the console

start http://127.0.0.1:3333/console

Or browse to http://127.0.0.1:3333/console. Logs: docker logs -f agentx.

Linux · Docker Engine or Desktop

Install Docker Engine for your distribution (from Docker’s docs, or Docker Desktop on a workstation. Your user needs permission to talk to the Docker socket (often membership in the docker group).

1 · Pull

docker pull agentxhq/agentx-daemon:latest

2 · Run

docker run -d --name agentx --restart unless-stopped \
  -p 127.0.0.1:3333:3333 \
  -v agentx-data:/var/lib/agentx \
  -v agentx-root:/root \
  -v agentx-home:/home \
  agentxhq/agentx-daemon:latest

Prefer a native package install on bare metal servers? Use the Debian / Ubuntu / Arch packages instead.

3 · Open the console

xdg-open http://127.0.0.1:3333/console

Or open http://127.0.0.1:3333/console. Health: curl -sS http://127.0.0.1:3333/readyz.

03 / 05

Enroll & claim

Connect the container to your account.

Open the local console. http://127.0.0.1:3333/console While enrollment is pending, the daemon shows a claim code and a claim link.
Open the claim URL (or paste the code into the claim flow on AgentX). Sign in if prompted, then confirm Claim daemon.
Non-default host port. If you publish something other than host port 3333, set -e AGENTX_SURFACES_WEB_PUBLIC_URL_OVERRIDE=http://127.0.0.1:<port> so claim redirects return to the URL you actually open.
Do not publish gRPC. Leave :3334 inside the container — MCP and the CLI talk to the daemon on the container network only.

04 / 05

Data & Unix users

Volumes hold your work. Users isolate agents.

The image runs as root inside the container — that is deliberate multi-user mode, the same as agentx-server on bare metal. Root on the container is not root on your laptop unless you escalate Docker itself.

/var/lib/agentx

Daemon state

SQLite, identity, enrollment. Named volume agentx-data. Survives container recreate.

/root

Default workspaces

Agents that run as root use /root/.agentx/<Name>. CLI auth files live under /root too. Volume agentx-root.

/home

Other Unix users

Homes for users you create for run_as. Volume agentx-home.

Add a user for run_as.

The create-agent picker lists Unix accounts inside the container that have a real login shell and a home directory. Create users with useradd; they land on the /home volume and persist across image upgrades.

Add a login user

docker exec -it agentx useradd -m -s /bin/bash alice
docker exec -it agentx id alice

Then create an agent in the console and set Run as to alice. Workspace defaults under /home/alice/.agentx/<AgentName>.

List users the daemon will advertise

docker exec agentx getent passwd | cut -d: -f1,6,7

Accounts with shells like nologin or false are omitted from the picker.

What is in the image. agentx-daemon and agentx (plus helpers). Vendor agent CLIs are downloaded on first start into /var/lib/agentx/tools on the data volume — not baked into the Hub layers.
Auth tokens stay per home. CLI login state lives under the run-as user’s home on the root/home volumes; the tools binaries live under the data volume.
Factory reset. Stop the container, then docker volume rm agentx-data agentx-root agentx-home.

05 / 05

Day-two ops

Upgrade, stop, and stay oriented.

Upgrade to a new image tag

docker pull agentxhq/agentx-daemon:latest
docker rm -f agentx
docker run -d --name agentx --restart unless-stopped \
  -p 127.0.0.1:3333:3333 \
  -v agentx-data:/var/lib/agentx \
  -v agentx-root:/root \
  -v agentx-home:/home \
  agentxhq/agentx-daemon:latest

Reuse the same volume names so enrollment and workspaces come back. To pin a build, replace :latest with a version tag from the Hub tags list.

Stop

docker rm -f agentx

Volumes remain until you delete them explicitly.

Sign in → Linux packages Trust & Security