Architecture Overview

The Trailer.dev dashboard showing the hosts list and a deployed workspace, to anchor the server and agent concepts.

Trailer.dev is a self-hostable, container-based development platform. The backend is written in Go. The frontend is a React and TypeScript single-page app served by the server.

Components

There are two backend roles and one web client.

1. Server

   • Handles authentication and authorization.
   • Stores the desired state of hosts, images, and workspaces in the database.
   • Exposes the REST API and serves the web client.
   • Accepts agent registrations and heartbeats, and answers agent reconciliation polls.
   • Enforces workspace access control, including forward-auth for workspace URLs.

2. Agent

   • Runs on a host with a container runtime and reconciles that host against the server’s desired state.
   • Builds images, creates and manages containers, networks, and volumes.
   • Collects host, GPU, and workspace metrics and reports them via heartbeats.
   • Serves interactive sessions (logs, exec, attach, proxy) over a realtime WebSocket.

3. Web client

   • React and TypeScript app served by the server (it is not a separately deployed binary).
   • Provides the dashboard, workspace and image management, and real-time updates.

Deployment modes

Trailer runs in one of three modes. Each is a separate deployment of the same platform:

Mode	Role
Server	API, database, web client
Agent	Host reconciliation
Standalone	Server and agent in one process

See Server Mode, Agent Mode, and Standalone Mode for details.

Component interaction

flowchart LR
    Client["Web client<br/>(React, served by server)"]
    Server["Server<br/>(API + DB)"]
    Agent["Agent<br/>(host reconciler)"]
    Runtime["Container runtime<br/>(Docker)"]

    Client <-->|REST + realtime| Server
    Agent -->|connects, polls for desired state, reports status| Server
    Server -.->|realtime: logs, exec, attach, proxy| Agent
    Agent -->|create / manage| Runtime

Data flow

The agent pulls desired state from the server rather than the server pushing deployments.

1. A user creates or updates a workspace through the web client or REST API.
2. The server validates the request and stores the desired state in its database.
3. The agent polls the server for changes and learns the new desired state.
4. The agent reconciles the host: it builds images and creates or updates containers, networks, and volumes through the runtime.
5. The agent reports status and metrics back through periodic heartbeats. The client sees updates in real time through the server.

Security

• Authentication and role-based access control are provided by the server.
• Workspace URLs are gated by a forward-auth flow so only authorized users can reach a running workspace.
• Containers are isolated per workspace using the runtime’s networks and volumes.
• The agent authenticates to the server with a per-machine registration token.

Runtime backends

The agent’s container runtime is pluggable. Docker is the current implementation. A Kubernetes backend is planned but not yet available. See Agent Types.

Resource management

• Container lifecycle, networks, and volumes managed by the agent.
• NVIDIA GPU detection and passthrough, with GPU metrics collection.
• Persistent storage through runtime volumes.