An instance stores your configuration and run history. Its projects group repositories; each project’s loops select work for agents. The diagram separates the configuration you set up from the execution of a matching issue or pull request.
Instance
Section titled “Instance”An instance is one installation of usine with its own configuration, credentials, and runtime state, served by an orchestrator. It contains projects, agents, and workers. Its instance folder contains .usine/; an instance repo is a Git repository for bootstrap and configuration import and export files. Start an instance in the quickstart.
Project
Section titled “Project”A project is a named group of managed repositories with one board and the loops that run on them. The registry lists managed repositories, and a repository belongs to at most one project. Operate a project’s board.
A loop belongs to a project and defines a trigger and the agent run to start for each matching item in that project’s repositories. It references one agent from the instance. An item is a GitHub issue or pull request; a trigger can select issues, pull requests, or schedule ticks. Write a loop.
An agent is an instance-level definition of standing instructions and a brain spec: its harness, model, and reasoning effort. Multiple loops can reference the same agent. The harness is the coding-agent CLI, such as Claude Code, Codex, or Pi. Write an agent.
A run is the work for one event of a loop, such as an issue or pull request matching its trigger. A run has one or more attempts when execution starts, one per try. In the UI, a run can wait for approval, queue for a worker, run an attempt, or wait for CI before it closes as succeeded, failed, or canceled. Approve and follow a run.
Attempt
Section titled “Attempt”An attempt is one try of a run’s step, running the loop’s agent on a worker. Retrying a failed run creates another attempt in the same run, with its own transcript of session messages. Retry an attempt.
Worker
Section titled “Worker”A worker is an instance-level machine configuration for running an attempt’s child sessions in a checkout. The default local worker uses the machine and user running usine up; the Pi parent session always runs in the orchestrator. Add a worker to run children on another machine.
Board and task
Section titled “Board and task”A board groups a project’s tasks into lanes. A task groups linked issues and pull requests with their runs; its current item is the issue or pull request shown on the board. A lane maps to GitHub labels or item states, and moving a card changes labels on GitHub. Use the board.
Configuration revision
Section titled “Configuration revision”A revision records a configuration change with its number, actor, time, optional message, and before-and-after values. Later starts read stored configuration; editing the original bootstrap files has no effect until you import them. Change the configuration.