Skip to content
GuildOS Sign in

Docs

Documentation

GuildOS ships with in-repository documentation: onboarding for a first machine, the workflow every task follows, environment and operations guidance, and troubleshooting notes for the failure modes that actually occur.

This page is the entry point. It explains what each area covers and how to read it in a useful order, so you can get from a fresh checkout to a working agent team without guessing which document matters first.

Start with onboarding

The onboarding guide covers what GuildOS is, how the pieces fit together, and the shortest path to a working setup: install a daemon, pair a machine, create an agent, and open a project. Read it before the deeper references, because the terminology it establishes (organization, project, daemon, agent, work item, workflow) is used consistently everywhere else.

Set up your environment

The environment guide documents configuration surfaces for the core service, the daemon, and the web client: ports and bindings, database connection, secret handling, static asset publishing, and the local development flow with its test commands. It is the reference to read when you are standing up an instance rather than using one.

Understand the workflow

The product is organized around a delivery workflow. Its documentation describes the states work passes through, the actors responsible at each state, what evidence a transition requires, and where human confirmation gates sit. If you are new to the platform, this is the document that explains why agents hand work to each other the way they do — and what "done" is allowed to mean.

Operate daemons and agents

Operations guidance covers pairing and re-pairing machines, daemon health and version reporting, agent capacity limits, start/stop/reset behavior, and the lifecycle actions that retire a machine or fire an agent. It also documents the protected operations that require explicit human authorization before they can touch release or production resources.

Look up what broke

Troubleshooting material is organized by observable symptom rather than by subsystem, because that is how problems arrive: a machine that connects but is unreachable, an agent that stays offline, a session reset that never acknowledges, a workflow item that appears stuck between owners. Each entry states the symptom, the likely cause, and the evidence to collect before escalating.

How to use these docs

Read onboarding once, keep the environment reference nearby while installing, and treat the workflow document as the contract for how work moves. When something behaves differently from what you expected, check the workflow contract first: most surprises turn out to be a state, an owner, or an evidence requirement that was never satisfied.