Agent Mode

The host detail view for a connected agent, showing its status, capabilities, and host metrics.

The agent runs on a host with a container runtime and reconciles that host against the server’s desired state. It is published as a container image:

docker pull ghcr.io/trailer-dev/agent:latest

The ghcr.io/trailer-dev registry path is set at release time. Your deployment’s registry and organization may differ. Adjust the image reference to match where your images are published.

Responsibilities

• Register with the server and keep its connection alive through heartbeats.
• Poll the server for desired state and reconcile the host (containers, networks, volumes).
• Build images on the host.
• Collect host, GPU, and workspace metrics.
• Serve interactive sessions (logs, exec, attach, proxy) over a realtime WebSocket.

Lifecycle

After startup the agent connects to the server, then keeps three things running at once: a realtime connection for interactive sessions, a loop that polls for the host’s desired state and reconciles it, and a periodic heartbeat that reports status and metrics. The polling and heartbeat intervals, and whether the host is enabled, come from per-host settings the server sends when the agent connects and refreshes on each heartbeat.

sequenceDiagram
    participant A as Agent
    participant S as Server
    A->>S: connect and register
    S-->>A: per-host settings
    par Realtime
        A->>S: realtime connection
        S-->>A: logs / exec / attach / proxy requests
    and Reconcile loop
        loop periodically
            A->>S: poll for desired state
            S-->>A: desired host state
            A->>A: reconcile containers, networks, volumes
        end
    and Heartbeat loop
        loop periodically
            A->>S: heartbeat with status and metrics
            S-->>A: refreshed settings
        end
    end

If the connection fails the agent retries until it succeeds. The realtime connection reconnects on error.

Configuration

The agent reads configuration from a YAML file (default ~/.config/trailer.dev/config.yml), overridable by CLI flags. There is no environment-variable binding for these flags. Key flags:

Flag	Default	Purpose
--server-url, -S	http://localhost:8090	Address of the remote server to connect to.
--deployment-name, -D	host name	Name shown for this host in the server.
--build-directory, -b	/tmp	Directory used when building images.
--log-directory	XDG state dir	Directory for agent log files.
--log-max-size	built-in default	Maximum total size of agent log files in bytes.

For the agent, --server-url is the address of the server it connects to (not a bind address). The agent identifies itself with a per-machine registration token derived from the host’s machine ID.

Minimal config.yml:

server_url: http://server-host:8090
deployment_name: gpu-box-1

See the Configuration Reference for all options.

Running the agent

Pass the server address as an argument and mount the Docker socket:

docker run -d \
  -v /var/run/docker.sock:/var/run/docker.sock \
  ghcr.io/trailer-dev/agent:latest \
  -S http://server-host:8090

You do not need to add --gpus all for NVIDIA GPUs. When you enable the NVIDIA container toolkit from the host’s NVIDIA driver settings, Trailer restarts the agent with the NVIDIA runtime automatically, which is what gives it GPU access. Passing --gpus all at launch only works on a host that already has the NVIDIA container toolkit installed outside Trailer, and is otherwise unnecessary.

Runtime backend

The agent’s container runtime is pluggable. Docker is the current backend, and Kubernetes is planned. See Agent Types.