pocage is a web control plane plus a local daemon. The web app manages auth, pairing, sessions, and run orchestration. The local pocage daemon connects to that control plane and executes agent work on your machine.
- Install the local daemon prerequisites:
npm install -g @zed-industries/codex-acp
pip install pocage-
Open the official pocage web app in your browser, sign in, and generate a pairing code.
-
Pair your local daemon with the official service:
pocage pair --agent codex --api-url https://pocage.toce.ai --pairing-code <pairing-code>
pocage --agent codexUse this when you want to run the full stack locally in containers. For day-to-day code changes, prefer the host-side Local Development flow below.
- Create the Compose env file:
cp .env.compose.example .env.compose- Start the self-hosted stack:
docker compose up --build -d- Install the local daemon prerequisites:
npm install -g @zed-industries/codex-acp
pip install pocage- Open
http://127.0.0.1:8080, create a pairing code, then run:
pocage pair --agent codex --api-url http://127.0.0.1:8080 --pairing-code <pairing-code>
pocage --agent codexPocket Agent is a multi-process system with a web UI, an API/orchestrator, and a remote connector bridge.
React Frontend --HTTP/REST + SSE--> FastAPI Backend
|
| WebSocket
v
Pocket Agent Connector
|
| ACP / JSON-RPC (stdin/stdout)
v
codex-acp
frontend: presents the session list and chat UI, creates sessions, sends user messages, subscribes to run events, and handles permission decisions.backend: exposes public APIs, indexes remote ACP sessions, keeps active run state in memory, streams run events via SSE, and dispatches queued runs to the selected connector.connector: the publishable Python project for the local daemon; itspocagepackage maintains the backend WebSocket connection, lists and creates ACP sessions, executes assigned runs throughcodex-acp, and relays streaming updates.codex-acp: the session and prompting engine used by the connector.
session: the long-lived conversation container. A session is bound to one remote ACP session on one connector machine and tracks the title, working directory, connector, and current high-level status.run: one execution turn inside a session. Each time the user sends a new message, backend creates a run, assigns it to the connector, and tracks streaming deltas, tool activity, permission requests, and terminal status for that turn.transcript: the chat history shown in the right-hand conversation view. In the current architecture it is not a separate persisted database entity; it is a session-level message view assembled from remote session history returned bysession/loadplus any in-flight local run messages.message: one user or assistant entry inside the transcript. Remote replayed messages haverun_id = null; messages produced by an active local run carry that run'srun_id.
Relationship summary:
- one
sessioncontains manyruns - one
sessionrenders one transcript view - one transcript contains many
messages
- The frontend creates or selects a session.
- The frontend posts a user message to
POST /v1/sessions/{session_id}/messages. - The backend creates a queued run in memory and emits
run.queued. ExecutorManagerassigns the queued run to the connector bound to that session via WebSocketrun.assign.- The connector loads the ACP session and sends
session/prompttocodex-acp. - The connector streams
run.delta,run.tool, andrun.updateback to backend. - The backend appends assistant deltas and run events to its in-memory runtime registry and pushes the same events to frontend over SSE.
- On completion, failure, or cancel, backend finalizes the run and session status and emits terminal events.
codex-acprequests permission during a run.- The connector forwards it as
run.permission.requested. - The frontend calls
POST /v1/runs/{run_id}/permissions/{approval_id}/decision. - The backend forwards the decision to the connector, stores it, and emits
run.permission.decision.
- Frontend -> Backend (REST):
POST /v1/sessionsGET /v1/sessionsGET /v1/sessions/{session_id}/messagesPOST /v1/sessions/{session_id}/messagesGET /v1/connectorsGET /v1/context/searchGET /v1/runs/{run_id}/permissionsPOST /v1/runs/{run_id}/permissions/{approval_id}/decisionPOST /v1/runs/{run_id}/cancel
- Frontend -> Backend (SSE):
GET /v1/runs/{run_id}/events
- Backend <-> Connector (WebSocket + bearer auth):
- endpoint:
/api/daemon/ws - backend -> connector:
session.create.request,session.list.request,context.search.request,run.assign,run.cancel,run.permission.decision - connector -> backend:
session.create.result,session.list.result,context.search.result,run.accepted,run.delta,run.tool,run.update,run.permission.requested,run.completed,run.failed
- endpoint:
- Connector <-> codex-acp (JSON-RPC):
- main methods:
session/new,session/list,session/load,session/prompt,session/cancel,session/set_mode - callbacks:
session/update,session/request_permission
- main methods:
This is the default workflow when you are changing code in this repository.
- Create the local development env file:
cp .env.local.example .env.local- Install project dependencies:
cd backend && uv sync
cd ../frontend && npm install
cd ../connector && uv sync
cd ../..
npm install -g @zed-industries/codex-acp- Start PostgreSQL:
docker compose up -d db- Start the backend and frontend on the host with a fresh local database reset:
./scripts/dev-up.shReuse the existing local database state only when you need it:
./scripts/dev-up.sh --no-freshReset the local development database without starting the host-side services:
./scripts/dev-reset.shStop the host-side services with:
./scripts/dev-down.sh- Open
http://127.0.0.1:5173, create a pairing code, then pair the daemon:
cd connector
uv run pocage pair --agent codex --api-url http://127.0.0.1:8000 --pairing-code <pairing-code>
uv run pocage --agent codex.env.example: index file that points to the right template.env.local.example->.env.local: host-side development.env.compose.example->.env.compose: Docker Compose.env.production.example->.env.production: deployment placeholders
Backend env selection:
- host-side backend commands default to
.env.local - Docker Compose reads
.env.compose - set
POCAGE_ENV_FILE=.env.productionto force a different backend env file
cp .env.production.example .env.production- The official public URL is
https://pocage.toce.ai - Replace database credentials, SMTP credentials, and
SECRET_KEY - If you run the backend directly, use
POCAGE_ENV_FILE=.env.production - Keep
VITE_API_URLempty when the frontend should use the same public origin as the reverse proxy
Production Docker Compose:
docker compose -f docker-compose.production.yml up -d --buildNotes:
docker-compose.production.ymlincludes a bundled Postgres service and persists it in thepostgres_datavolume- Caddy listens on
:8080 - if you expose
:8080directly without upstream HTTPS, setPUBLIC_BASE_URL,FRONTEND_URL, andPOCAGE_CORS_ORIGINStohttp://<host>:8080, and setCOOKIE_SECURE=false - if you front the site with Cloudflare or another browser-focused WAF, allow non-browser traffic to
/api/daemon/pairand/api/daemon/ws; browser integrity checks can block thepocageCLI - terminate TLS upstream if you still want HTTPS on the public edge
- Caddy state persists in the named volumes
caddy_dataandcaddy_config