Skip to content
CherryPi
v0.6.0 is out

One agency.
Every agent.

CherryPi is self-hosted orchestration for a fleet of AI agents. Put the agency on your VPS, connect agents from any machine, and run every task, session and terminal from one place — without exposing a single inbound port.

Download CherryPi Read the docs
AGPL-3.0 SQLite or PostgreSQL Linux + macOS agents
CherryPi
4 agents online

Tasks

All projects

Newest first · scheduler ready

+ New task
3running
2queued
14settled
Fix the onboarding redirect Running
WEB-42 / Website Relaunch
B
Add dark mode to settings Running
APP-18 / Mobile App
D
Rotate the staging credentials Queued
INF-07 / Infrastructure
R
Rewrite the release notes Settled
WEB-39 / Website Relaunch
D
Describe a task for your fleet… ⌘ ↵

Built for the machine you already own

agency on a VPS agents behind NAT live Pi sessions per-task cost

The product

A control plane that actually understands agents.

Not a chat window with extra steps. CherryPi gives a fleet of Pi workers projects, permissions, a queue, live terminals and a paper trail — while every agent keeps running on the machine it was installed on.

A queue that keeps agents busy

Draft, queue and settle tasks across projects. The scheduler respects each agent's concurrency limit, so a fleet never stampedes a model or a machine.

Live sessions and terminals

Watch Pi work in real time, send follow-up prompts, open a PTY or bring up the agent's desktop — all through the agency, all over one outbound tunnel.

Built for more than one human

Projects, teams, ownership, invitations and per-actor audit trails. Give people and agents exactly the access they need, and keep the history.

Cost and usage, per task

Token usage, total cost and run time land on the task, the agent and the project. Know what your fleet is doing without scraping logs.

Artifacts, not lost output

Agents publish files, screenshots and structured results as task artifacts. Attachments and session history stay with the task when the run ends.

Open source, yours to run

AGPL-3.0, Go and Vue. Bring your own database (SQLite or PostgreSQL), object storage and reverse proxy. No hosted control plane in the middle.

How it works

One exposed service.
Every agent behind it.

The agency owns accounts, projects, scheduling and history. Agents dial out over a single tunnel and serve their Pi sessions, PTYs and desktop through it. Put a TLS proxy in front of the agency and you are done.

Browser

HTTPS · session cookie

HTTPS
Agency · your VPS online

cherrypi-agency

Go + Vue · tunnel hub

task queue teams usage artifacts

SQLite · PostgreSQL · S3

outbound tunnel
Agent machines
builder ci-runner-01
design mac-mini.local
reviewer vps-fra-02

no inbound ports

01

Install the agency

Run one container on a VPS. It serves the web app, API and tunnel hub; add a TLS reverse proxy in front.

02

Register an agent

Create the agent in the UI, copy its one-time personal access token, and start cherrypi-agent on the worker machine.

03

Queue the work

Create a project and a task, write the prompt, and let the scheduler start it when an agent has capacity.

WEB-42 / Fix the onboarding redirect
Settled builder
The onboarding flow drops invitees on a blank page after they accept. Reproduce it, find the cause and add a regression test.

Beginning of conversation

Reproduced locally. InviteView routes to /tasks before the session cookie is committed, so the first request is unauthenticated.

Thinking · 4 steps · 7s view

The fix awaits the session reload and only redirects when it succeeds. Added a Vitest regression for the blank-page case.

Send a follow-up prompt… ⌘ ↵
Attach Sketch session stored in agency

The unit of work

The task outlives the machine.

Prompts, follow-ups, session history, attachments and artifacts stay in the agency — not in a scrollback buffer on someone's laptop. Reassign a task, pause it, or come back tomorrow and continue where the agent stopped.

  • A real conversation

    Send follow-up prompts to a live Pi session and keep the full reasoning trace.

  • See the machine

    Open a PTY, browse the agent's desktop, or read the task's terminal without SSH.

  • Output that stays put

    Publish task artifacts and attach files; the agency stores them with the task.

  • Handover without context loss

    Move work between agents, people and projects with permissions and an audit trail.

How tasks work

Self-hosted by default

Your infrastructure.
Your data. Your agents.

CherryPi ships as two containers and a set of environment variables. There is no hosted control plane, no vendor account and no telemetry phone-home. Point it at the database and bucket you already trust.

  • SQLite or PostgreSQL

    Start with a file, move to Postgres when the team grows.

  • Any S3-compatible bucket

    Attachments and task artifacts stay in your object storage.

  • OIDC, LDAP, SMTP

    Bring the identity provider and mail server you already run.

  • Open source under AGPL-3.0

    Audit the server, the SPA, the agent and the tunnel.

Install the agency Install an agent

Two containers, one tunnel

linux/amd64

01 / agency · the exposed service

agency · scroll → 
docker run -d --name cherrypi-agency \
  --restart unless-stopped \
  -p 8080:8080 \
  -v "$PWD/agency_data:/root/.cherrypi-agency" \
  -e CHERRYPI_ADMIN_PASSWORD='choose-a-long-password' \
  -e CHERRYPI_PUBLIC_URL='https://cherrypi.example.com' \
  ghcr.io/cherrypidotdev/cherrypi-agency:latest

02 / agent · behind NAT

agent · scroll → 
docker run -d --name cherrypi-agent \
  --restart unless-stopped \
  -v "$PWD/cherrypi_data:/root/.cherrypi" \
  -e CHERRYPI_AGENCY_URL='https://cherrypi.example.com' \
  -e CHERRYPI_AGENT_TOKEN='pat_…' \
  ghcr.io/cherrypidotdev/cherrypi-agent:latest

Images: ghcr.io/cherrypidotdev/cherrypi-{agency,agent}

Latest release

Put the fleet on your own hardware.

Binaries for Linux and macOS, container images for the agency and agent, and release notes on GitHub. This page reads the latest tag directly from the public repository.

All downloads View source

v0.6.0 · published Nov 4, 2026 · baked into this build

Quick download notes
Agency · Linux x86_64 30.0 MB · one binary, zipped Agent · Linux x86_64 11.9 MB · Pi runtime included
docker pull both images →

$ ghcr.io/cherrypidotdev/cherrypi-agency:v0.6.0

Questions

The honest answers.

Still unsure? Open a discussion or read the operations guide before putting an agency on the public internet.

Discussions Documentation
Do agents need a public IP or inbound ports?

No. Agents dial out to the agency and keep a tunnel open. Only the agency needs to be reachable from a browser, which makes agents work behind NAT, on laptops, and on machines you do not expose to the internet.

What exactly runs on an agent machine?

The cherrypi-agent binary hosts the Pi harness, a parallel session manager, PTYs, a desktop bridge and the tunnel client. One agent can serve several concurrent sessions, subject to the limits you configure.

Is CherryPi open source?

Yes. CherryPi is licensed under AGPL-3.0. Every commit on main is published as a complete, buildable source snapshot on GitHub, with releases, issues and discussions there.

Can I run the agency with PostgreSQL?

Yes. The agency supports SQLite out of the box and PostgreSQL as a first-class alternative store. Configuration is environment-driven, including object storage for attachments.

How are updates distributed?

GitHub Releases carry signed release notes, per-platform binaries and container images on GHCR. This page reads the latest release from the GitHub API; the binaries below always point at the current tag.

Where can I read the documentation?

The documentation lives at docs.cherrypi.dev, with guides for installing the agency, connecting agents, configuration and the JavaScript SDK. The repository also ships a compose file for a local agency + agent.