Runtime lifecycle
Trace an iPolloWork task from the desktop shell through the local server, OpenCode sidecar, approvals, and session-owned artifacts.
iPolloWork is not a browser-only chat client. A normal desktop task crosses a small number of explicit boundaries: the Electron shell presents the work surface, the local server owns workspace-facing APIs, and OpenCode runs as an external agent sidecar. The optional Cloud control plane supplies organization capabilities; it does not replace the local execution path.
Each boundary has a different owner, credential shape, and failure mode. Keep the adapter at the edge rather than letting one layer silently impersonate another.
Desktop and browser UI
Owns native lifecycle and the visible desktop window.
Presents chat, Design, Video, files, and review controls.
Local iPolloWork Server
Owns workspace configuration, file sessions, extensions, artifacts, and approvals.
Keeps filesystem-backed work close to the workspace owner.
OpenCode through supported APIs
Executes agent work through its supported server, CLI, plugin, and config interfaces.
Add capability to the task; they do not become a second workspace database.
iPolloWork Cloud / Den API
Owns identity, roles, shared providers, hosted workers, and reusable organization configuration.
A local desktop task remains useful when no organization control plane is configured.
The task path
The task remains session-scoped all the way through execution, review, and subsequent revision.
- 01Frame
A person starts or continues a session with an outcome, workspace, and intended surface.
- 02Resolve
The local runtime resolves project context, approved tools, and the active session-owned artifact.
- 03Execute
OpenCode performs agent work through the supported sidecar boundary; tool calls remain observable.
- 04Review
The result opens in the appropriate editable surface and a person can revise, approve, or continue.
What the session owns
A session is the durable unit of work. It carries task context, activity, tool history, and the relationship to the current artifact. Design and Video are deliberately session-owned: a follow-up on the same deliverable belongs in the same session, while a new repository, a different owner, or a different permission boundary should start a new one.
The runtime should not silently move a task into a different workspace or rewrite an unrelated session. In particular, a Video composition is loaded from the session-specific project path, and a Design artifact remains editable as project files instead of being reduced to a screenshot.
Start paths are chosen by the job
| Need | Real boundary to use | Why |
|---|---|---|
| Work in the desktop app | Desktop shell plus local server | Native lifecycle and UI stay aligned with the checked-out application. |
| Develop the browser UI | pnpm dev:ui | Limits the loop to the React/Vite surface. |
| Run an agent host without the desktop app | ipollowork start or ipollowork serve | The orchestrator starts and observes the server plus OpenCode sidecar. |
| Keep several workspaces warm | ipollowork daemon start | The router keeps one OpenCode process and switches workspace context using the requested directory. |
The repository launcher is the safer default for project development because it prepares compatible local state. The orchestrator is the explicit host boundary when you need a CLI-first runtime rather than a desktop window.
Approval is part of the runtime contract
The local server separates ordinary client access from host-owner actions. Workspace writes are approval-gated. In development, automatic approval can shorten the loop; in a real shared or remote workspace, manual approval keeps an operator in control.
A request being received is not equivalent to a permission grant or a completed write.
- 01Request
A desktop client or remote client asks the local server to perform a workspace-facing action.
- 02Authorize
The server checks the caller token and the required owner or collaborator scope.
- 03Approve
Manual mode waits for a host decision; automatic mode is a deliberate local-development setting.
- 04Record
The client re-reads the resource, event stream, or artifact rather than assuming the write succeeded.
Sidecars and isolation
OpenCode is an external runtime dependency. iPolloWork integrates through documented APIs, CLI behavior, plugins, and config—not by altering OpenCode internals. The orchestrator can resolve iPolloWork Server and OpenCode sidecars from bundled, downloaded, or explicitly external sources. For source development, the launcher enables an isolated OpenCode development profile so normal personal configuration, auth, cache, and state are not reused accidentally.
This is also why a sidecar change needs an end-to-end check: verify the UI or client path that actually consumes it, not just that a process can start.
Read the right health signal
Use the health endpoint to establish reachability, then use status and capabilities to understand what the server actually resolved. For a specific workspace, use the workspace-specific health, configuration, event, and extension routes. An orchestrator host can run ipollowork status to inspect both the iPolloWork Server and OpenCode sidecar as one system.
For the operational commands, sidecar sourcing, sandbox options, and recovery evidence, continue with Orchestrator and sandbox and Observability and recovery.