sencho/docs/features/multi-node.mdx

---
title: Multi-Node Management
sidebarTitle: Multi-node
description: Connect multiple Sencho instances and manage every server from one console with no central server, no SSH, and no shared Docker sockets.
---

Sencho's multi-node feature lets you operate Docker Compose stacks on every server you run from a single browser tab. Each server runs its own Sencho instance and the control instance acts as a transparent proxy to the others.

<Frame>
  <img src="/images/multi-node/node-manager.png" alt="Settings · Infrastructure · Nodes panel showing the masthead breadcrumb, SCOPE/NODES/REMOTE stat strip, Add node button, Generate Node Token card, and a populated table of one Local row plus three Proxy-mode remote rows." />
</Frame>

## How it works

There is no central server. Each Sencho instance manages its own host independently. When you select a remote node from the switcher, your browser keeps talking to your control instance; the control instance forwards the call to the remote one, authenticated by a per-node bearer token in Distributed API Proxy mode or by the enrolled outbound tunnel session in Pilot Agent mode. No SSH. No shared Docker sockets. No remote Docker TCP exposure.

Remote nodes connect in one of two modes. Pick the one that matches your network topology before you add the node, because the add-node flow branches on the choice.

<Note>
  Adding, editing, removing, and testing nodes, and generating a node token, require an administrator account.
</Note>

## The local node

Only one local node can exist per Sencho instance. The local node cannot be deleted because each instance must retain its own Docker engine identity. All operations on the local node run directly against the host's Docker socket.

If multiple local nodes exist from an older version, the extra rows show a Delete action so you can clean them up. Deleting a local node removes its schedules, labels, dossiers, findings, and other node-scoped data; containers and compose files on the host are not affected. The last remaining local row hides Delete because it cannot be removed.

## Choose a remote mode

When you add a remote node, the Mode picker offers two options. The form tells you the difference inline:

> Pilot Agent requires only outbound HTTPS from the remote host. Distributed API Proxy requires the remote host to expose an inbound port. Sencho Mesh works with both modes.

| | Pilot Agent (default) | Distributed API Proxy |
|---|---|---|
| **Direction** | Remote dials the control plane (outbound only) | Control plane dials the remote (inbound to remote) |
| **Network requirement** | Outbound HTTPS to the control instance | Inbound TCP port reachable from the control instance |
| **What you run on the remote host** | A generated Compose file, brought up with `docker compose up -d` | A full Sencho install reachable on a routable URL |
| **Token model** | One-shot enrollment token, 15-minute expiry | Long-lived bearer token, rotates on regeneration |
| **Best for** | Hosts behind NAT, dynamic IPs, restrictive ingress, edge boxes | Servers you already expose on a stable URL with TLS termination |

If you are not sure, start with **Pilot Agent**. It is the default because it works in more network shapes and the enrollment is a single Compose file.

For a deep look at how the pilot tunnel works under the hood (credential lifecycle, security model, resource limits, environment variables, and pilot-specific troubleshooting), see [Pilot Agent](/features/pilot-agent). Cross-node container networking (reaching a meshed service on any node by hostname) rides the same authenticated channel and works in either mode; see [Sencho Mesh](/features/sencho-mesh).

## Add a remote node: Pilot Agent

### Step 1. Open the Add node form

On the control instance, click your avatar in the top-right and choose **Settings**. In the sidebar pick **Infrastructure → Nodes**, then click **Add node**.

<Frame>
  <img src="/images/multi-node/add-node-pilot.png" alt="Add remote node modal with Type set to Remote and Mode set to Pilot Agent. The form shows Name, Type, Mode, Mode helper text, and Compose Directory fields. URL and token fields are hidden because Pilot Agent does not need them." />
</Frame>

| Field | Notes |
|-------|-------|
| **Name** | A display name (e.g. `staging-vps`, `media-box`). Visible in the switcher and across the UI. |
| **Type** | Set to **Remote**. |
| **Mode** | Set to **Pilot Agent**. |
| **Compose Directory** | The absolute directory where compose stack folders live on the remote host. Pilot Agent defaults to `/opt/docker/sencho` and mounts the directory at the same path inside the agent so relative stack bind mounts remain host-correct. |

Click **Add node**.

### Step 2. Deploy the agent on the remote host

A modal opens with a generated Compose file and a start command.

<Frame>
  <img src="/images/multi-node/pilot-enroll.png" alt="Enroll the pilot agent modal with two steps. Step 1 shows a generated compose.yaml with SENCHO_MODE=pilot, SENCHO_PRIMARY_URL pointing to the control instance, and a SENCHO_ENROLL_TOKEN. Step 2 shows the docker compose up -d start command with a copy button. The footer reads Expires 14m from now and offers a Copy compose file button." />
</Frame>

Save Step 1's contents as `compose.yaml` on the remote host, then run Step 2's command (`docker compose up -d`) in the same directory as the user that owns Docker. The generated file pulls the `saelix/sencho:latest` image, mounts the host Docker socket, attaches a named volume for the agent's own state so re-enrollment survives a container restart, and starts a container named `sencho-agent` that opens an outbound tunnel back to the control plane.

The enrollment token embedded in the file is **valid for 15 minutes and can only be used once**. If you wait too long, follow the regeneration steps below.

### Step 3. Verify the tunnel

Back on the Nodes table, the new row shows **Status: Online** once the agent dials home, and the Endpoint column reads `tunnel (seen Xs ago)`. Until the agent connects for the first time, the Endpoint reads `tunnel (waiting)`.

### Re-enrollment

If the enrollment token expires, the container is removed, or the host is rebuilt, click the **Edit Node** icon on the pilot row. The Edit modal shows a **Regenerate enrollment token** card.

<Frame>
  <img src="/images/multi-node/edit-pilot-regenerate.png" alt="Edit node modal for a Pilot Agent node. Below the Compose Directory field a bordered card explains: 'Re-enroll the agent if the container was lost or the enrollment token expired. The previous tunnel is disconnected automatically.' A Regenerate enrollment token button sits below the explanation." />
</Frame>

Click the button to mint a fresh enrollment Compose file. The previous tunnel is disconnected automatically; save and deploy the new file on the remote host the same way (`compose.yaml`, then `docker compose up -d`) to reconnect.

## Add a remote node: Distributed API Proxy

### Step 1. Generate a long-lived token on the remote

On the **remote** Sencho instance (the server you want to add), open **Settings → Infrastructure → Nodes**. Click **Generate Token** in the **Generate Node Token** card and copy the token that appears.

<Frame>
  <img src="/images/multi-node/generate-token.png" alt="Generate Node Token card showing the explanation text and a freshly issued JWT-style token displayed in a monospace block with a copy button." />
</Frame>

<Note>
  The token is a long-lived credential that grants full control over that Sencho instance. Treat it like a password. Generating a new token invalidates the previous one.
</Note>

### Step 2. Add the node on your control instance

Open **Settings → Infrastructure → Nodes** on the control instance and click **Add node**. Set Type to **Remote** and Mode to **Distributed API Proxy** to reveal the URL and token fields.

<Frame>
  <img src="/images/multi-node/add-node-proxy.png" alt="Add remote node modal in Distributed API Proxy mode. The form shows Name, Type, Mode, Sencho API URL with a plain-HTTP warning banner underneath, API Token (masked), and Compose Directory. The HTTP warning recommends HTTPS or a VPN when the node is reachable over the public internet." />
</Frame>

| Field | Notes |
|-------|-------|
| **Name** | A display name shown in the switcher. |
| **Type** | **Remote**. |
| **Mode** | **Distributed API Proxy**. |
| **Sencho API URL** | The full URL of the remote Sencho instance, including scheme and port (e.g. `https://sencho.example.com` or `http://10.0.1.20:1852`). |
| **API Token** | The token you copied in Step 1. |
| **Compose Directory** | The root directory where compose stack folders live on the remote host. |

If the URL starts with plain `http://`, the form shows an inline warning. Plain HTTP is fine on a private network or VPN, but it leaks the bearer token over any path you do not control. See [Transport encryption](#transport-encryption) below.

Click **Add node**. Sencho immediately tests the connection and shows the result.

### Step 3. Verify connectivity

Click the **Test Connection** icon on any row to re-check status. A successful test shows a Connection Details panel below the table with the remote's OS, architecture, container count, and Sencho version.

If the row shows **Offline** or **Unknown**, see [Troubleshooting](#troubleshooting).

## Switching between nodes

The **node switcher** sits at the top of the sidebar and acts as a persistent identity anchor. It shows the active node's status dot, a `Node · LOCAL`, `Node · REMOTE`, or `Node · AGENT` kicker, and the node name, so you always know which node you are operating on.

When two or more nodes are registered, clicking the switcher opens a popover listing every connected node. Each row shows a status dot, the name, and a metadata line that joins the type chip, the last-seen timestamp (pilot agents only), and the node version with middle-dot separators (for example, `AGENT · SEEN 13H AGO · v0.76.3`). The active node is marked with a brand-coloured rail, and a filled star calls out the default node.

<Frame>
  <img src="/images/multi-node/node-switcher-dropdown.png" alt="Node switcher popover with a Connected header above a 4 NODES count. The Local row shows LOCAL · v0.95.0 with a star icon. Three Remote rows show the REMOTE chip. A Manage nodes link sits at the bottom." />
</Frame>

Click any row to switch. All views (dashboard, stack list, editor, resources, logs) immediately reflect the selected node. The **Manage nodes** link at the bottom of the popover opens the Settings → Nodes panel to add, edit, or remove nodes.

## What top-level views show when a remote node is active

Top-level views that manage fleet-wide state are scoped to the local hub and are hidden from the nav strip when a remote node is the active selection. They reappear automatically when you switch back to your local node.

| View | Why it is hub-only |
|------|--------------------|
| **Fleet** | Manages your node registry and cross-node topology; only meaningful from the hub. |
| **Schedules** | Schedules are dispatched from the hub to target nodes. |
| **Audit** | Audit history is centralized on the hub. |
| **Logs** | Aggregates logs across the fleet. |
| **Auto-Update** | Compares image versions across all nodes in your fleet. |

Node-level views (Home, Resources, Networking, App Store, Console, the editor) work as expected against whichever node you have selected.

## The Nodes table

The Nodes table surfaces routing, status, and per-node automation at a glance for every node:

<Frame>
  <img src="/images/multi-node/nodes-table-overview.png" alt="Nodes table close-up showing the ten columns: a default-marker column with a star on the Local row, Name, Type, Mode, Endpoint, Status, Labels, Schedules, Updates, and Actions. The Local row shows Endpoint 'docker.sock' and an Auto updates badge. Three Proxy-mode remote rows show full URLs in the Endpoint column." />
</Frame>

| Column | What it shows |
|--------|---------------|
| **Default** | A filled star marks the default (Local) node. The column has no header. |
| **Name** | A globe or monitor icon followed by the display name. |
| **Type** | `Local` or `Remote` badge. |
| **Mode** | `-` for the local node; `Proxy` or `Pilot Agent` badge for remotes, with an icon matching the mode. |
| **Endpoint** | `docker.sock` for local; the full Sencho API URL for proxy nodes; `tunnel (seen X ago)` or `tunnel (waiting)` for pilot agents. |
| **Status** | `Online`, `Offline`, or `Unknown` badge. |
| **Labels** | Per-node label palette. The cell shows the label picker; an empty cell reads `No labels` with an Add label control. |
| **Schedules** | Number of active scheduled tasks targeting this node, plus a `next X` countdown to the next run. Click the count or the calendar icon in the Actions column to filter the Schedules view to that node. |
| **Updates** | `Auto` if at least one enabled `Auto-update Stack` or `Auto-update All Stacks on Node` schedule targets the node; `Off` otherwise. A pulsing dot and count appear when stacks have pending image updates. |
| **Actions** | **View Schedules**, **Test Connection**, **Edit Node**, and **Delete Node** icon buttons. The last local row hides Delete because the local node cannot be removed. When multiple local nodes exist from an older version, the extra rows show Delete so you can clean them up. |

Clicking the schedules-link icon opens the Schedules view filtered to the selected node. From there you can create, edit, or manage scheduled tasks scoped to that node. The filter bar shows which node you are viewing, with a Clear filter control to return to the full list.

When a node is deleted, all scheduled tasks and update status data associated with it are cleaned up automatically.

## What Settings apply per node

When you select a remote node in the switcher, the Settings hub filters to the panels that control that specific instance. Values saved here never cross over to other nodes.

| Panel | Scope | Notes |
|-------|:-----:|-------|
| Appearance | Per browser | Theme, density, and navigation preferences are stored in your browser, not on the node. |
| Stacks | Per node | Stack editor, lifecycle workflow preferences, and deploy guardrails for the selected node. |
| Fleet (Settings panel) | Per node | Fleet-snapshot documentation capture for Dossier notes on the selected node. Administrator only. Distinct from the hub-only **Fleet** nav view described below. |
| App Store | Per node | Template registry URL and featured-catalog source for the selected node's catalog. |
| Host Alerts | Per node | Host CPU, RAM, and disk alert thresholds for the selected node. |
| Container Alerts | Per node | Crash, OOM, and healthcheck alert behavior for containers on the selected node. |
| Docker & Storage | Per node | Reclaimable-space alerts and image cleanup after updates on the selected node. |
| Channels | Per node | Discord, Slack, Webhook, and Apprise destinations that fire from whichever node detects the event. |
| Image update checks | Per node | How often the selected node polls registries for available image updates. |
| Labels | Per node | Stack and container label palettes for the selected node. |
| Data Retention | Per node | How long the selected node keeps container metrics, notification logs, scan history, and audit entries. |
| Developer Diagnostics | Per node | Developer mode for real-time metrics streams and verbose debug diagnostics on the selected node. |
| Support | Same everywhere | Diagnostics bundle, docs links, and contact channels; identical regardless of the active node. |
| About | Same everywhere | Build metadata, release notes, and licence attributions; identical regardless of the active node. |

Panels that manage control-plane concerns (Account, Admiral Account, Users, SSO, API Tokens, Nodes, Registries, Recovery Vault, Routing, Mute Rules, Webhooks, Recovery) are hub-only and are hidden when a remote node is active.

## License enforcement across nodes

When the control instance has an Admiral license, all remote nodes inherit that license tier for proxied requests. You do not activate a license on each remote node separately.

### How it works

The control instance asserts its license tier on every proxied request. Remote nodes trust the assertion because it arrives alongside the valid bearer token you configured when adding the node.

This means:

- **Admiral control plane → remote nodes**: Admiral features work on every remote node, governed by the control instance's license.
- **Community control plane → remote nodes**: Admiral features are blocked on remote nodes, even if a remote node has its own Admiral license. The control instance's tier is authoritative for proxied requests.
- **Direct access to a node**: If you load a remote Sencho instance in your browser directly (not through the control plane), it uses its own local license tier.

<Note>
  Remote nodes do not need their own license keys. A single license on the control instance covers every node managed through it.
</Note>

## Editing and deleting nodes

Click the pencil icon on any row to edit its name, URL, token, or compose directory. The API Token field opens blank for security: leave it blank to keep the current token, or paste a new one to rotate it. For a Pilot Agent row, the Edit modal also surfaces the **Regenerate enrollment token** card described earlier.

Click the trash icon to remove a remote node. The local row hides this icon when it is the only local node. When multiple local nodes exist from an older version, the extra rows expose Delete so you can clean them up. Deleting a local node removes its schedules, labels, dossiers, findings, and other node-scoped data; containers and compose files on the host are not affected.

## Security

### Token security

Bearer tokens grant full control over the remote Sencho instance. Treat them like passwords:

- **Rotate immediately** if a token is compromised: open the remote instance's **Settings → Infrastructure → Nodes** and click **Generate Token** to mint a new one. The previous token is invalidated instantly.
- Tokens are **encrypted at rest** in the local SQLite database.
- Tokens cannot be used to open interactive terminals (Host Console or container exec). Interactive shell access requires a signed-in browser session. From the control plane you can open Host Console on a compatible Distributed API Proxy remote; Pilot Agent remotes do not offer Host Console.

### Transport encryption

Sencho delegates transport encryption to your infrastructure rather than implementing TLS at the application layer. This is the same approach used by other self-hosted tools; it avoids certificate management burden while letting you use the encryption layer that best fits your environment.

<Warning>
  **Never send bearer tokens over plain HTTP across the public internet.** A token intercepted in transit grants full control of the remote instance. Use one of the approaches below when nodes communicate over untrusted networks.
</Warning>

There are three recommended approaches.

#### Private network (LAN or VPC)

If all your Sencho instances are on the same local network, VPC, or subnet, HTTP is fine. The token never leaves the private network, so there is no interception risk.

```
http://192.168.1.50:1852   ← safe on a private LAN
http://10.0.1.20:1852      ← safe inside a VPC
```

#### VPN tunnel (WireGuard, Tailscale)

<Tip>
  This is the simplest approach for connecting nodes across the internet. A VPN encrypts all traffic between your servers at the network layer, with no certificate management required.
</Tip>

With a mesh VPN like [Tailscale](https://tailscale.com) or [WireGuard](https://www.wireguard.com/), each server gets a private IP on the VPN. Use those IPs as your Sencho API URLs:

```
http://100.64.0.2:1852     ← Tailscale IP, encrypted by the VPN tunnel
```

All traffic between nodes is encrypted by the VPN. Sencho does not need to do anything additional.

#### Reverse proxy (Caddy, Nginx, Traefik)

If you prefer TLS termination at each node, place a reverse proxy in front of each Sencho instance. [Caddy](https://caddyserver.com/) is the simplest option; it auto-provisions HTTPS certificates from Let's Encrypt with zero configuration:

<CodeGroup>
```text Caddyfile
sencho.example.com {
    reverse_proxy localhost:1852
}
```

```nginx nginx.conf
server {
    listen 443 ssl;
    server_name sencho.example.com;

    ssl_certificate     /etc/letsencrypt/live/sencho.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/sencho.example.com/privkey.pem;

    location / {
        proxy_pass http://localhost:1852;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}
```
</CodeGroup>

Then use the HTTPS URL when adding the remote node:

```
https://sencho.example.com   ← TLS terminated by Caddy/Nginx
```

### Why Sencho doesn't implement application-layer TLS

Some tools auto-generate self-signed TLS certificates between their server and agents. In practice that provides minimal security benefit because the certificates are self-signed with no verification, meaning they do not protect against man-in-the-middle attacks.

Sencho takes the opposite approach: infrastructure-level encryption (VPN, reverse proxy, or private networking) is more robust, easier to manage, and does not impose certificate rotation burden on you. This is the same model used by other self-hosted orchestrators.

## Troubleshooting

<AccordionGroup>
  <Accordion title="A remote node shows Offline">
    Click **Test connection** on the row to re-probe and read the toast. The most common causes are: a wrong URL (missing scheme, missing port, trailing slash typo), a token that was rotated on the remote (any new **Generate Token** invalidates the previous one, so re-issue and update the saved row), and a firewall or reverse proxy that is not forwarding to port 1852 on the remote. Distributed API Proxy mode requires the control instance to reach the remote on the URL you saved; Pilot Agent mode requires the remote to reach the control instance on outbound HTTPS.
  </Accordion>
  <Accordion title="A pilot agent stays on `tunnel (waiting)`">
    The agent has not dialled home yet. Three things can cause this. First, the enrollment token expired (15 minutes from generation): open **Edit node**, click **Regenerate enrollment token**, save the new `compose.yaml`, and run `docker compose up -d` again on the remote host. Second, the `sencho-agent` container exited or never started; `docker ps -a` on the remote will show the exit code. Third, outbound HTTPS to the control instance is blocked, so check the remote's egress firewall or proxy.
  </Accordion>
  <Accordion title="Test Connection fails with 401 Unauthorized">
    The bearer token saved for the row no longer matches what the remote will accept. This usually means somebody clicked **Generate Token** on the remote (which invalidates the previous token) or the row was saved with a typo. Generate a fresh token on the remote, click the pencil icon on the row in the control instance, paste the new token into the API Token field, and save.
  </Accordion>
  <Accordion title="A paid feature is blocked when I switch to a remote node">
    The control instance's license tier is authoritative for proxied requests, so a Community control plane gates Admiral features on every remote, even if the remote itself has its own Admiral license. Activate an Admiral license on the control instance to lift the gate fleet-wide. The reverse case (Admiral control plane, Community remote) works automatically because the control plane's tier is what the remote trusts.
  </Accordion>
  <Accordion title="Settings panels disappear when I switch to a remote">
    That is intentional. Account, Admiral Account, Users, SSO, API Tokens, Nodes, Registries, Recovery Vault, Routing, Mute Rules, Webhooks, and Recovery are control-plane concerns and are hidden while a remote node is selected. Switch back to **Local** from the node switcher to manage them. The full list of which panels are per-node, per-browser, and control-plane-only lives in the [What Settings apply per node](#what-settings-apply-per-node) table above.
  </Accordion>
</AccordionGroup>