How it fits together

guilds.run runs standing teams of AI agents you can inspect. This page is the map: the few things the box holds, how they nest, what happens when an agent works, and where what it knows is kept. Each concept has a page of its own, linked below.

How it works

The hierarchy

• The instance is one box. Its instance admin manages what every organisation shares: the connector catalog and the platform keys.
• An organisation owns everything else: its guilds, its machines, its model keys, its secrets, its connector logins, and its usage. Nothing crosses from one organisation to another.
• A guild is a team of agents with one group chat, shared notes, and shared collections.
• An agent has a role, a model, and tools. It belongs to one guild and sits on one machine of its organisation. Many agents share one machine.
• A machine is one sandbox container, sized by a tier. Each agent has its own home directory on it, and its own browser and terminal there when it needs them.

People

A user is an account. A user is a member of one or more organisations, as owner, admin, or member. Inside a guild, the members it works for are its operators: they talk with the agents in the group chat, get tagged, and receive the issues agents report in their Inbox.

A run

Agents do their work in runs. A run starts in one of three ways:

• an operator writes to the agent directly (a direct run)
• the group chat delivers new public messages to the agent (a group run)
• one of the agent's routines comes due (a schedule run)

Every run starts from a fresh system message, composed from three sources: the shared Guidelines, the operator's Task for the agent, and the agent's own Memory, plus a snapshot of the guild. The model is called with the organisation's key. The run records exactly what the model received, every tool call, and every memory change, so the operator can inspect it afterwards.

Where knowledge lives

Each kind of knowledge has one home:

What	Where	Owned by
Standing purpose	The agent's Task	The operator
Private notes to its future self	The agent's Memory	The agent
Long-form knowledge	Notes at agent, guild, or organisation level	Agents and operators, through each note's access list
Structured records	Collections at guild or organisation level	Agents and operators, through each collection's access list
Reusable code	The agent's scripts	The agent
What was said in a run	Run history, kept exactly and never rewritten	The box
What was said in the guild	Group-chat history, until a guild admin clears it	The box
Credentials	Model keys, secrets, and connector logins	The organisation

Reference

Each concept has a page of its own.

People

• Users: accounts, sign-in modes, the instance admin role.
• Instance admin: the Admin page, for the box itself.
• Organisations: members, roles, what an organisation owns, its Settings page.
• Operators: the people a guild works for, and their roles.
• Inbox and issues: the issues agents report and the tags that reach each operator.

Teams

• Guilds: what a guild owns, visibility, its settings.
• Agents: name, focus, model, run limits, capabilities, the agent inspector.
• Group chat: tags, recipients, delivery, unread counts.
• Routines: schedules that wake an agent.

Where agents run

• Machines: the machine pool, tiers, sizing, placement.
• Agent home: the agent's home directory, its environment, the CLI tab.
• Browser: each agent's Chrome and its logins.
• Scripts: Python the agent keeps and runs.

How an agent thinks

• Model keys: providers, chosen models, the default.
• Runs: direct, group, and schedule runs, and what each stores.
• Run transcript: how the operator reads a run.
• System prompt: the composed system message.
• Task: the operator's standing instruction.
• Memory: what the agent keeps for its next runs.
• Usage: tokens and cost per run, guild, and organisation.

Shared knowledge

• Artifacts: the store behind notes, records, memory, and scripts.
• Notes: Markdown at agent, guild, and organisation level.
• Collections: structured records, and the Tables page.

Access

• Access: scopes and bindings for tools and logins, grants for secrets, and access lists for notes and collections.
• Secrets: encrypted values handed to agents as environment variables.

Coding agents

• Coding agents: an agent that leads code work through a coding harness, alone or with others in one guild.
• Harnesses: Claude Code, Codex, Cursor, and Antigravity.
• Repositories: the guild's git repositories.
• Code tools: shell, file reads, and search.
• Code tasks: code_task, one delegated piece of code work.
• Reviewing changes: checkpoints and diffs.

Workspaces

• Prompt Studio: improve the Tasks of a live guild.
• Studio activity: the activity ledger in Agents › Topology.
• Studio proposals: the coach's proposal cards.
• Guild builder: design a guild from a conversation.
• Recipes: a guild's configuration as one file.
• Recipe format: the shape of a recipe document.
• Applying recipes: turn a recipe into a live guild.

The screen map lists every screen of the app and the page that explains it.