Self-hosting

Run the whole platform yourself with Docker Compose — the same product, on your own box.

Peractor is one MIT-licensed product with two supported ways to run it: Peractor Cloud, which we operate, and self-hosted, which you do.

Self-hosting is not a reduced edition — same workflows, gates, connectors, tracker, wiki, and apps. The officially supported deployment is a single-node Docker Compose stack.

What you need

• Docker. Postgres ships as a service in the compose file, and every run executes in an isolated container the host launches. Isolation is mandatory, so the run image must exist.
• An agent credential. Runs execute inside containers, which cannot see an interactive login on the machine. Use a subscription token from claude setup-token, or an Anthropic API key; add an OpenAI key if your workflows select Codex.
• Mail. Sign-up confirms an email address, so the host needs a mail sender configured and refuses to boot without one.
• A git push credential for runs that push branches and open pull requests — a GitHub App, or a token or SSH key connected in the app. See Git & credentials.

Quick start

# 1. Get the source and build the run image (mandatory)
git clone https://github.com/peractor-ai/peractor && cd peractor
docker build -f infra/docker/Dockerfile --target sandbox -t peractor-sandbox .

# 2. Configure — at minimum: POSTGRES_PASSWORD, PERACTOR_SECRET_KEY,
#    a mail sender, and an agent credential
cp infra/docker/.env.example infra/docker/.env

# 3. Up
docker compose -f infra/docker/compose.saas.yaml \
  --env-file infra/docker/.env up --build

Open http://localhost:7878, sign up — the first account is yours — and create your organization. A fresh host works out of the box: a built-in default workflow, and no connectors required.

Point your apps at it

Repositories choose their control plane with peractorrc.json at the repository root:

{ "host": "https://peractor.internal.example.com", "project": "…" }

Without a host entry, the apps use Peractor Cloud. The extension fills this file in when you connect a repository to a project.

Hardening

• Every run container is one-shot and locked down: non-root, all capabilities dropped, no privilege escalation, with CPU, memory, and process caps (PERACTOR_RUN_CPU, PERACTOR_RUN_MEM_MB, PERACTOR_RUN_PIDS).
• Set PERACTOR_ISOLATION=gvisor once the Docker daemon has the gVisor runtime, for a kernel-level boundary. Recommended when people you do not fully trust can start runs.
• PERACTOR_SECRET_KEY encrypts every per-organization secret at rest. Keep it stable and backed up — rotating it makes existing secrets undecryptable.
• The host mounts the Docker socket to launch run containers. Treat the host as your trust boundary and give it an isolated daemon.
• Cap load with PERACTOR_MAX_CONCURRENT_RUNS and PERACTOR_MONTHLY_RUN_QUOTA. Both count jobs, so a workflow that fans out counts one per lane.
• Cap spend with PERACTOR_MONTHLY_TOKEN_QUOTA — the model tokens one organization may spend a month on this deployment's own credential.

Useful knobs

Every knob — sign-in providers, tracker and notifier OAuth apps, push, quotas — is documented in .env.example, and every optional group degrades gracefully when unset.

To run phases on other machines you own, see Run on your own machine. For limits and metering, see Plans & usage.