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. Add --gpus all for NVIDIA GPU passthrough:

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

Runtime backend

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