> ## Documentation Index
> Fetch the complete documentation index at: https://www.towbar.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Servers
> Register an Ubuntu host, verify its identity, and prepare it for deployments.
A server is a workspace-owned Ubuntu host. Towbar uses SSH to build and run workloads on it. Multiple Repositories can share the same server without duplicating credentials or competing server configurations.
## Requirements
Use a dedicated Ubuntu 22.04 or 24.04 LTS host with root access or a user that has passwordless `sudo`. The worker must be able to reach its SSH port. Restrict access at the network layer and keep the operating system maintained.
Preparation installs or validates Docker Engine 29 or newer with Buildx per-build resource controls, Caddy, `python3`, GNU `timeout`, and the required non-interactive permissions. It checks for at least 1 GiB of available storage under Docker's data directory. Plan additional disk and memory for builds, retained images, and database volumes. Re-run preparation after upgrading Towbar so an older Docker installation is upgraded before the next deployment.
## Register and trust the host
1. Open **Servers → Add server**. Enter the canonical IP, SSH connection, and concurrency settings.
2. Open **Settings → Credentials** and select a stored [SSH key](/docs/ssh-keys). Choose **Add private key** inside the dropdown to create one without leaving the server.
3. Install the public key in the SSH user's `~/.ssh/authorized_keys`, then choose **Save**. Towbar checks the connection and discovers the server's host key.
4. Compare its fingerprint with the server console or another independent, trusted channel before accepting it.
5. Towbar attaches the selected private key only after SSH authentication succeeds. The **Host verified** badge appears in the credentials widget; hover or focus it to see when trust was recorded.
Docker access is root-equivalent. Do not share the deployment account with
untrusted users, and do not approve a changed SSH fingerprint without
investigating why it changed.
Select a stored SSH key under Credentials. Host verified records the server
identity check.
## Prepare the runtime
Choose **Prepare server** from the server's Overview or **Server Preparation** page. The checklist groups connection and host checks under **Server Inspection**, followed by the installation and verification steps under **Prerequisites**. Progress updates automatically; expand a step to see the connection result, inspection findings, installed services, and captured terminal output. Terminal output is redacted and retained up to the most recent 32,768 characters per step. Workloads remain **Server Setup Pending** until preparation succeeds.
Overview shows a preparation prompt before preparation starts or when a failed attempt needs a retry. The full checklist and recorded output remain available under **Server Preparation**, next to Overview in the server sidebar. A yellow warning marks a server that needs preparation; a spinner marks a queued or running preparation. If preparation fails, the failed step opens with its details so you can resolve the issue and retry.
Towbar reuses compatible installations. It does not remove conflicting packages or overwrite an unmanaged Caddy binary. If a step fails, read its output and error before changing the host. Retry after resolving the conflict; use a fresh host when ownership of existing services is unclear.
If the server presents a different host key, Towbar pauses the connection and asks you to verify the new fingerprint. A server rebuild can cause this, but so can an intercepted connection. Update trust only after confirming the new identity independently.
Server Preparation keeps the complete inspection and prerequisites checklist
available after setup finishes.
## Interactive terminal
Admins can open **Terminal** in a server's sidebar and choose **Connect**. Towbar
uses the SSH username, port, private key and trusted host keys configured under
Credentials. The server does not need to be prepared first. If no verified key
is connected, the page links to Credentials.
The shell has the same permissions as that SSH user. Commands run directly on
the host and can change running workloads outside the deployment scheduler.
Use the terminal for inspection and deliberate maintenance; use deployments
and resource operations when Towbar should track and coordinate the change.
A recent sign-in is required. Terminal access is unavailable to Members,
Viewers, personal API keys, team API keys and MCP. Connection tickets expire
after 30 seconds, work once, and are bound to the issuing browser session.
Private keys remain on the API. A changed or untrusted host identity prevents
connection; resolve it through Credentials.
Connections close when you disconnect, leave the page, lose the browser
connection, reach one hour, or provide no input for 15 minutes. Towbar rechecks
session, role, server configuration and credentials every five seconds and
closes the shell when they change. Up to three sessions per user and 20 per API
process are allowed. There is no automatic reconnect or command replay.
Connection open/close events are audited. Towbar does not store terminal input
or output; the remote shell may keep its own history. Terminal output is shown
as received and is not subject to deployment-log secret redaction.
Expose the app and API over HTTPS and allow WebSocket upgrades on
`/v1/terminal` through your reverse proxy. The API process needs network access
to the target's SSH port, in addition to the worker's existing access. The
standard Compose installation has one API process. If you run multiple API
replicas, use connection affinity so the ticket request and WebSocket reach
the same process; restarting that process disconnects its shells.
The local fixture terminal is clearly marked and supports a few demonstration
commands. It does not connect to a target server.
## Set concurrency
`buildConcurrency` limits build work on this host. `previewBuildConcurrency` reserves a bounded share for previews, defaults to 1, cannot exceed the total, and is capped at 4. Production and maintenance work take priority over previews.
Also account for the installation-wide [worker activity limit](/docs/reference/environment-variables#servers-and-worker-capacity). Increasing concurrency consumes real CPU, memory, and disk bandwidth on the target.
## Read capacity and health
The Servers table shows hardware capacity. A server's Apps and Resources sidebar items show configured allocations alongside the latest observed consumption. Known cloud instance types appear below the IP. When only the provider is known, its logo appears beside observed CPU and memory capacity. If metadata is unavailable, Towbar shows hardware capacity or **Unknown Instance Type**.
### Automatic cloud detection
Server checks read the provider's local metadata service. No cloud account API key is required.
| Provider | Displayed information |
| ----------------- | ------------------------------------------ |
| AWS | Instance type |
| Google Cloud | Machine type |
| Azure | VM size |
| Oracle Cloud | Shape, including flexible shapes |
| Akamai / Linode | Instance type |
| Alibaba Cloud ECS | Instance type |
| Hetzner Cloud | Provider logo with observed CPU and memory |
| DigitalOcean | Provider logo with observed CPU and memory |
Hetzner and DigitalOcean do not expose an exact plan name through the metadata endpoints Towbar uses. Towbar does not guess one from CPU or RAM. Other providers and dedicated servers still show observed hardware capacity.
Detection is best effort: blocked, unsupported, or slow metadata does not fail a server check. Run **Check server** after upgrading to refresh the provider information.
Capacity comes from server checks. A displayed value is an observation, not a guarantee that the host is reachable at that instant. Check its timestamp and the latest check result during an incident.
Host capacity, connection details, and recent operations appear on the
server Overview.
For public routes, continue with [Domains and TLS](/docs/domains-tls). For private database access, see [Resources](/docs/resources#connect-privately).
## Clean up leftover workloads
Deleting a repository removes its imported inventory and history from Towbar. It does not stop running services or delete Docker data. Choose **Check server**, wait for a successful check, then open **Settings → Cleanup** to review leftover containers, images, and volumes.
Towbar retains workload ownership separately from repositories. Cleanup lists only objects whose ownership is known to this server. Existing installations recover ownership from retained server-check history; objects with no surviving ownership evidence are excluded.
Container and image cleanup is separate from permanent volume deletion. Towbar checks ownership and current release references again before removing each selected object. Objects that are now in use are skipped. Volumes are never deleted automatically.
## Remove a server
Admins can remove a server from **Danger zone → Remove server**, including a server still referenced by app and resource manifests. Active checks, preparations, deployments, resource operations, and vulnerability scans must finish first.
Removing a server stops Towbar management and scheduled checks, archives its assigned inventory, deletes its stored SSH and Cloudflare credentials, revokes its trusted host keys, and closes remaining Preview records. It does not terminate the cloud instance, stop services, or erase Docker data.
When a later Repository sync finds the same IP in a manifest, Towbar restores the archived server automatically in **Server Setup Pending**. Configure credentials and verify host-key trust again before preparing it. During that first preparation, Towbar makes a best-effort attempt to remove old Towbar-managed app containers for the restored manifest inventory. Resource volumes and other data are not removed. Historical records and workload ownership remain available.
## Scout Agent
Enable opt-in 30-second host and container reporting in **Settings → Scout Agent**. Scout Agent starts after reboots, uses a bounded local buffer, and retains history for 15 days by default (up to 60). See [Scout Agent](/docs/scout) for setup, charts, retention, and removal.
