> ## 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.

# Agents

> Your agents: their identity, capabilities, routines and automations, environment and vault, the nodes they run on, and how they leave.

An agent is a record in your shared database: its name, description, icon and id, its settings and its grants. A folder on a Mac, or a server, is one of its **nodes** - a place where it is set up and runs. The agent stays one, however many nodes it has.

## The agents list

The **Agents** section lists every agent your database holds, not only those set up on this Mac. One control at the top switches between four presentations, kept across launches:

* **List** and **Grid**: small cards with the agent's icon, name, and counts - enabled capabilities, routines, automations and sessions, each explained on hover. A softly pulsing green dot marks an agent with a session working now.
* **Pills** and **Bubbles**: a cloud you pan by dragging and zoom with the wheel, a pinch or the zoom buttons. Each agent's size follows how much it is used - its sessions in the last 30 days, the last 7 days, or Equal - and the most used gather at the centre.

On a card, while the pointer is over it, a compact **New** starts a session with the agent. An **Onboarding** tag marks an agent whose onboarding is unfinished. The **Add agent** card creates one; see [Your first agent](https://docs.agenium.io/first-agent.md#add-more-agents).

An agent with no node on this Mac is marked as not here. **Materialize** asks for a folder on this Mac, registers it as the agent's node there, and lays the files its sessions need. Talking to an agent needs it on this Mac or on one of its servers; an agent running elsewhere can still be managed.

## The agent's page

The page shows the agent's identity - its icon, name and description, edited in place: click the name or description and type, Enter applies it. Pick an icon image and crop and zoom it before it is saved.

Its top bar holds:

* **New**, a split button that starts a session in the agent's folder in Claude or Codex.
* **All sessions**, which opens Sessions filtered to this agent.
* **Options** (⋯): **Show Context File**, which shows the context the agent's sessions receive, with **Regenerate**; **Add Node**; **Archive**; and, last, **Remove agent**, which removes the agent from Agenium only and leaves its folder and files on disk.

### Capabilities

Every capability the agent can use shows as a tile, grouped into **Capabilities** and **System capabilities**. A tile shows the capability's icon, name and counts, such as connections or automations. A capability switched off for this agent stays in its place, muted, with **Off**. A green dot on the icon means its service runs and its health check finds no problem; red means it runs with a problem.

Press a tile to open the capability's view for this agent: its on/off switch for this agent alone, the connections granted to it, its service and its settings. See [Capabilities](https://docs.agenium.io/app/capabilities.md).

### Routines and automations

**Routines** are the agent's repeatable procedures. Each tile shows its title, which you can edit, its description, which the agent uses to decide when to run it, and a switch that turns it on or off for this agent.

**Automations** are the scheduled items the agent's capabilities report, each with whether it is active and when it runs, a switch, and a name and description you can edit.

### Tasks

A summary of the agent's [tasks](https://docs.agenium.io/app/tasks.md) by status. An agent whose tasks capability has no granted connection says so quietly, with a way to grant one.

### Teams

The [teams](https://docs.agenium.io/app/teams.md) the agent belongs to and what each adds to its context.

## Secrets

The **Secrets** section has two parts kept apart.

### Environment

The agent's `.env.local` in its folder on this Mac, with a `.env` beside it as a second tab. The section counts its variables and those still without a value, such as a key a capability added as a placeholder. **Edit** opens the file's raw text; **Save** writes exactly that text. If the file changed since you opened it, Save offers to reload instead of overwriting. A warning shows when the file is not ignored by git. A saved change reaches new sessions and the next start of a service; nothing restarts by itself.

### Vault and encryption key

The **Vault** holds the agent's named secrets in the shared database, encrypted with the agent's own key, `AGENT_ENCRYPTION_KEY`. The key lives only in the agent's environment - its `.env.local` on a Mac, its environment on a server - never in the database. **Keeping a copy of the key is your responsibility**; Agenium keeps none.

* **Generate key** shows a new key once, as text with Copy and as a QR code, and closes only after you confirm that a copy is saved.
* **Enter key** writes a key you already have.
* **Change key** first says how many vault entries become unreadable, since entries sealed under the old key cannot be read and must be added again.

Each secret is a row: its name, when it changed, the connection that uses it, and its value masked, with ways to reveal, edit in place or delete it. A raw view shows the whole vault as `KEY=value` lines. Without the key on this Mac the names still show but every value action is unavailable, with the reason.

A secret several agents need is a copy in each one's vault. An agent can also ask you for a secret in a session with the [Secret widget](https://docs.agenium.io/app/sessions.md#widgets).

## Nodes

A node is a place an agent is set up: **This Mac** with its folder, or a server with its address. An agent on more than one node shows a **Nodes** section of tiles; a server's tile carries a green dot while one of the agent's services runs there. Each tile's actions sit behind its ⋯ menu.

* **Add Node**, in Options and as the last tile, gives the agent a server node step by step: the server, created through [Create instance](https://docs.agenium.io/recipes/connect-coolify-and-create-instance.md) when Agenium has no Coolify yet; where it runs; its memory; then its sign-ins and which services move to it. See [Add a server node and move a service](https://docs.agenium.io/recipes/add-a-server-node-and-move-a-service.md).
* **Runs on**, in the view of a capability whose service runs in one place, moves that service between the agent's nodes.
* A session can run on any of the agent's nodes; see [Where a session runs](https://docs.agenium.io/app/sessions.md#where-a-session-runs).

**Nodes** in the sidebar lists every node your agents run on, across agents, with a count of those that need attention: unreachable, a sign-in that does not hold, or a service that is not running. A node's page shows every agent on it and their services, and offers **Update** when a newer node version is available.

## Archive and delete

An agent leaves in two stages.

**Archive** stops nothing by itself. When nothing of the agent runs, Agenium asks once and archives it. When something still runs, a pane at the right lists each place - This Mac and each server with its services - each with a **Stop** button, and turns into the confirmation once everything has stopped. An archived agent disappears from every list along with its sessions, tasks and Inbox items; its records, folder and connections stay.

The Agents page's **Archived** button shows archived agents. An archived agent's page offers **Restore**, which brings it back without starting anything.

> [!NOTE]
>
> Deleting an archived agent for good, with everything it owns, is planned and not yet available.


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