---
title: Multi-Node Management
description: Connect multiple Sencho instances and manage all your servers from a single dashboard.
---

Sencho's multi-node feature lets you manage Docker Compose stacks on multiple servers - all from the same browser tab. Each server runs its own Sencho instance, and your primary instance acts as a transparent proxy to the others.

<Frame>
  <img src="/images/multi-node/node-manager.png" alt="Node Manager showing a local and a remote node, both Online" />
</Frame>

## How it works

There is no central server. Each Sencho instance manages its own host independently. When you select a remote node, your browser's API calls are proxied through your local Sencho instance to the remote one, authenticated by a long-lived Bearer token. No SSH. No shared Docker sockets.

## The local node

Your primary Sencho installation is always listed as **Local**. It is the default node, marked with a star, and cannot be deleted. All operations on the local node run directly against the host's Docker socket.

## Adding a remote node

### Step 1: Generate a token on the remote machine

On the **remote** Sencho instance (the server you want to add), open **Settings → Nodes** and click **Generate Token**. Copy the generated token - you'll only see it once.

<Note>
  The token is a long-lived JWT scoped to `node_proxy`. Anyone with this token can fully control that Sencho instance, so treat it like a password.
</Note>

### Step 2: Add the node on your primary instance

On your **primary** Sencho instance, open **Settings → Nodes** and click **+ Add Node**. Fill in:

| Field | Description |
|-------|-------------|
| **Name** | A display name (e.g. `prod-server`, `media-box`) |
| **Type** | Select **Remote** |
| **Sencho API URL** | The full HTTP/HTTPS URL of the remote instance (e.g. `http://192.168.1.20:3001`) |
| **API Token** | The token you generated in Step 1 |

Click **Create**. Sencho immediately tests the connection and shows the result.

### Step 3: Verify connectivity

A successful connection shows the remote node as **Online** with a green badge. If it shows **Offline** or **Unknown**, check:
- The remote Sencho instance is running and reachable from your primary host
- The API URL is correct (include the port if non-standard)
- The token was copied correctly without extra whitespace

Click the **wifi icon** (test connection) on any node row at any time to re-check status.

## The 1:1 path rule for remote nodes

The Compose directory path matters on remote nodes too. When you register a remote node, its `COMPOSE_DIR` is whatever that remote instance was configured with. Make sure the remote Sencho's `COMPOSE_DIR` follows the [1:1 path rule](/getting-started/configuration#compose-directory-the-11-path-rule) on that remote host.

## Switching between nodes

The **node switcher** dropdown in the top-left of the sidebar shows the currently active node. Click it to switch to any registered node. All views - dashboard stats, stack list, editor, resources, logs - immediately reflect the selected node.

<Frame>
  <img src="/images/multi-node/node-manager.png" alt="Node switcher dropdown and node list" />
</Frame>

Node status indicators:

| Indicator | Meaning |
|-----------|---------|
| Green dot | Node is reachable and responding |
| Red dot | Node is unreachable |
| Gray dot | Status not yet checked |

## Editing and deleting nodes

Click the **pencil icon** on any remote node row to edit its name, URL, or token. Click the **trash icon** to remove it. The local node cannot be edited or deleted.

## Security considerations

- Node tokens grant full control over the remote Sencho instance. Rotate them if compromised via Settings → Nodes → Generate Token (the old token is invalidated).
- Use HTTPS between instances in production to prevent token interception.
- The host console and container exec terminals are blocked for node-proxy tokens - interactive shell access always requires a real browser session on that instance.
