Approving

Docs

Quick start

Bring up Approving on a Linux host with Docker Compose.

Prerequisites

  • A Linux host
  • Git, Docker, and Docker Compose installed

Clone the repository

git clone https://github.com/cocofhu/approving.git
cd approving

Start

By default this pulls published images from GHCR (no local image build required):

./start.sh -d

Then open:

./start.sh also pulls five sandbox runtime images from GHCR (one per acpBackend: cursor / claude_code / codebuddy / trae / opencode; large). Until that finishes, sandbox chats may stay on “starting sandbox…”.

Agent / workspace / platform-rules and SQLite data live under .localdata at the repo root (bind mounts: gateway / db / app-data). ./start.sh restart and ./start.sh down keep that directory. To wipe: ./start.sh down && rm -rf .localdata.

Database and attachments share one lifecycle (backup / cleanup)

In the release stack (compose.release.yaml), SQLite is mounted at ./.localdata/db and app data (including default attachment blobs under data/blobs relative to WORKDIR) at ./.localdata/app-data. Composite variable images keep only blob:{id} refs in the DB / Run outputs; bytes live under the blobs directory. Backing up or cleaning only one side creates orphan refs (“ref still present, GET /api/blobs/:id → 404”), and Run detail shows Cannot display / Attachment unavailable.

Ops rules:

  • Paired backup: every backup set must include both ./.localdata/db and ./.localdata/app-data (or the whole .localdata tree).
  • Paired cleanup / migration / upgrade: never move only SQLite or delete only the blobs directory; if you override APPROVING_BLOBS_ROOT, include that path in the same lifecycle as the database.
  • Historical orphans: broken refs are not guaranteed recoverable; the UI only shows a permanent-failure placeholder. This delivery does not add an orphan inspection console, bulk scan page, or startup/health-check alerts.

Common commands

./start.sh logs
./start.sh down
./start.sh pull          # refresh GHCR images (including five sandbox runtimes)
./start.sh restart       # down + up -d (keeps .localdata)
./start.sh dev -d        # source stack: go run + Vite HMR

Image tags / digests can be overridden in .env — see .env.example at the repo root. By default sandbox images follow acpBackend; set SANDBOX_IMAGE / APPROVING_SANDBOX_IMAGE only for an optional global force. Publish and smoke checks are covered in Contributing.

Next steps

  • After login, the default project opens first-time setup: ACP backend, API token, and optional Git credentials (written to shared Agent config), then creates the default team and publishes Default Workflow. Fill the repo URL when starting a Run.
  • Core concepts — FSM, gates, sandbox, artifacts
  • Configuration summary — points to full CONFIGURATION.md
  • Gateway summary — points to GATEWAY.md