The TurboV Agent System

An in-depth guide to the TurboV Agent daemon, its security model, filesystem layout, and self-update engine.

1. Role of the Agent

The TurboV Agent is a lightweight daemon that runs on your server. It acts as the local executive arm of the TurboV platform:

  • Maintains an outbound persistent WebSocket connection to the backend.
  • Executes Docker actions (build, run, restart, stop, delete).
  • Configures Traefik reverse proxy routes dynamically.
  • Manages local SQLite state cache.
  • Streams live container logs and host telemetry.
  • Manages managed database lifecycles and backup streams.

2. Host Filesystem Hierarchy

All TurboV agent files and directories follow strict Linux Filesystem Hierarchy Standards (FHS):

/opt/turbov/
  └── bin/
        └── turbov-agent                  # Executable daemon binary

/etc/turbov/
  └── config.json                         # Agent identity, server URL, tokens

/var/lib/turbov/
  ├── agent.db                            # Local SQLite cache & task queue
  ├── builds/                             # Ephemeral build contexts & git clones
  ├── applications/                       # Container volume storage
  │     └── <app_id>/volumes/<name>/
  └── traefik/
        ├── traefik.yml                   # Static Traefik configuration
        ├── acme.json                     # Let's Encrypt TLS certs (chmod 0600)
        ├── fallback/                     # Nginx fallback maintenance site
        └── dynamic/                      # Hot-reloaded routing manifests
              ├── <app_id>.yml
              └── _fallback.yml

/var/log/turbov/
  ├── agent.log                           # Agent process output
  └── build.log                           # Compilation & container build logs

3. Zero-Inbound Security Model

Traditional server management solutions require exposing port 22 (SSH) or custom API ports to the public internet, leaving servers vulnerable to port scanning and brute-force attacks.

TurboV eliminates this vulnerability entirely:

  1. Outbound Only: The agent connects outward to the TurboV control plane over HTTPS/WSS (port 443).
  2. Mutual Authentication: Connections are authenticated using an HMAC secret versioning token established during initial server provisioning.
  3. Session Persistence: If the connection drops due to network blips, the agent employs an exponential backoff reconnect strategy with jitter.
  4. No Public Agent Port: The agent does not bind to any external TCP or UDP ports on the host.

4. Systemd Service Management

The agent is installed and monitored as a standard Linux systemd service named turbov-agent:

# Check service status
sudo systemctl status turbov-agent
 
# Inspect live agent logs
sudo journalctl -u turbov-agent -f -n 50
 
# Restart the daemon
sudo systemctl restart turbov-agent
 
# Stop the daemon
sudo systemctl stop turbov-agent

5. Cryptographic Self-Update Engine

TurboV agents update automatically without requiring manual SSH intervention:

  1. Version Polling: The agent periodically queries the release registry for updates according to its configured channel (stable, beta, or dev).
  2. Signature Verification: Every new binary release is signed using an Ed25519 private key. Before executing any update, the agent validates the cryptographic signature using the embedded public key (updater-public.pem).
  3. Atomic Replacement:
    • Downloads the new binary to /opt/turbov/bin/turbov-agent.tmp.
    • Runs a self-check test (--version).
    • Atomically renames turbov-agent.tmp to turbov-agent using rename().
  4. Automatic Rollback: If the new binary fails to establish a healthy connection within 90 seconds, the agent rolls back to the previous binary and alerts the control plane.

6. Log Forwarding & WebSocket Backpressure

The agent streams runtime container stdout and stderr to the dashboard in real time:

  • Docker Multiplexing: The agent attaches directly to the Docker engine log stream using the Docker Engine API.
  • Bounded Queues: Log lines are buffered in memory using a bounded ring buffer (BoundedSet / circular queue).
  • Backpressure Handling: If a dashboard client experiences slow network bandwidth or disconnects, the agent drops non-critical historical lines to ensure host memory usage remains strictly bounded ($\le 50\text$).