Parpaing

The building block for AI agents.
Run any AI coding agent in isolated Docker containers via a simple REST API.

Send a prompt, get structured results. Parpaing handles container orchestration, job queuing, and result collection. Use it standalone or as the execution backend behind your own SaaS.

Status: MVP - Core features work (job queue, container pool, dashboard, multi-engine). Not production-hardened yet. See Roadmap for what's planned.

What works: create/poll/cancel/wait jobs, profiles, web dashboard, multi-tower scaling, Prometheus metrics, LLM gateway.

What's missing for production: multi-tenant auth, rate limiting, file upload, cost tracking, CI/CD.

Architecture

Quick Start

cp .env.example .env
# Set POSTGRES_PASSWORD and at least one engine auth key (see .env.example)

docker compose up --build -d

# Open dashboard
open http://localhost:8420/ui

Usage

Python

import requests

API = "http://localhost:8420"

# Create a job and wait for the result (blocking)
r = requests.post(f"{API}/jobs", json={
    "agent_id": "test",
    "engine": "claude-code",
    "prompt": "List files in /workspace",
})
job_id = r.json()["job_id"]

# Wait for completion (blocks until done, timeout 1h by default)
result = requests.get(f"{API}/jobs/{job_id}/wait").json()
print(result["status"])   # completed / failed
print(result["result"])   # agent output

# Use a profile with variables
r = requests.post(f"{API}/jobs", json={
    "agent_id": "search",
    "engine": "claude-code",
    "profile": "researcher",
    "prompt_vars": {"query": "best CI tools"},
})
result = requests.get(f"{API}/jobs/{r.json()['job_id']}/wait").json()

curl

# Create + wait
JOB_ID=$(curl -s -X POST http://localhost:8420/jobs \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"test","engine":"claude-code","prompt":"Hello"}' | jq -r .job_id)

curl http://localhost:8420/jobs/$JOB_ID/wait    # blocks until done

# Cancel
curl -X DELETE http://localhost:8420/jobs/$JOB_ID

API

See docs/api.md for full reference and docs/request.md for request fields.

Interactive docs available at /docs when running.

Profiles

Profiles are reusable agent configurations in TOML. They define the model, tools, prompt template, hooks, and resource limits.

Profile	Purpose
`default`	General-purpose agent
`researcher`	Deep research with web search
`code-review`	Code quality analysis

No profile needed for simple jobs - default is used automatically.

Discover profiles and their variables via GET /profiles.

See docs/profiles.md and docs/templates.md.

Configuration

All variables are read from .env (copy from .env.example). Only POSTGRES_PASSWORD is required - everything else has a working default.

Core

Variable	Default	Description
`POSTGRES_PASSWORD`	-	Required. PostgreSQL password
`TOWER_PORT`	`8420`	Port exposed by Tower
`TOWER_API_KEY`	-	Bearer token for API auth - empty means no auth
`TOWER_REPLICAS`	`1`	Number of Tower instances (horizontal scaling)

Engine Authentication

Parpaing handles orchestration, profiles, and infrastructure - you bring your own engine credentials.

Engine	Auth variable(s)	Cost model
Claude Code	`ANTHROPIC_API_KEY` (pay-per-token) or `CLAUDE_CODE_OAUTH_TOKEN` (Pro/Max subscription)	API usage or flat subscription
OpenCode	`ANTHROPIC_API_KEY` or `OPENAI_API_KEY`	API usage

Recommended for Claude Code - use a long-lived OAuth token from your Pro/Max subscription:

claude set-token
# Paste your OAuth token when prompted
claude -p "hello"   # verify it works

Then set CLAUDE_CODE_OAUTH_TOKEN in .env. No per-token billing - you pay only your subscription.

Check which engines are currently available: GET /engines.

Scaling and Concurrency

Variable	Default	Description
`MAX_CONCURRENT_JOBS`	`10`	Max parallel jobs per Tower instance
`POOL_SIZE`	`3`	Number of warm (pre-started) worker containers
`POOL_CHECK_INTERVAL`	`10`	Pool maintenance interval in seconds
`POOL_MAX_IDLE`	`3600`	Seconds before an idle container is recycled

Worker Limits

Variable	Default	Description
`WORKER_IMAGE`	`agent-worker-worker`	Docker image used for worker containers
`WORKER_TIMEOUT_SECONDS`	`3600`	Max job duration before the container is killed
`WORKER_MEM_LIMIT`	`2g`	Memory limit per worker container
`WORKER_CPU_LIMIT`	`1.0`	CPU quota per worker container
`WORKER_RUNTIME`	-	gVisor runtime for kernel-level isolation - set to `runsc`
`WORKER_NET`	`agent-workers`	Docker network name for worker containers

Job Retention

Variable	Default	Description
`JOB_TTL_HOURS`	`24`	Hours to keep finished jobs in the database
`MAX_RETAINED_JOBS`	`1000`	Maximum number of finished jobs stored
`CLEANUP_INTERVAL`	`600`	Seconds between job cleanup cycles
`MAX_RESULT_SIZE`	`10485760`	Maximum size of a result payload in bytes (10 MB)
`WEBHOOK_TIMEOUT`	`10`	HTTP timeout for outgoing webhook calls in seconds

Network and Gateway

Variable	Default	Description
`GATEWAY_URL`	`http://agent-gateway:4000`	LLM Gateway URL - hides API keys from workers
`GATEWAY_CONTAINER`	`agent-gateway`	Docker container name of the LLM gateway

Database

Variable	Default	Description
`POSTGRES_USER`	`tower`	PostgreSQL user
`POSTGRES_DB`	`tower`	PostgreSQL database name
`DB_POOL_MIN_SIZE`	`2`	Minimum asyncpg connection pool size
`DB_POOL_MAX_SIZE`	auto	Maximum asyncpg connection pool size (auto-sized to `MAX_CONCURRENT_JOBS * 2 + 5`)

All numeric config values are auto-clamped to valid ranges at startup. Out-of-bounds values log a warning and are clamped to the nearest valid bound.

Production

Set in .env:

TOWER_API_KEY=your-strong-random-token
POSTGRES_PASSWORD=strong-password
WORKER_RUNTIME=runsc                   # optional: gVisor kernel-level isolation

Security hardening is always enabled: cap_drop=ALL, no-new-privileges, pids_limit=100, ipc_mode=private. Optional gVisor (WORKER_RUNTIME=runsc) adds kernel-level isolation.

Scale: TOWER_REPLICAS=3 docker compose up -d. Add TLS with a reverse proxy (Traefik, Caddy) in front of Tower.

LLM Gateway

The gateway is an nginx reverse proxy that sits between worker containers and LLM APIs. It is always enabled - workers receive placeholder keys and real API keys stay inside the gateway, never exposed to the job code. The gateway supports both API key and OAuth token authentication, forwarding anthropic-beta and anthropic-version headers. The worker network is internal=true (no internet access, ICC enabled for gateway access).

Project Structure

agent-worker/
├── tower/                 # Orchestrator (FastAPI)
│   ├── Dockerfile         #   Python 3.12 + dependencies
│   ├── main.py            #   Routes, auth middleware, health check
│   ├── config.py          #   Environment variables and defaults
│   ├── models.py          #   Request/response validation (Pydantic)
│   ├── profiles.py        #   Profile loading and template rendering
│   ├── engines.py         #   Engine loading and availability checks
│   ├── metrics.py         #   Prometheus metrics (shared across modules)
│   ├── store/             #   Persistence layer
│   │   ├── jobs.py        #     PostgreSQL persistence with TTL cleanup
│   │   ├── pool.py        #     Warm container pool (DB-backed)
│   │   └── configs.py     #     Config store (profiles, engines, templates in DB)
│   └── runner/            #   Execution layer
│       ├── executor.py    #     Background job execution and webhook dispatch
│       └── worker.py      #     Config injection and result extraction
├── worker/                # Agent container
│   ├── Dockerfile         #   Node.js 22 + engine binaries (Claude Code, OpenCode)
│   ├── entrypoint.sh      #   Waits for config injection, then runs job
│   ├── run-job.sh         #   Engine-agnostic execution (hooks + CLI + result)
│   └── parse-job.js       #   Translates job.json to shell variables
├── gateway/               # LLM Gateway (nginx - hides API keys)
├── profiles/              # Agent profiles (TOML)
├── templates/             # Jinja2 templates (prompts, agent instructions)
├── hooks/                 # Pre/post hook scripts
├── engines/               # Engine configs (TOML - one per AI tool)
├── db/                    # PostgreSQL schema
├── tests/                 # Unit (8 files) and E2E tests (9 files)
├── docs/                  # Documentation and assets
├── ui/                    # Web dashboard (single HTML file)
├── docker-compose.yml
└── docker-compose.prod.yml # Production variant (pre-built images)

Scaling

# Run multiple Tower instances - all share the same PostgreSQL database
TOWER_REPLICAS=3 docker compose up -d

# Any Tower instance can serve any job
# Container pool is DB-backed - atomic acquire with no race conditions
# Cancel works cross-instance via the Docker socket

Roadmap

Items are roughly ordered by priority. Contributions are welcome.

Profiles, prompts and hooks in DB - manage profiles and templates via the API instead of TOML files on disk; enables dynamic configuration without container restarts
Multi-tenant auth - user accounts, organizations, quotas, and scoped API keys; foundation for running Parpaing as a shared service
File upload - inject arbitrary files into /workspace via the API before a job runs; enables code review, document processing, and other file-based workflows
More engines - add support for Codex CLI, Gemini CLI, Aider, and other coding agents; each engine is a single TOML file
WebSocket push - real-time job status updates without client-side polling; reduces latency for interactive use cases
Cost tracking - record token counts and estimated USD cost per job; expose aggregated metrics per agent, profile, and time window
Scheduling - cron expressions and recurring jobs; run agents on a schedule without external orchestration
CI/CD pipeline - automated build, test, and image publish workflow; includes Docker image versioning and release automation

License

Parpaing is licensed under the GNU Affero General Public License v3.0.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Parpaing

Architecture

Quick Start

Usage

Python

curl

API

Profiles

Configuration

Core

Engine Authentication

Scaling and Concurrency

Worker Limits

Job Retention

Network and Gateway

Database

Production

LLM Gateway

Project Structure

Scaling

Roadmap

License

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Parpaing

Architecture

Quick Start

Usage

Python

curl

API

Profiles

Configuration

Core

Engine Authentication

Scaling and Concurrency

Worker Limits

Job Retention

Network and Gateway

Database

Production

LLM Gateway

Project Structure

Scaling

Roadmap

License