Self-hosted topology
Separate the local Work runtime from the organization control plane when planning a private or VPC deployment.
Self-hosting should start from the required capability, not from a desire to deploy every service. A single private remote workspace has a different topology from an organization deployment with identity, RBAC, shared providers, and hosted workers.
The local server that executes workspace work is distinct from an optional organization control plane. Keep ingress, service ownership, data, and recovery boundaries explicit.
- 01Ingress
TLS, routing, health checks, and the public organization entry point.
- 02Control plane
Optional identity, teams, RBAC, policies, shared providers, and Worker lifecycle.
- 03Workspace runtime
The local or remote iPolloWork Server that runs workspace tasks.
- 04Data and recovery
Database, backups, audit export, restore owner, and failover process.
Start with a real server boundary
apps/server packages a filesystem-backed iPolloWork Server. It can run as a compiled binary without Bun at runtime, or from source while contributing to the repository.
# Compiled binary
ipollowork-server --workspace /srv/ipollowork/workspace --approval manual
# From the iPolloWork checkout
pnpm --filter ipollowork-server dev -- \
--workspace /srv/ipollowork/workspace \
--approval manual
The server default configuration is ~/.config/ipollowork/server.json. It can define the bound host and port, approval mode and timeout, an explicit list of workspaces, and accepted CORS origins. Environment overrides cover those categories as well as host and owner tokens, OpenCode connection settings, token storage, and runtime-specific behavior.
The server exposes workspace and runtime functions. Administrative writes are gated by host approval or a scoped owner token, so network reachability alone is not a permission model.
Where requests can arrive
Set a narrow host and explicit origins. Do not use a wildcard as a convenience policy.
Own external TLS and routing outside the local server process.
What the server serves
Health, capabilities, workspace state, artifacts, files, sessions, and audit data.
The supported path through which the client reaches the sidecar.
How sensitive work is permitted
The normal gate for operations that require local host approval.
A scoped bearer alternative for explicitly managed automation.
Decide what to deploy
- Private workspace only: deploy a workspace server and its supported sidecar boundary.
- Organization control plane: deploy the web and controller services for identity, teams, policy, and administration.
- Model gateway or metering: add the inference service only when that specific service is required.
Probe the path you own
| Endpoint or check | Purpose | When to use it |
|---|---|---|
GET /health | Server liveness, version information, and basic reachability | Process and ingress checks |
GET /status | Current server status | Operator diagnostics after reachability succeeds |
GET /capabilities | Supported runtime features | Client compatibility and rollout validation |
GET /w/{workspaceId}/health | Workspace-scoped liveness | Isolating a single remote or local workspace failure |
/opencode/* through the server | Supported sidecar route | Checking the execution boundary rather than calling the sidecar directly |
Use IPOLLOWORK_APPROVAL_MODE=manual as the normal operating posture. Any use of auto should have a clear local automation scope, a named owner, and a recovery path.
Production checklist
- Define the precise ingress, app, API, worker, database, and backup topology.
- Put services behind health checks and avoid a single-node control plane.
- Document the owner for restore, failover, and emergency access.
- Protect organization administration with the strongest authentication available.
- Keep secrets out of source control and audit logs.
- Test backup restoration and failover before an incident.
The project does not require a Cloud control plane for local work. Keep the user-facing Work client on its local server path, and add organization services only when a real identity, policy, connector, or hosted-worker requirement demands them. See Production operations for release gates and recovery evidence.