Agents

The agent is what actually builds and runs preview containers. The server queues jobs; the agent claims them, builds the images, brings up the containers, and streams logs + events back. In v1, the agent runs in the same compose project as the server.

Single-host (recommended, the only tested path)

The bundled compose file at https://galley.sh/install/docker-compose.yml already includes a galley-agent service. It mounts the host’s Docker socket so it can spin up preview containers:

galley-agent:
  image: galleysh/agent:v1
  restart: unless-stopped
  depends_on: [galley-server]
  environment:
    GALLEY_CONTROL_PLANE_URL: ${GALLEY_PUBLIC_URL}
    GALLEY_NATS_URL: nats://bus:4222
    GALLEY_AGENT_TOKEN: ${GALLEY_AGENT_TOKEN}
    GALLEY_DATA_DIR: /var/lib/galley
    GALLEY_PUBLIC_NETWORK: galley-public
    GALLEY_TLS_ENABLED: "true"
    GALLEY_CERT_RESOLVER: le
  volumes:
    - /var/run/docker.sock:/var/run/docker.sock
    - galley-agent-data:/var/lib/galley
  networks:
    - galley-internal
    - galley-public

The bootstrap flow:

1. After docker compose up -d for the first time, sign in to the dashboard.
2. Admin → Agents → New agent, name it, copy the bootstrap token.
3. Set GALLEY_AGENT_TOKEN=<token> in .env.
4. docker compose up -d galley-agent.

The agent registers with the bootstrap, exchanges it for a long-lived credential, and shows up online in the dashboard within a heartbeat (~30s).

What the agent connects to

Destination	Why	Failure mode
Control plane URL	Bootstrap exchange (one-shot at start)	Won’t start without it
Message bus (bus:4222)	Job claim, log + event publish (always-on)	Reconnects with backoff; deploys queue
Local Docker socket	Run/inspect/remove containers	Won’t start without it
Public registry	Pull base images for builds	Build fails; user-actionable error in logs
Repo provider (GitHub)	git clone PR refs	Build fails; surfaces auth/network detail

If the agent loses contact with the message bus mid-build, the build runs to completion locally (cancels are advisory). The reconciler on the server marks the deployment failed with agent_lost_contact if the agent never reconnects.

Capacity

One agent can run dozens of small previews comfortably; the limits in practice are:

• Disk for build caches + worktrees. 20 GB is comfortable for a moderate team; large monorepos may want more. Mounted at galley-agent-data.
• CPU + RAM during simultaneous builds. Default cap is 4 concurrent service builds (GALLEY_MAX_PARALLEL_BUILDS).
• Open file descriptors under load — the default is fine; only worth touching if you hit it.

When one host can’t keep up, you can stop the included agent and run more agent instances on the same host under different compose projects (each with its own bootstrap token + data volume). Not a great long-term answer, but it works while we get multi-host ready.

Roadmap: multi-host

A separate-host agent install (systemd unit pulling the binary out of the published image, or a container with the docker socket mounted) is planned but not tested. We don’t recommend running it in production yet — there are gaps in the proxy story for previews on hosts other than the one running the proxy.

Tuning knobs

• GALLEY_MAX_PARALLEL_BUILDS — concurrent builds per agent. Default 4.
• GALLEY_DEFAULT_CPUS / GALLEY_DEFAULT_MEMORY — defaults applied to services that don’t pin resources. e.g. 1.5 for CPUs, 1g for memory.
• GALLEY_DATA_DIR — host-mounted volume for build caches and per-build export dirs. Disposable; deleting it forces fresh git clones on next deploy.