Run Harborist with Docker
Run the Harborist service and browser workspace in local Docker containers. Select Docker Sandboxes for your Workspace so that each agent stage and mandatory TEST run in fresh VMs on the host.
Before you begin
Section titled “Before you begin”- Use Apple silicon macOS with hardware virtualization and Docker Desktop running.
- Install Git, uv, and standalone Docker Sandboxes 0.54.x.
Check the sandbox version with
sbx version. - Sign in with
sbx login, initialize the Docker Sandboxes network policy withsbx policy initif needed, and configure Codex authentication withsbx secret set openai --oauth. Run these commands on the Mac as the same user who starts Harborist.
1. Start Harborist
Section titled “1. Start Harborist”From a Harborist checkout on the Mac, run:
./deploy/harborist start./deploy/harborist exec service statusThe installer starts the host sandbox helper and two containers. It checks that the worker can read the host sandbox policy through the helper. Open http://127.0.0.1:8765 to use the browser workspace.
2. Register a repository and select Docker Sandboxes
Section titled “2. Register a repository and select Docker Sandboxes”Put the target Git repository in the worker’s persistent data directory.
For example, replace REPOSITORY_URL in this command with a public Git clone URL:
docker compose --project-name harborist exec -T service \ git clone REPOSITORY_URL /home/harborist/.harborist/projectThe repository must have committed mandatory checks and a settings file with accessible playbook and skill paths. See Configure Harborist for the file formats.
- In Workspaces → New Workspace, register
/home/harborist/.harborist/projectand select its settings file. Enter the container path. - In Integrations → Docker Sandboxes, choose Check Docker Sandboxes. Select your Workspace, choose Edit execution policy, and select Docker Sandboxes.
- Save the policy, then submit a new Run. Harborist freezes the policy at intake. Existing Runs keep their captured settings.
3. Submit a Run and inspect the result
Section titled “3. Submit a Run and inspect the result”Use New Run in the browser workspace to submit an engineering request. For Markdown intake, use a request file accessible to the worker, such as a committed request in the cloned checkout. You can also submit it from the CLI:
./deploy/harborist exec run file:/home/harborist/.harborist/project/request.md \ --repo /home/harborist/.harborist/project./deploy/harborist exec status RUN_ID --waitReplace RUN_ID with the returned UUID. Open the Run to inspect trusted checks,
review findings, and the candidate SHA. A VERIFIED result applies to that exact
commit. See Run and deliver changes for delivery and troubleshooting.
Use ./deploy/harborist stop when you are done. It stops the containers and
the host helper while retaining Run data. See local container deployment
for upgrades and configuration.
Run the development checkout directly
Section titled “Run the development checkout directly”Submit a Markdown request from a Harborist development checkout, follow its progress, and inspect the candidate and verification evidence.
Before you begin
Section titled “Before you begin”- Install Git and uv. uv uses the checkout’s pinned Python version.
- Install and authenticate Codex CLI with
codex login. Your account needs access to the model in the execution profile. See Set up local Codex. - Use a Harborist checkout and a request you trust. This tutorial selects the
included
trusted-localprofile so you can run it without Docker Sandboxes. Git worktrees isolate checkout state. Local agents and check commands run with your OS user’s permissions. For VM isolation, see Docker Sandboxes execution.
Install dependencies and start the service
Section titled “Install dependencies and start the service”If you need a development checkout, clone the repository:
git clone https://github.com/maciejgos/harborist.gitcd harboristFrom the Harborist repository root, run:
uv syncuv run harborist agent check --settings examples/intake/settings.yamluv run harborist service startThe agent check reports Codex connection and profile status. If either needs attention, fix it before submitting the request. The service continues running after the command returns.
Submit the example request
Section titled “Submit the example request”uv run harborist run file:examples/intake/issue.md \ --settings examples/intake/settings.yamlHarborist captures the request and records the base revision, mandatory checks, and execution settings. The command returns a Run UUID. A successful submission means the service accepted the Run.
Follow the Run
Section titled “Follow the Run”Replace RUN_ID with the UUID from the previous command.
uv run harborist status RUN_ID --waitFor the browser workspace, run the command below in another terminal and open http://127.0.0.1:8765. Open the Run to see its stage timeline, mandatory checks, and review findings.
uv run harborist webInspect the outcome
Section titled “Inspect the outcome”Read the Run outcome and the saved report.md and evidence.json. A
VERIFIED outcome identifies the Git commit that passed both mandatory checks
and independent review. Your branch moves only when you explicitly apply the
candidate.
- Verified. Review the evidence, then apply the candidate locally or publish it to GitHub.
- Checks failed or review requested changes. Inspect the failed checks or criteria, then start a rework Attempt.
- Execution was interrupted. Check the delivery and Run status before starting recovery.
When you finish, uv run harborist service stop requests a graceful shutdown.
Next steps
Section titled “Next steps”Configure a target repository to use your own mandatory checks, agent profile, and sandbox policy. See Run and deliver changes for GitHub issue intake and foreground execution.