Production operations

Prepare a private or organization deployment with explicit ownership, health, recovery, and release gates.

Production readiness is not a single command. It is a set of verified boundaries: what is local, what is organization-managed, which service owns a credential, how a runtime becomes healthy, and how an operator restores state after a failure.

The iPolloWork repository supports a local desktop and local server path without a Cloud control plane. A private organization deployment should add only the control-plane and hosted-runtime capabilities it actually needs.

Operations topologyOperate each layer through its owning health and recovery path

The diagram separates user work, local runtime, optional organization services, and the operational evidence that proves each layer is safe to use.

Person and device

Local-first user path

Desktop client

The Electron client and editable work surfaces.

Local workspace

Repositories, artifacts, and user-controlled work material.

Local runtime

Work execution

iPolloWork server

Workspace HTTP API, approval gates, audit, artifacts, and runtime adapters.

OpenCode sidecar

A separately managed agent runtime checked through the supported adapter.

Organization plane

Deploy only when required

Identity and policy

Organization access, roles, shared configuration, and governance.

Workers and connectors

Hosted runtime lifecycle and external integration state.

Operations evidence

What an operator can verify

Health and capability probes

Reachability, runtime compatibility, and scoped readiness checks.

Backup and audit trail

Restorable data, owner, recovery procedure, and exported evidence.

Pick a deployment profile

Profile	Include	Use when	Do not assume
Local desktop	Electron app, local server, supported sidecars, local project files	One person or a local project needs agent work against files	Organization identity or remote Workers are required
Private workspace server	`ipollowork-server`, workspace configuration, a bounded network path	A controlled machine or VPC hosts a workspace runtime	It automatically provides a complete organization control plane
Organization control plane	Identity, organization resources, connectors, shared capabilities, optional Workers	Teams need policy, shared configuration, and managed runtime lifecycle	It replaces the local editable Work experience

Configure the local server intentionally

The local server can run from the compiled binary:

ipollowork-server --workspace /path/to/workspace --approval auto

Or from source during development:

pnpm --filter ipollowork-server dev -- \
  --workspace /path/to/workspace \
  --approval auto

The default configuration file is ~/.config/ipollowork/server.json. It holds host, port, approval mode and timeout, known workspaces, and CORS origins. Environment variables can override the config path, host and port, tokens, approval mode, workspace list, CORS origins, OpenCode connection, token store, and related runtime settings.

For a normal human-operated installation, preserve the default manual approval behavior. --approval auto is useful for local development or a tightly governed automation boundary, not as an unreviewed production default.

Health and readiness checks

Use health checks to prove the layer you will actually route traffic to:

Check	Meaning	Operational response
`GET /health`	Local server reachability and server version information	Fail closed for new traffic if the process is unavailable.
`GET /status` and `/capabilities`	Server state and supported runtime features	Reconcile incompatible clients or disabled capability boundaries.
`GET /w/{workspaceId}/health`	Scoped workspace server health	Isolate one bad workspace instead of declaring every workspace unavailable.
Supported OpenCode health path	Sidecar reachability through the server adapter	Repair the sidecar boundary, not the client UI, when it is unhealthy.

Do not publish a path externally merely because a generic health endpoint responds. Health endpoints prove liveness, not authorization scope, data recovery, or tenant isolation.

Release gates

Release gateA narrow, verifiable production change

Run the gates in order. If one fails, stop the rollout at that boundary and fix the owner rather than widening the change.

01Configuration
Review resolved host, workspace, CORS, approval, credential, and ingress configuration without exposing secrets.
02Build and checks
Run the repository check flow, narrow tests, and diff validation before producing an artifact.
03Staged health
Verify server, scoped workspace, sidecar, and enabled control-plane endpoints through their real route.
04Recovery proof
Name the backup location, restore owner, rollback condition, and audit evidence before broad traffic changes.

Recovery and evidence

Before an organization rollout, document these answers in the operator runbook:

Which state is on the local device, in a workspace, and in the organization control plane?
Who can rotate each server, host, owner, session, and provider credential?
Where is the backup, how recently was it restored in a test, and who owns the restore decision?
Which health result blocks new task execution, and which result only degrades an optional Cloud feature?
Which resource IDs, deployment revision, and audit records are needed to investigate an incident without leaking secrets?

For repeatable development and release commands, follow Local development and Desktop packaging. For specific private runtime boundaries, read Self-hosted topology.