Skip to main content
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. 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 AgentKit 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.

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 by status. An agent whose tasks capability has no granted connection says so quietly, with a way to grant one.

Teams

The teams 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; AgentKit 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.

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 when AgentKit 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.
  • 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.
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, AgentKit 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.
Deleting an archived agent for good, with everything it owns, is planned and not yet available.