LightsOut

Agent orchestration system: it runs chains of coding-agent sessions (Claude Code, Codex) inside one container, mediates their permission requests against policy, raises doubts instead of guessing, asks a second opinion when a doubt is resolvable, and exposes the whole thing over MCP plus a web panel.

Everything runs inside a single container. The only prerequisite is Docker.

Quick start

1. Install Docker

Windows — Docker Desktop. Open it once and leave it running; it starts by itself on later reboots.

winget install Docker.DockerDesktop

macOS — Docker Desktop (brew install --cask docker). Linux — Docker Engine with compose v2, from your distribution's packages.

2. Start LightsOut

Windows (PowerShell):

docker run -d --name lightsout --restart unless-stopped `
  -p 127.0.0.1:8484:8484 -p 127.0.0.1:1455:1455 -p 127.0.0.1:5170-5189:5170-5189 `
  -v lightsout-db:/data `
  -v "$env:USERPROFILE\Documents\LightsOut:/workspace" `
  -v lightsout-toolchains:/toolchains `
  -v claude-auth:/home/app/.claude -v codex-auth:/home/app/.codex `
  -e LO_WORKSPACE_MODE=host -e LO_WORKSPACE_HOST="$env:USERPROFILE\Documents\LightsOut" `
  ghcr.io/filipeagg/lightsout:latest

macOS / Linux (bash):

docker run -d --name lightsout --restart unless-stopped \
  -p 127.0.0.1:8484:8484 -p 127.0.0.1:1455:1455 -p 127.0.0.1:5170-5189:5170-5189 \
  -v lightsout-db:/data \
  -v "$HOME/LightsOut:/workspace" \
  -v lightsout-toolchains:/toolchains \
  -v claude-auth:/home/app/.claude -v codex-auth:/home/app/.codex \
  -e LO_WORKSPACE_MODE=host -e LO_WORKSPACE_HOST="$HOME/LightsOut" \
  ghcr.io/filipeagg/lightsout:latest

The image is public and multi-arch, so there is no registry login. Every setting has a working default; there is no file to edit.

The panel is at http://127.0.0.1:8484. Panel and API are bound to localhost only.

Port 1455 is the OAuth callback the engine CLIs use when you sign in; 5170–5189 is the pool the preview server hands out, so a project you are building can be opened in your own browser.

3. Connect the engines

Open the web wizard: http://127.0.0.1:8484/setup.html

Press Connect on each engine. The page runs the engine CLI's own login, shows its output unedited, and gives you the field for whatever it asks for; an API key works too. Claude runs the work and Codex gives the second opinion before a doubt is opened, so connect both.

Credentials stay in this machine's claude-auth and codex-auth volumes and survive updates.

4. Connect Claude Desktop

Download the extension: https://github.com/filipeagg/LightsOut/raw/main/scripts/windows/lightsout.mcpb

Install it by dragging it onto the Claude Desktop window, or through Settings → Extensions → Advanced settings → Install Extension… It asks for one setting, the port, and 8484 is the default. Restart Claude Desktop afterwards.

This is the only supported way to reach a local MCP server. A custom connector URL does not work — Claude reaches remote MCP servers from Anthropic's cloud, which has no route to your 127.0.0.1 — and claude_desktop_config.json is no longer read by recent builds.

5. Check

Ask Claude Desktop: use the health tool of lightsout. It should report the database, both engines authenticated and no active runs. The same picture is at http://127.0.0.1:8484/health, or curl -s localhost:8484/health.

Related MCP server: Hermes Squad

Updating

docker pull ghcr.io/filipeagg/lightsout:latest
docker rm -f lightsout

Then run the command from step 2 again. Migrations run at boot and every volume survives, so credentials, database and projects are kept. Restart Claude Desktop: it reads the tool list once, when it connects.

Worth knowing

• Your workspace is a folder on your own machine — %USERPROFILE%\Documents\LightsOut on Windows, ~/LightsOut elsewhere. Projects, agent profiles, templates and knowledge bases live there, openable in your own editor. Do not hand-edit a project while a run is active on it; the panel shows which ones are busy.

• The extension is only a bridge. It declares no tools of its own — the container serves the tool list when Claude Desktop connects — so it does not have to match the image version.

• Projects do not travel with the image. To take one from another machine: clone its repository and use Adopt existing, or import the .lobundle its owner exported. A bundle carries what git cannot — knowledge bases, agent profiles, the template — and names the credentials it needs without ever carrying their values, so you fill those in yourself. When the project has no git remote at all, the bundle carries the repository too, as a git bundle, and the import unpacks it for you. The answer to import_bundle tells you what is left to do.

Documents

• doc/QUICKSTART-WINDOWS.md — the steps above, Windows only, nothing else.

• doc/INSTALL.md — full installation guide, including a fresh machine.

• doc/EXAMPLES.md — realistic usage walkthroughs.

• doc/REQUIREMENTS.md — what the system must do (requirement IDs).

• doc/DESIGN.md — how it is built, section by section.

• doc/TESTING.md — what can be exercised today and how.

Requirements

• Windows 11 or macOS with Docker Desktop, or Linux with Docker Engine + compose v2.

• A Claude subscription or API key, and a ChatGPT/OpenAI subscription or API key.

Egress allowlist (RT-05)

By default outbound traffic is unrestricted and /health says so (network: unrestricted). To enforce the allowlist, edit proxy/filter with your git remote hosts and start with the overlay:

docker compose -f docker-compose.yml -f docker-compose.secure.yml --profile secure up -d

Development

npm install
npm run typecheck
npm run build
npm test

The build order and the per-phase verification scripts are defined in doc/DESIGN.md §13; each phase has a gate under scripts/verify/. The gates need a shell with docker on PATH: on Windows, Git Bash works.

Licence

Copyright 2026 Filipe Gomes. Licensed under the Apache License, Version 2.0 with the Commons Clause condition (see LICENSE): free to use, modify and redistribute, including commercially inside your own organisation; not for sale or resale, as itself or as a service, by anyone but the Licensor.