iPolloWork Docs
Deployment

Observability and recovery

Operate iPolloWork with explicit health signals, scoped logs, release evidence, and a recovery path that preserves workspace ownership.

Good operations do not start with a dashboard. They start by separating what is actually unhealthy: the desktop application, iPolloWork Server, the OpenCode sidecar, a specific workspace, or an external connector. The evidence and recovery owner are different for each layer.

Health is a layered probe, not one boolean

QuestionFirst signalFollow-up signal
Can clients reach the local runtime?GET /healthGET /status and GET /capabilities
Can this caller access the workspace?GET /whoami and GET /workspacesthe workspace-specific config or event route
Can agent work run?ipollowork statusone small end-to-end task through the actual client path
Did a remote operation finish?resource ID returned by the requestcurrent Worker, connector target, discovery, or sync-event representation
Is an import or file action visible?explicit artifact or file-session readevent/catalog read-back after the intended operation

For a self-hosted runtime, do not publish only an HTTP reachability check. A deployment is useful only when a correctly scoped caller can reach the configured workspace and use the required capability.

Correlate without leaking secrets

The orchestrator can emit a unified log stream from OpenCode and iPolloWork Server. Use JSON output when logs enter a system that indexes structured fields:

IPOLLOWORK_LOG_FORMAT=json \
ipollowork start --workspace /path/to/workspace --run-id release-2026-07-15

The local server logs request method, path, status, and duration. OpenCode's log level can be passed through --opencode-log-level <DEBUG|INFO|WARN|ERROR> when the host starts it. Do not add client tokens, host tokens, provider keys, or raw pairing credentials to a run ID, shell history, copied logs, or support tickets.

Evidence loopCollect, classify, repair, then prove the original path

Every recovery should finish with the smallest real task that originally failed.

  1. 01Capture

    Record the exact user path, workspace ID, request time, status signal, and a redacted run correlation value.

  2. 02Classify

    Identify the owning boundary: UI, local server, sidecar, workspace configuration, or external connector.

  3. 03Repair narrowly

    Change the failing owner only—configuration, sidecar source, expired credential, or remote resource state.

  4. 04Re-prove

    Repeat the original path and re-read the health, status, event, artifact, or resource state that proves success.

Release gate: prove more than compilation

Use a staged release gate. The exact commands vary by delivery target, but the evidence must remain comparable:

  1. Static correctness — run the package's narrow type, test, or build check for the changed boundary.
  2. Artifact correctness — use package:dir when an unpacked Electron app is enough to validate the desktop flow; reserve a native package for installer verification.
  3. Runtime correctness — start the actual local server or orchestrator path and check health plus capabilities.
  4. User-path correctness — complete one focused task in the UI or remote client that uses the changed feature.
  5. Rollback readiness — know the previous artifact, configuration version, and owner responsible before changing a remote deployment.

The repository's ./ipollowork check is a verification command, not a deployment mechanism. package:dir creates a local validation artifact; package creates host-native installers. Neither command by itself pushes a release, changes GitHub tags.

Recovery playbooks

The server is reachable but a workspace cannot be used

Read GET /whoami, GET /workspaces, then the target workspace config and events. Check that the workspace declaration, token scope, approval posture, and CORS origin match the client actually in use. Restart only the owning server process after preserving the error and resolved configuration evidence.

The sidecar fails after a host change

Use ipollowork status, enable --verbose, and confirm the resolved sidecar policy before changing anything else. A downloaded, bundled, and explicitly external binary are different release inputs. Fix that source selection first, then rerun a small end-to-end task.

A destructive or permission-sensitive request is pending

Review it through the approval or owner flow. Do not bypass manual approval with a production-wide auto setting. If access is incorrect, repair the token or grant boundary, then repeat the request with the smallest appropriate scope.

For exact runtime construction continue with Orchestrator and sandbox. For private network and server configuration continue with Self-hosted topology.