System architecture
Understand the local work runtime, the optional control plane, and the two API surfaces that connect them.
iPolloWork is designed as a local-first system. The desktop client, local server, workspace files, and agent sidecar can complete normal work without an organization Cloud deployment. When a team needs identity, shared capabilities, connector administration, or managed workers, the control plane adds those functions without replacing the local Work path.
This split is intentional. It keeps local files and immediate creative work close to the person doing the work, while keeping organization policy and reusable configuration in the systems that own them.
Each lane owns a different type of state. The client should use the interface belonging to that state instead of bypassing a boundary.
Person-facing and editable
Renders sessions, files, browser output, design, and video surfaces.
Owns native lifecycle, local permissions, and desktop integration.
Workspace execution boundary
Serves workspace state, approval gates, artifacts, and runtime adapters.
An external agent runtime reached through the supported server adapter.
Local source of truth
The directly editable project material and outputs.
Context, tool trace, approvals, and exported activity for a workspace.
Organization-level state
Identity, organizations, capabilities, connectors, and worker lifecycle.
Remote runtimes created only when a hosted worker is required.
The execution path
An agent task is a loop with explicit review points. The runtime should not silently switch to an unrelated client, a private local API must not become a public admin API, and a rendered output must remain editable in the surface where it was produced.
The same session can cross code, design, browser, and video work, but all execution remains observable through the local server boundary.
- 01Outcome
A person supplies a goal, constraints, files, repository, or URL.
- 02Session context
The client preserves task context and selects the needed work surface.
- 03Approval and tools
The local server brokers tool work and asks for approval when its policy requires it.
- 04Editable artifact
Files, visual canvas, browser state, or video scene can be inspected and revised.
Two API surfaces
The project exposes two different integration planes. Choosing the correct one prevents accidental coupling between a local workspace and organization administration.
| Surface | Owner | Typical address | Use it for | Do not use it for |
|---|---|---|---|---|
| Local iPolloWork server | The person or workspace host | http://127.0.0.1:8787 by default | Workspace files, sessions, local approval, artifacts, server status, and the supported OpenCode proxy | Organization membership, shared Cloud configuration, or managed worker provisioning |
| Den control plane | The organization | A configured iPolloWork Cloud base URL | Identity, organization scope, configuration resources, connectors, plugins, Skills, and hosted workers | Reaching directly into an arbitrary local file system or bypassing a workspace approval policy |
The local server documents /health, /status, /capabilities, /whoami, workspace routes, audit routes, and the /opencode/* proxy boundary. The control plane contract is maintained in packages/docs/openapi.json and described in the API reference.
Local work remains useful without Cloud
Cloud connection adds organization capabilities. It is not a prerequisite for a local project, local server, or the desktop work loop.
- 01Open a workspace
Launch the desktop or browser work surface against a local project.
- 02Run the local server
Keep workspace state, approval policy, artifacts, and runtime adapters on the local path.
- 03Use supported sidecars
Prepare OpenCode and Orchestrator through the repository launcher.
- 04Add Cloud later
Connect only when team identity, shared capabilities, or hosted workers are needed.
Design rules for integrations
- Let the server own workspace operations. A client should call the local server API rather than inventing a second local execution path.
- Keep OpenCode behind the supported adapter. It is an external sidecar, not an API surface for application code to modify directly.
- Make remote work explicit. A hosted worker begins with a worker lifecycle request. It is not silently created because a local task exists.
- Keep secrets at their owning boundary. Local server tokens, Cloud session tokens, provider credentials, and connector credentials should never be copied into artifacts or logs.
- Preserve a reversible review loop. Outputs should stay inspectable as files, editable visual structures, or recorded runtime state.
For the component-level package layout and exact commands, continue with Local development. For route shapes and authentication, continue with OpenAPI and integration.