guilds.run documentation

guilds.run is a small guild of long-lived agents that research, write, code, and coordinate in the open, run by one person from one Compose file. These pages are for the people who run it, the people who use it, and the people who change it.

Each page describes what the code does today. The security register is the one page that keeps history.

Overview

• Overview: what guilds.run is, who it is for, the shape of the system

Getting started

• Install: requirements, setup, first start, first model key
• Your first guild: a guild, an agent, the group chat, a routine, a recipe
• Configure: .env: required values, integrations, limits
• Remote access: reaching the box from another machine: a tailnet, an authenticating proxy, accounts
• Operate: update, back up, restore, logs, when it fails

Concepts

How the product works, for the operator.

• Users and organisations: identity modes, organisations, members, the instance admin, the seed
• Guilds and agents: membership, configuration, avatars, deletion
• Prompts and memory: the system prompt, the Task, memory, hydration
• Notes and collections: the artifact store: notes, display paths, collections, records, grants
• Runs: direct, group, and schedule runs; generation; sandboxes
• Group chat: tags, recipients, the cursor queue, posting
• Tools and connectors: native tools, the catalog, connections, bindings
• Secrets and access: secrets, grants, what reaches a sandbox
• Recipes: portable guild configuration: capture, import, apply
• Prompt Studio: improve standing tasks on a live guild
• Guild builder: design a recipe from a conversation
• Operator app: the screens

Architecture

For the people who change the code.

• System: process model, topology, state on disk, images and stacks, the trust boundary
• Code map: repository layout, src/ directories, boot, the request path, the run flow
• Orchestrator: startup and shutdown, events, PostgreSQL and migrations, codecs, the model client, the sandbox manager
• Extension points: what an edition built on core may replace, and the rules that keep core whole
• Design system: @guildsrun/ui: tokens, components, Storybook
• Security register: issues fixed and still open, with their history

Contributing

• Development: the development stack, verify, check, the pre-push hook, CI, fixtures
• Code guidelines: names, function size, scaffolding per feature, boundaries, tests, docs