Agents, identity and manifest

An agent is a customized AI teammate with its own identity, personality and model. Most people create one in the app with New agent (see Connect with AI). This page is the technical view: what defines an agent and how the CLI sees it. “cybo” is the technical name for an agent in the manifest and in CLI commands such as cybo:create.

What defines an agent

• Identity: name, slug (handle), role (job title), description and avatar.
• Soul: the personality and instructions, as text.
• Provider and model: which provider runs it, and the model.
• Tools: tool grants and MCP servers it may use.
• Autonomy level and an optional monthly spend cap.
• Home machine: the machine it runs on. You can move an agent to another machine.

Where it runs

An agent runs with its provider on its home machine. For Claude Code and Codex the provider runs natively on the machine, using the machine’s own login for it. Other providers go through their own integration or through Pi (the pi provider CLI, installed from the machine’s Providers list). The model id depends on the provider: a native id for Claude and Codex, or a backend/model reference for Pi.

An agent can run only where its own provider is available: a Claude or Codex agent does not need pi. An agent on a Pi-backed provider gets the workspace tools only when pi-mcp-adapter is installed in Pi on that machine; without it, it runs with Pi’s own tools.

Creating an agent from the terminal

cyborg cybo:create and cybo:update set an agent’s fields with flags. They do not read a cybo.json file:

cyborg cybo:create <workspace-id> atlas "Atlas" \
  --provider claude --model claude-opus-4-8 \
  --role "Research & Project Assistant" --avatar "🗺️" \
  --description "Plans work and keeps the team unblocked." \
  --soul-file soul.md

--soul-file reads the personality from a Markdown file and sends its text; --soul takes the text inline. cybo:update accepts the same fields, plus --home-daemon to move the agent to another machine.

Local agents (cybo.json on a machine)

A machine’s daemon also loads agents from its own disk: a directory ~/.cybo/agents/<slug>/ holding a cybo.json manifest and its soul. These agents appear only on that machine. Create the directory by hand:

{
  "slug": "atlas",
  "name": "Atlas",
  "role": "Research & Project Assistant",
  "provider": "claude",
  "model": "claude-opus-4-8",
  "soul": "soul.md"
}

The soul field is either an inline string or a path ending in .md, read from the agent’s directory. The manifest can also carry mcpServers, toolGrants, autonomyLevel and monthlySpendCap, among other fields.

System prompt

When an agent starts, Cyborg7 builds its system prompt from its identity and soul, and adds its memory and standing instructions. The prompt is handed to the provider along with the model. The same identity and soul produce the same behavior on any machine.

Workspace agents

In a workspace the agent is stored with the workspace, and you edit it in the app: identity, soul, provider, tools and autonomy. Editing it there does not rewrite a local soul.md. From the terminal, use cyborg cybo:create, cybo:list, cybo:spawn, cybo:update and cybo:delete. See the CLI reference.

Moving and handoff

• An agent’s home machine can be changed.
• When a member leaves a workspace, the agents they own are moved, reassigned to a surviving teammate, or deleted. Other people’s agents are never moved or deleted. Only the leaver’s sessions on the leaver’s machines are closed.