Facility is an open-source, self-hosted platform for teams working with Claude Code and Codex. Each task keeps a shared conversation, a development environment, and a record of the changes made. People and agents can continue the work, try the running application, and review the pull request.
We call that unit of work a story. Its files, dependencies, and engine sessions stay together when an agent finishes or compute stops. The next turn continues in the same workspace.
How it works · Run it locally · Self-hosting guide · Security model
Facility is early software, built and used by The Agile Monkeys. We publish it so teams
can try the workflow, inspect the code, and help shape the product. APIs, database schemas, and
manifests evolve between 0.x releases. Plan upgrades as explicit migrations with backups.
Start with one evaluation repository and follow the security model when connecting code and credentials. Questions, bug reports, and focused pull requests help us improve the next release.
- Choose the work. Start a story from a GitHub issue or an ad hoc request. Repository-defined agents can also respond to configured GitHub events and schedules.
- Continue with an agent. Facility prepares the repository's development environment and runs the selected Claude Code or Codex agent. People can steer the shared conversation, and later turns can use another agent in the same workspace.
- Check the running result. Run the repository's tests and open an authenticated preview of its declared services. The preview uses the story workspace, including its current files and local data.
- Review and deliver through GitHub. Agents use ordinary Git and GitHub commands to commit, push, and open pull requests. Required checks, reviews, and branch protection enforce your repository's merge policy.
- Keep the work available. Merge marks the story done and suspends compute. Archive and suspend also retain the workspace. Only explicit workspace deletion removes its durable files and engine sessions.
The story timeline brings together messages, agent turns, Git changes, pull requests, reviews, and checks. Project views expose recorded model and workspace costs, budgets, and operational activity. MCP and the web application work with the same stories and lifecycle controls.
Two contracts live in your repository: .facility.yml
defines setup, services, and readiness; .agents/*.md
defines agent instructions, engines, models, and triggers. The kickstart pull request creates both.
The project manifest also lets you choose CPU and memory for new story workspaces.
You need Docker, Node.js 24 LTS, and pnpm 11.20.0. Node.js 22 is also supported from 22.13.0. Start the application locally, then connect a repository to run Claude Code or Codex in a story workspace.
git clone https://github.com/theam/facility.git
cd facility
corepack install --global pnpm@11.20.0
pnpm devKeep the terminal open. When the services are ready, visit
http://localhost:3400 and choose continue locally. The API runs at
http://localhost:4400 and the documentation at http://localhost:3500.
pnpm dev installs dependencies, prepares the local database, and starts the
services. It creates .env as needed and preserves existing values. The
self-host quickstart covers prerequisites,
health checks, and stopping and resuming the stack.
Build the image used by story workspaces:
docker build -f runner/Dockerfile -t facility-runner:dev .Follow the GitHub App guide to create
and install the App, configure its credentials, and bind the installation to
Facility. GitHub delivers events to a publicly reachable
<PUBLIC_URL>/webhooks/github; use a forwarding tunnel for local development.
The authentication guide covers
GitHub and OIDC sign-in.
Configure credentials for your chosen engine using the
project environment guide.
Restart pnpm dev after changing .env. The GitHub App supplies repository
access for cloning, pushing, and opening pull requests.
Create a project and select a repository visible to the GitHub App. Review the
detected setup command, development command, and service port. Open and merge
the kickstart pull request: it adds .facility.yml and the agent manifests in
.agents/ so the environment and workflow are reviewed with your code.
Start a small story from the web application or MCP and select an agent that accepts that trigger. Watch the conversation, open the service preview, then suspend and continue the story. Your files and session should still be there. That is your first complete workspace loop.
Use story operations for the next task and end-to-end validation to check the full setup. The CLI reference covers creating the repository configuration from a terminal.
Every agent receives maintainer-level access to the repositories and credentials connected to its project. Each role defines instructions and triggers within that shared capability. Configure protected branches, required CI, reviews, and GitHub App bypass settings to enforce your merge policy.
Self-hosting gives you control of the Facility services, database, and workspace storage. Claude Code and Codex communicate with the model service you configure for the engine. Choose providers and credentials that fit your infrastructure requirements.
Project budgets are checked before new provider calls. Usage is recorded afterwards, so an in-flight call can take spending beyond the monthly limit. Retained workspaces also need an explicit storage and deletion policy.
The hardening guide covers isolation, credentials, backups, and retention. The production guide covers operating the instance.
| You want to… | Read |
|---|---|
| Understand the operating model | AI SDLC method and story loop |
| Install and operate an instance | Self-hosting, authentication, and production |
| Configure a repository and its agents | Project manifest and agent manifest |
| Continue, suspend, or archive work | Story operations and workspace lifecycle |
| Find stories that need attention | Project overview and attention queue |
| Connect a client or build an integration | MCP tools, REST API, and webhooks |
| Check the whole setup on a repository | End-to-end validation |
| Find your way around the code | Architecture and contributor guide |
Bug reports, documentation improvements, and focused feature proposals are welcome. Before implementing a substantial change, open an issue so its behavior and boundaries can be agreed on.
git clone https://github.com/theam/facility.git
cd facility
corepack install --global pnpm@11.20.0
pnpm install --frozen-lockfile
pnpm verifypnpm verify runs lint and type checks, a clean cache-disabled build, critical integration tests,
the remaining uncached tests, repository guards, and the dependency gate. CI separately builds the
self-host images and applies the Docker-backed workspace E2E policy documented in
docs/testing.md.
Use a semantic branch name such as docs/readme or fix/workspace-recovery, keep the change to one
coherent intent, add tests for behavior changes, and include the commands you ran in the pull
request. See CONTRIBUTING.md and the contributor
documentation for the complete workflow. Report
vulnerabilities through SECURITY.md, not a public issue.
Licensed under the Apache License 2.0. Copyright 2026 The Agile Monkeys.
An initiative by The Agile Monkeys