> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agenium.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Add a server node and move a service

> Give an agent a server node on your Coolify, and run one of its services there instead of on your Mac.

> [!NOTE]
>
> Draft: these steps await verification against the current release of Agenium.

**Outcome:** an agent has a server node beside This Mac, one of its services runs on that server, and sessions can run there too.

An agent stays one agent wherever it runs. A node is a place it is set up: This Mac, or a server. Agenium creates a server node as a resource on [its own Coolify](https://docs.agenium.io/recipes/connect-coolify-and-create-instance.md) and keeps it updated.

```mermaid theme={null}
flowchart LR
  agent["Agent"] --> mac["This Mac"]
  agent --> srv["Server node<br/>(on Agenium's Coolify)"]
  svc["A capability's service,<br/>such as automations"] -- "Runs on" --> srv
  sess["Sessions"] -- "Run on" --> mac
  sess -- "Run on" --> srv
```

## What you need

* An agent on This Mac.
* Agenium's Coolify connection in [Settings > Coolify](https://docs.agenium.io/app/settings.md#coolify). If there is none, **Add Node** offers **Create instance** as its first step.
* Enough free memory on one of the Coolify's servers for the node.

## Steps in the app

**1. Start Add Node**

Open the agent's page and choose **Options** (⋯) > **Add Node**. For an agent that already has a **Nodes** section, its last tile does the same.

**2. The server**

Choose the server. When Agenium has no Coolify yet, this step goes through **Create instance**.

**3. Where it runs**

Choose among the servers of Agenium's Coolify; each shows its free memory.

**4. The node's memory**

Set how much memory the node gets.

**5. Sign-ins and services**

Choose the node's sign-ins, such as Claude or Codex and capability connections, and which services move to it.

Steps already settled are checked and passed over, a failed step says why with **Retry**, and closing the sheet keeps where it stood.

**6. Move a service later with Runs on**

To move a service afterwards, open the capability's tile on the agent's page. The view of a capability whose service runs in one place has **Runs on**, a choice of the agent's nodes. Choose the server; it reads **Moving** until the service has started there.

## Steps by command line

Nodes are the capabilities manager's: `capabilities node list` and `capabilities node state` show them, and `capabilities help` gives the full reference.

## Check it worked

1. The agent's page shows a **Nodes** section with **This Mac** and the server. The server's tile carries a green dot while one of the agent's services runs there.
2. The capability's **Runs on** shows the server, no longer **Moving**.
3. **Nodes** in the sidebar lists the server; its page shows the agent and its services.
4. **New**'s menu on the agent's page has a **Run on** section with the server. Start a session there; its row shows a server glyph after the agent's name.

## Common failures

| What you see | Why, and what to do |
| - | - |
| A step fails | It says why. Fix the cause and press **Retry**. |
| **Runs on** reads **Not running** | The service is placed on no node. Choose one. |
| The service does not start on the server | Open the node's page for its log; check the sign-ins the service needs are on the node. |
| **Service Down** notification | A service on the node is not running, or a policy holds it idle. It is withdrawn once the service runs again. |
| The node is red in **Nodes** | It is unreachable, a sign-in does not hold, or it is behind after a database upgrade. Its page offers **Update** when a newer node version is available. |
| The server is greyed in **Run on** | It is unreachable now. Sessions there keep their history readable. |

> [!NOTE]
>
> TODO: verify whether Add Node asks to grant the agent Agenium's Coolify connection. The product's settled design says a node goes through Agenium's own connection with no grant to the agent; an earlier release note said Create asks once and grants it.

## Related

* [Agents: nodes](https://docs.agenium.io/app/agents.md#nodes)
* [Sessions: where a session runs](https://docs.agenium.io/app/sessions.md#where-a-session-runs)
* [Connect Coolify and create an instance](https://docs.agenium.io/recipes/connect-coolify-and-create-instance.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.