Deputies

Deputies is a control plane for delegating engineering work to background agents. It includes a fully featured web UI where each task gets a persistent session for queueing prompts, following live progress, reviewing diagnostics, inspecting artifacts, and managing callbacks from integrations like Slack, GitHub, or webhooks.

[!NOTE] Deputies is still early-stage. Expect the system to evolve quickly as real usage exposes needed changes, including occasional breaking changes.

Deputies primary view

What It Does

Runs agent work in durable background sessions with searchable, paginated activity history.
Streams progress, tool diagnostics, artifacts, and final responses into the web UI.
Lets users star, tag, filter, search, archive, and resume sessions.
Built on Pi for real agent work, with a fake runner for deterministic smoke tests.
Supports Slack, GitHub, generic webhook, scheduled automation, and per-session scheduled follow-up workflows with callback delivery tracking where applicable.
Supports GitHub OAuth login, static login, and tenant-wide viewer/member/admin access control.
Works with Daytona, Superserve, Docker, Tensorlake, Kubernetes Agent Sandbox, and AWS Lambda MicroVM sandbox providers, plus fake and unsafe local providers for tests and trusted development.
Runs repo-owned .agents/setup scripts to prepare sandbox workspaces before agents start.
Supports standard LLM API-key configuration and OpenAI Codex/ChatGPT subscriptions.
Provides reusable environments, versioned agent skills and profiles, personal prompt snippets, and durable session notepads.
Supports nested deputy sessions, private sessions, pending-message steering, and one-time or recurring scheduled follow-ups.
Tracks artifacts, callback deliveries, repositories, sandbox status, automations, and queued messages.
Deploys as portable Node, Caddy, Postgres, and optional S3-compatible object storage services.

Deployment

Start with the provider-agnostic deployment guide:

docs/deployment.md: required services, env vars, integrations, sandbox providers, and operations checklists.

Specific deployment targets:

Railway: the public template at https://railway.com/deploy/deputies-monolith provisions the app services and supporting infrastructure.
Docker Compose: deploy/docker-compose/ contains local production-style Compose stacks for combined and split API/worker/orchestrator deployments.
Kubernetes: deploy/kubernetes/ contains Helm charts for Kubernetes deployments.
AWS: deploy/aws/ contains a Terraform reference deployment for ECS Fargate, RDS, S3, and Lambda MicroVM sandboxes.

More deployment targets are expected over time. See deploy/README.md, docs/deployment.md, and target-specific docs for details.

Local Development

For contributor setup, see docs/contributing-local-development.md. It covers the local Postgres and SeaweedFS baseline, Portless, Docker Compose, Pi runner setup, and local integration testing.

Project Layout

apps/: independently runnable and deployable applications/services.
apps/control-plane/: backend control-plane API, event stream, stores, integrations, workers, and sandbox providers.
apps/web/: React frontend for session management and agent progress review.
apps/www/: static root-domain website with an embedded public demo build.
packages/: reusable libraries shared by apps, including the Docker sandbox bridge.
deploy/: deployment and local runtime configuration.
docs/: architecture, domain notes, testing strategy, and feature backlog.

More Docs

Start with docs/README.md for deeper project documentation.