Scalable, Observable and Governed AI SDLC Platform.
Overview
Facility is open-source, self-hosted tooling for running AI coding agents as part of a reviewable software delivery process — with the humans, the gates and the evidence in one place. Facility connects software work, agents, development environments, GitHub delivery state, human review, costs, and operational evidence. Each story has a persistent workspace and shared conversation that agents and people can continue until the work is complete. MCP is the primary automation interface, while the web application is a first-class surface over the same projects, agents, stories, conversations, environments, previews, and lifecycle controls. Facility runs the delivery of the team that builds it, and nowhere else yet. It is published at this stage deliberately: a platform for governing AI-assisted delivery is not something to design in private for a year and then unveil. It gets better by being used, argued with, and corrected.
README
A persistent workspace for every story
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
Status
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.
How the work moves
- 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.
Quick start: run Facility
You need Docker, Node.js 24 LTS, and pnpm 11.28.2. 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.
1. Open the local application
git clone https://github.com/theam/facility.git
cd facility
corepack install --global [email protected]
pnpm dev
Keep 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.
2. Prepare for your first repository
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
/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.
3. Connect, configure, and start a story
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.
Before connecting more repositories
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 reserve a priced estimate before a turn or title-generation call. Measured usage replaces the hold afterwards; an individual call can exceed its estimate. Interrupted worker usage is recovered from retained per-turn journals where possible. Missing or incomplete usage pauses new model calls while budget enforcement is enabled; see the deployment FAQ. Retained workspaces also need an explicit suspension, retention and deletion policy because storage and provider resources have their own costs.
The hardening guide covers isolation, credentials, backups, and retention. The production guide covers operating the instance.
Documentation
| 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 |
Contributing
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 [email protected]
pnpm install --frozen-lockfile
pnpm verify
pnpm 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.
License
Licensed under the Apache License 2.0. Copyright 2026 The Agile Monkeys.
An initiative by The Agile Monkeys
Recommended Tools
Try a different keyword or remove a filter.
Install
npx skillfish add theam/facility