Documentation

How Fleet works

Fleet is a lightweight deployment tool for servers you own. This guide covers how the web dashboard, background agent, and security model work together.

Overview

Fleet separates planning from execution. The web dashboard manages your applications, repositories, and team permissions. A lightweight agent binary runs on your server to pull code, run builds, and start processes.

The agent connects outbound to the dashboard over a secure WebSocket channel. You never need to open inbound SSH ports or share server passwords with Fleet.

Agent vs control plane

Agent (on your server)

  • A single lightweight binary (<10 MB) running via systemd
  • Clones your Git repository into an isolated folder
  • Runs your install, build, and start commands
  • Monitors process health and restarts crashed apps
  • Streams build logs and CPU/RAM metrics back to the UI

Control plane (web dashboard)

  • Web UI and REST API
  • Stores application configurations and encrypted secrets
  • Manages workspaces, team members, and permissions
  • Dispatches deploy jobs to connected agents
  • Displays deployment history and real-time logs

Versions

Control plane version: —

Recommended agent version: —

Web UI version: 1.0.0

Architecture

┌─────────────────────────────────────────────────────────┐
│              Control Plane (Dashboard & API)            │
│  - Web Interface          - Team Permissions & Roles    │
│  - Encrypted Secrets      - WebSocket Gateway           │
└────────────────────────────┬────────────────────────────┘
                             │ Outbound WSS Connection
                             │ (Signed WebSocket)
                             ▼
┌─────────────────────────────────────────────────────────┐
│                 Fleet Agent on your Host                │
│  - Clones Git repo        - Runs build & start scripts  │
│  - Manages processes      - Streams logs & metrics      │
└─────────────────────────────────────────────────────────┘

How the agent works

  1. Registration: You run fleet register <token>. The agent pairs with your dashboard.
  2. Outbound connection: The agent maintains a live outbound WebSocket connection to receive jobs.
  3. Deploy pipeline: When you trigger a deploy, the agent clones the commit, runs your install script (e.g. npm install), builds the project, and starts the process.
  4. Process supervision: The agent monitors child processes. If your app crashes, the agent automatically detects it and restarts the service.

Control plane role

The control plane acts as the central coordinator. It does not run your server code. Instead, it coordinates deployments, securely holds your encrypted environment secrets, and routes live logs and telemetry to your browser.

Life of a deploy

1. Trigger

You trigger a deploy from the UI (latest branch tip or pinned commit).

2. Dispatch

Control plane packages the deploy job and sends it to the agent.

3. Pipeline

Agent runs: Clone → Install → Build → Start.

4. Live

Process starts, health is verified, and logs stream to the dashboard.

Security

Security is built-in across the network, server, and storage layers:

Network & access

  • Agent connects outbound only (no inbound SSH ports needed)
  • Every message is verified with digital signatures (Ed25519)
  • Transport sits on HTTPS / WSS encryption

Secrets & storage

  • Environment variables encrypted with AES-256-GCM at rest
  • API masks secrets so values are never visible in plaintext responses
  • Tokens are hidden from logs automatically so secrets are never shown on screen

Boundaries

Fleet handles

  • Deploy orchestration and release history
  • Running your git, build, and start commands
  • Delivering encrypted environment variables
  • Real-time deployment logs and process monitoring

You manage

  • Your VPS hardware and network configuration
  • Host OS, packages, and language runtimes
  • Databases, reverse proxies, and DNS
  • Correctness of your application code

Fleet deploys your code on hosts you manage. System operations stay with you.

How to use Fleet

  1. Prepare your machine — Install Node, Go, Python, or whatever tools your app needs.
  2. Install the agent — Download the agent binary on your VPS and register it with the token from your dashboard.
  3. Configure your app — Add a service pointing to your Git repository and set your install/start scripts.
  4. Deploy & monitor — Click deploy, view real-time build logs, and monitor host health.

Why Fleet instead of a script?

A shell script can clone a repository and start a process, but it doesn't give you a shared team dashboard, live deployment logs, server health metrics, or secure secret storage. Fleet wraps your build commands in a modern deployment UI without locking you into expensive cloud hosting.

  • Clean web dashboard to trigger deploys and check application status without logging into SSH.
  • Live deploy logs & history saved for every release so you can inspect what happened anytime.
  • Team collaboration with workspaces and roles—teammates can deploy without sharing server root keys.
  • Automatic process monitoring that detects crashes and restarts your apps.

FAQ

More help

Download agentInstall commands and binary downloadsSupportContact and troubleshooting helpPlans & pricingHobby $0 plan and workspace limitsStart deployingSign in to your dashboard
Fleet · CP — · Agent — · UI 1.0.0