# Servers
URL: https://synquic.tech/docs/dashboard/servers.md

Add your own servers over SSH, let Synq install what a deployment needs, and manage each server's health, CPU cores, Docker disk usage and cleanup, rate limiting, and a live terminal.

The **Servers** section is where you connect the machines Synq deploys to. You give Synq SSH access to a
box you already own (a VPS, a bare-metal server, a VM) and it installs and checks everything a deployment
needs (Docker, OpenResty, Git). Once a server is connected, you can pick it as a deploy target from the
[deploy flow](/docs/guides/deploy-from-github) and manage it from its own detail screen.

<Callout title="Where this lives">
The list is at **`/servers`**, adding a server is **`/servers/new`**, and each server's detail screen is
**`/servers/<serverId>`**. For the conceptual walkthrough, see [Deploy to your own server](/docs/guides/custom-servers).
</Callout>

## The Servers list

This screen (**`/servers`**) shows every server you've connected. The header reads **Servers** with the
subtitle "Manage your deployment servers and infrastructure", and an **Add Server** button sits top-right.

Each server appears as a card showing its name (or host if unnamed), a **Connected** / **Error** status pill,
and the `user@host:port` it dials. Click a card to open that server's detail screen.

On the right, a **Quick Info** panel tallies **Total Servers**, **Connected**, and **Errors**.

If you have no servers yet, the empty state explains what an auto-setup configures, with an **Add Your First
Server** button and four cards under "What gets configured":

| Card | What it means |
|---|---|
| **Container runtime** | Runs each app in isolation (Docker) |
| **Reverse proxy** | Routing & SSL (OpenResty) |
| **Monitoring** | Health checks |
| **Git** | Source deployments |

## Adding a server

Press **Add Server** to reach **`/servers/new`**. The page title is **Add Server** with the subtitle "Enter
your server details and choose an auth method", and a **Getting Started** panel on the right lists what you
need: a server with SSH access (Ubuntu, Debian, or similar) and an SSH key or password.

### The SSH Connection form

| Field | Notes |
|---|---|
| **Server Name** | Optional label shown in the list and header. Leave blank to fall back to the host. |
| **Server IP Address** | The host to connect to, e.g. `123.45.67.89`. Required. |
| **Port** | SSH port; defaults to `22`. |
| **Username** | SSH user; defaults to `root`. |
| **Authentication** | Choose **Password**, **SSH Key**, or **Agent** (see below). |

The **Authentication** control is a three-way toggle:

- **Password**: enter the server password.
- **SSH Key**: give a **Key Path** (e.g. `~/.ssh/id_rsa`) and an optional **Passphrase**.
- **Agent**: connects using the host machine's `ssh-agent` (like VS Code); no password or key is entered
  here. The machine running Synq must already have access to the server.

Under **Advanced** you can add a **Jump Host** (e.g. `user@bastion.example.com`) and **Extra SSH Arguments**
(e.g. `-o StrictHostKeyChecking=no`).

Two buttons finish the form:

- **Test Connection**: dials the server with the details you entered and reports success or the failure
  reason, without saving anything.
- **Save & Continue to Setup**: saves the server and moves straight into the component setup flow. (When
  you're editing an existing server, this button reads **Save Changes** instead.)

### The setup flow

After you save a new server, Synq walks you through installing its prerequisites. You first choose how to
run it:

- **Automatic Setup**: checks the requirements and installs everything automatically. One click, and Synq
  handles Docker, OpenResty and Git.
- **Step-by-Step Setup**: review each component and its detailed status before installing.

The flow then moves through **Connect → Check → Install**: Synq opens the SSH connection, runs health
checks, and installs whatever's missing. Progress streams live, per component (Waiting → Installing → Installed,
or Failed), with an expandable **Install Logs** panel. When it finishes you can jump to the server's detail
screen; if anything failed, **Retry Failed** re-runs just those components.

<Callout title="Tip" type="info">
You don't have to get setup perfect here. Every check, install, reinstall, and removal is also available later
from the server's **Components** tab.
</Callout>

## The server detail screen

Opening a server (**`/servers/<serverId>`**) shows its name with a **Healthy** or **Issues** badge and the
`user@host:port` beneath it. Top-right are two controls:

- **Edit**: reopens the SSH Connection form (at `?edit=true`) so you can change connection details.
- The **⋯** menu: holds **Reboot server** (owners and admins, see [Rebooting a server](#rebooting-a-server)) and
  **Remove Server** (see [Editing and removing a server](#editing-and-removing-a-server)).

If Synq can't reach the server, a banner appears above the tabs explaining whether the box is unreachable,
the credentials were rejected, or the config is incomplete, with a **Retry** and an **Edit** shortcut. A
**Connection** panel on the right always shows the current **Host**, **User**, and **Auth** method.

The screen is organized into tabs: **Overview**, **Migrations**, **Components**, **Docker**, **Git auth**,
**Security** and **Terminal**. Each tab has its own address
(`?tab=docker`, for example), so you can link straight to it.

### Overview tab

A live dashboard for the server. Four stat cards show **CPU** (with load averages), **Memory**, **Disk**
(each with a usage bar that turns amber past 70% and red past 90%), and **Uptime**. Below them, a
**Components** card lists each installed component with a **Healthy** / **Unhealthy** marker and version. The
header summary reads "All systems operational" or "\{n} of \{m} unhealthy". See
[Logs & monitoring](/docs/guides/logs-monitoring) for more on reading these signals.

#### CPU cores

The **CPU cores** card shows which projects pin or reserve this server's cores. Each core is drawn as a numbered box:
highlighted when a project **reserves** it exclusively, marked when a project **pins** it, plain when it is free
(hover a box to see who holds it). Under the boxes:

- the number of cores, and which are **Unreserved** when a project holds some exclusively;
- one row per project (or project and service) with its cores and a **Reserved** or **Pinned** badge; click it to
  open the project's resources;
- **Containers**, which lists every Synq container on the server with its current CPU set (**all cores** when it
  isn't restricted).

**Re-apply** updates every Synq container on the server to its effective cores, CPU priority and memory reservation
with `docker update`, without restarting anything. Use it after changing things by hand or when a container shows the
wrong CPU set. Synq's own containers are never restricted, and processes on the host outside Docker can still use
reserved cores. To pin or reserve cores, see [Dedicated CPU cores & reservations](/docs/guides/cpu-reservation).

### Migrations tab

Bring running Docker or Compose deployments that already live on this server into Synq. The tab lists past migration
runs (open one to see its steps and logs) and starts a new scan-first migration. See
[Migrate from Coolify, Dokploy, and Dokku](/docs/guides/migrate-from-coolify-dokploy-dokku).

### Components tab

Manage the software Synq relies on. The **System Health** card lists every required component and, under a
**Detected Infrastructure** divider, any optional ones it found. Each row shows health, version, and a status
message, with per-component actions:

| Action | When it shows | What it does |
|---|---|---|
| **Install** | Component is missing and installable | Installs it. |
| **Reinstall** | Component is already installed | Reinstalls / refreshes it. |
| **Remove** | Component is removable and installed | Uninstalls it (destructive, confirmation required). |

Header buttons let you **Install Missing (\{count})** in one go, or **Re-check** to re-run the health checks.
Installs and removals stream a progress card with component rows and an expandable logs panel, matching the
setup flow.

<Callout title="Removing OpenResty" type="warn">
Removing a component is destructive and can disable related deployment features until you install it again.
Removing **OpenResty** removes the edge container from the server, so your apps' domains on that server stop
answering until you install it again. Certificates and vhosts are left on the host. Use **Reinstall** if you only need to
refresh the edge to the current image.
</Callout>

### Docker tab

**Docker disk usage** shows what fills the server's disk: **Images**, **Containers**, **Volumes** and **Build cache**,
each with its size and how much is reclaimable, and a list per category with the project or stack each item belongs
to. Items Synq depends on carry a protection badge (**Control plane**, **Managed by Synq**, **Project data**, **Kept
for rollback**, **In use**) and are never removed.

Instance administrators also get **Clean up** (choose categories, review the exact list, confirm) and the
**Scheduled cleanup** card, which runs the same cleanup on a schedule across the servers you choose. Full guide:
[Docker disk usage and cleanup](/docs/guides/docker-cleanup).

The **Build for other servers** card has the **Can build for other servers** switch (off by default). Turned on,
projects deployed on other servers can choose this server under **Configuration**, **Build on**: their images are
built here, with their build cache here, and sent to their deploy server over SSH. See
[Build on another server](/docs/guides/build-servers).

### Git auth tab

Choose how this server signs in to GitHub to clone private repositories: a device login, a pasted token, an SSH key
of the server, or per-repository deploy keys. It wins over your account-wide GitHub settings for clones that run on
this server. See [Git authentication](/docs/guides/git-authentication).

### Security tab (connection hostname, rate limiting)

#### Connection hostname

The **Connection hostname** card sets the DNS name that database URLs, **Reachable at** addresses of
published ports and SSH tunnel commands use for this server instead of its IP address, for example
`psql postgresql://app@db.example.com:5432/app` rather than `...@203.0.113.5:5432/app`. Owners and admins
can change it; other members see it read-only. Once set, the **Connection** panel shows it too.

- Enter a DNS name only: no `https://`, no port, no IP address. Synq refuses anything else with the reason.
- Point an **A** record for the name at the server with no proxy (DNS only). Synq uses the name exactly as
  typed and does not check where it points, so a typo shows up as a URL that doesn't connect.
- **Clear** removes it. Without one, the server Synq runs on uses the panel's own domain (or your apps
  domain) when its DNS points straight at the server, and otherwise its IP address. A server you added with
  a DNS name keeps using that name.

Anyone can look the name up and find the server's address, so it is a convenience, not a privacy feature;
the SSH tunnel stays the private way to reach a database. From the command line:
`synq server update <server-id> --public-hostname db.example.com` (`--public-hostname none` clears it). See
[Public ports & database access](/docs/guides/ports#which-host-the-address-uses).

#### Rate limiting

This tab configures **OpenResty request rate limiting** for the server. The core control is **Requests /
second**; Synq derives a **burst** allowance automatically (about 40% of the rate). Open **Advanced** to
switch **Burst mode** to manual and set a custom **Burst allowance**.

**Whitelisted IPs** let you list addresses or CIDR ranges that bypass the limit (loopback `127.0.0.1` and
`::1` are always whitelisted). Type an IP or CIDR and press **Add**.

Save with **Apply rate limit** (first time) or **Save changes** (when one already exists); **Remove rate
limit** clears it, and **Refresh** re-reads the live config from OpenResty. A draft indicator at the bottom
summarizes pending changes before you save.

<Callout title="Needs OpenResty" type="info">
Rate limiting reads and writes the live OpenResty config on the server, so OpenResty must be installed and
reachable. If it can't be read, the tab shows a "Couldn't read OpenResty rate limit config" notice with a
**Retry**.
</Callout>

#### Exposed-port scan

The Security tab also has a **Scan ports** action that lists the ports actually **listening** on the server
and classifies each as **exposed** (bound to a public/all-interfaces address) or **loopback-only** (bound to
`127.0.0.1`, reachable only from the host). Use it to spot anything unintentionally reachable from the
internet (a database that should be loopback-only, a debug port left open) so you can lock it down. It's a
read-only probe (it changes nothing); re-run it after a deploy to confirm only what you expect is exposed.

### Terminal tab

A live SSH shell to the server, right in the browser, running over WebSocket. You can open **up to 3
concurrent** shells in tabs, and text is copied on select. The shell only stays open while this tab is active.

## Rebooting a server

Owners and admins of the organization can restart a machine with **Reboot server** from the **⋯** menu. You
confirm by typing the server's name. Synq sends the reboot over the same SSH connection it already uses for the
server (as root, or through passwordless `sudo`; a login with neither is refused), then shows
**Rebooting… waiting for the server to come back** and checks every few seconds until it answers again
(**back online**), or tells you after 5 minutes that it hasn't. Every app, database and service on the machine
is down until it has started again. The reboot is recorded in the audit log.

**This Server**, the machine Synq itself runs on, needs one more step: tick the box acknowledging that the panel
goes offline too. The panel is unreachable until the machine has restarted, then the page reconnects on its own.
Rebooting it also requires an instance administrator, and it is refused in desktop mode or when host control is
off, because Synq then has no channel to the host's operating system. Over the API, send
`POST /api/system/servers/<serverId>/reboot` with `{ "confirmPanelHost": true }` for this machine.

## Editing and removing a server

To change connection details, press **Edit** on the detail screen (or **Edit** from a single-server list):
this reopens the same SSH Connection form with a **Save Changes** button. When editing, leaving the password
or key blank keeps the stored secret; you only re-enter it when switching auth method.

To disconnect a server, use **Remove Server** from the **⋯** menu. Synq first checks what is deployed there:

- With nothing deployed, removing it deletes its connection settings and stored SSH credentials.
- With projects or apps deployed, they are **removed from Synq** together with the server (their environment
  variables too). By default their containers keep running on the machine and you can import them again later.
  Tick **Also stop and delete them on the server** to stop them, remove them and delete their volumes; this can't be
  undone.
- Mail server configuration, the server's GitHub registration and backup destinations that point at
  it are listed as **Also removed with this server**.
- If Synq itself runs on that server, it stays.

You confirm by typing the server's name.

## Related guides

<Cards>
  <Card title="Deploy to your own server" href="/docs/guides/custom-servers" description="The full walkthrough for connecting a server and deploying to it." />
  <Card title="Docker disk usage and cleanup" href="/docs/guides/docker-cleanup" description="Free disk space safely, by hand or on a schedule." />
  <Card title="Dedicated CPU cores & reservations" href="/docs/guides/cpu-reservation" description="Pin or reserve cores for a project." />
  <Card title="Deploy from GitHub" href="/docs/guides/deploy-from-github" description="Pick a server as the target when you ship a repo." />
  <Card title="Logs & monitoring" href="/docs/guides/logs-monitoring" description="Read CPU, memory, and health signals for your servers and apps." />
  <Card title="Email & webmail" href="/docs/guides/email-webmail" description="Mail management runs against a connected server from the Emails screen." />
</Cards>