Install the agent · Docs

The agent is a single binary that runs as a systemd service under its own fwoop user. It connects out to the control plane, runs what your workspace asks it to and reports back.

Requirements

Requirement	Supported
Operating system	Ubuntu 20.04+, Debian 11+, RHEL, Rocky and Alma 8+, Fedora, Amazon Linux 2023, Raspberry Pi OS (64-bit)
Architecture	amd64 or arm64
Init system	systemd
Network	Outbound HTTPS (port 443) to `*.fwoop.dev`
For services	Docker Engine 24+ with the Compose plugin

The agent uses about 30 MB of memory and under 1% CPU when idle.

Install

Get a command with a fresh one-time token from Servers → Connect server, then run it as root:

$ curl -fsSL https://get.fwoop.dev | sh -s -- --token $FWOOP_TOKEN

The installer accepts these options after --:

Option	Description
`--token`	One-time token that links the server to your workspace. Required.
`--name`	Server name in Fwoop. Defaults to the hostname.
`--labels`	Comma-separated `key=value` labels, e.g. `role=api,region=eu`.
`--project`	Project to join. Defaults to the workspace’s default project.
`--proxy`	HTTPS proxy to use for the control-plane connection.

Prefer to read the script first? Download it with curl -fsSL https://get.fwoop.dev -o install.sh and run it once you’re happy. Packages for apt and dnf are listed in the dashboard.

What gets installed

The binary at /usr/local/bin/fwoop
A fwoop system user, added to the docker group
The service fwoop-agent.service
Configuration in /etc/fwoop/agent.yaml and state in /var/lib/fwoop

Check the agent

$ fwoop agent status
connected · agent 2.3.1 · 0 inbound ports · labels: role=api, region=eu
$ journalctl -u fwoop-agent -f

Labels

Labels are how deploys, jobs, backups and alerts find servers. Set them at install time, in the dashboard, or from the CLI:

$ fwoop servers label web-01 role=web region=eu

Updates

Agents update themselves in waves after each release. An update that fails its health check rolls back automatically. To pin a server to its current version, run fwoop agent pin, or set an update window per project in the dashboard.

Uninstall

$ sudo fwoop agent uninstall

This stops the service, removes the binary, the fwoop user and its files, and marks the server as disconnected. Containers you deployed keep running; Fwoop just stops managing them.