Workspace and agents
Understand the session, local runtime, files, browser, and permission boundaries behind each task.
An iPolloWork session is the durable context for a task. It connects the conversation to files, tool runs, browser state, generated artifacts, and the surface currently open in the workspace.
The session relates intent, tool activity, and one editable artifact surface without turning every task into a global workspace mutation.
What should happen
A clear requested result, owner, repository or workspace, and review expectation.
Context and decisions that should stay attached to the task.
How it happens
Routes task work through the local server and supported OpenCode sidecar.
Files, browser, Skills, plugins, and MCP calls remain attached to the task boundary.
What can be reviewed and edited
Code, Design, Video, browser output, or another session-owned result.
The result is re-opened and checked in the surface that owns it.
What stays in the session
| Layer | Responsibility |
|---|---|
| Session | Task instruction, conversation, activity, and the current work context. |
| Local server | Routes agent requests, manages local project state, and exposes the local API. |
| OpenCode | Executes the underlying agent runtime and can be upgraded independently. |
| Work surfaces | Render and edit code, design artifacts, video compositions, browser work, and task output. |
| Permissions | Make requested file, browser, tool, and connector actions visible before they execute. |
Keep work scoped
Create a new session when the task has a different repository, owner, outcome, or permission boundary. Keep follow-up revisions in the existing session when they modify the same artifact or decision.
This separation is especially important for Design and Video. Their artifacts are owned by the session so that a new task cannot silently alter a previous project.
Use a new session when any of the following changes: the workspace path, the user or team that owns the work, the main output, the expected permission level, or the artifact type. Keep the same session for a review, correction, extension, or alternate version of the same work. This avoids losing relevant context while preventing a broad, ambiguous session from acquiring authority over unrelated work.
Use tools deliberately
Skills, plugins, MCP servers, and browser automation are extensions of a task. Add only the capability needed for the outcome and keep its authorization narrow. If a task needs a custom model or MCP server, configure it first in Models, tools, and MCP.
Optional Cloud connection
Local iPolloWork does not require an account. iPolloCloud is the optional control plane for identity, organizations, entitlements, hosted workers, administration, and commercial Apps. It is not in the local agent execution path.
Desktop and UI -> local iPolloWork server -> OpenCode runtime
|
+-> optional iPolloCloud identity and control requests
A response is intermediate state. The durable outcome is a reviewable artifact and a clear record of what changed.
- 01Scope
Choose the existing session or create a new one using workspace, outcome, and permission boundaries.
- 02Act
Use the local runtime and only the approved capabilities needed for the request.
- 03Open
Present the result in Code, Design, Video, browser, or the appropriate task surface.
- 04Continue or close
Keep revisions in the session, or archive it after the outcome and evidence are clear.
For the runtime itself, see Runtime lifecycle. For local file and workspace endpoints, see Local Server reference.