Local Server reference
Use the filesystem-backed iPolloWork Server API for local workspaces, approvals, extensions, artifacts, and batched file sessions.
The iPolloWork Server is the local, filesystem-backed API for remote desktop and browser clients. It is independent from the Electron app and must not be confused with the organization-facing Den API. Its job is to expose a private workspace runtime—not to become a public administration service.
Establish the server boundary first
The server maps clients to configured workspaces, gates writes through approval, and proxies OpenCode only through its explicit routes.
Desktop or approved remote client
Identifies a normal local client at the server boundary.
Names the configured workspace; never infer it from a display name.
Filesystem-backed runtime
Own configuration, extensions, events, import/export, inbox, artifacts, and file sessions.
Gate workspace writes instead of treating network reachability as authority.
Administrative authority
Uses an owner-scoped bearer token or host token for host APIs and approval decisions.
Controls host, port, workspaces, CORS origins, and the approval posture.
Discover before writing
The server exposes three useful levels of read-only discovery:
| Route | Use it to answer | Do not use it to infer |
|---|---|---|
GET /health | Is the server reachable? | Whether a particular workspace is configured and ready. |
GET /status | What is the runtime reporting? | Whether the caller may make an owner-level change. |
GET /capabilities | Which optional server capabilities are advertised? | Whether an integration has been authorized for this task. |
GET /workspaces | Which workspaces can this caller see? | A permission to alter any of them. |
GET /whoami | Which server identity and scope is active? | A Cloud organization identity. |
For a workspace, read GET /workspace/:id/config, GET /workspace/:id/events, GET /workspace/:id/plugins, GET /workspace/:id/skills, GET /workspace/:id/mcp, or GET /workspace/:id/commands before making a corresponding write. That keeps the client aligned with current server state rather than an old desktop cache.
Authentication and approval are separate checks
Normal clients authenticate with Authorization: Bearer <client-token>. Host APIs accept either an owner-scoped bearer token or X-iPolloWork-Host-Token. A host credential authorizes the administrative boundary; workspace writes are still subject to the server's configured approval mode.
Treat every write as a request through an authorization and approval boundary, then inspect the resulting resource or event.
- 01Identify
Resolve server health, caller scope, workspace ID, and the current resource representation.
- 02Request
Send the smallest specific mutation to the matching workspace route.
- 03Approve
In manual mode, the host allows or denies the pending operation; auto mode is for deliberate development use.
- 04Verify
Re-read the resource, artifact, configuration, or event stream and surface any denied state.
Route families
| Family | Read | Write | Operational purpose |
|---|---|---|---|
| Workspace configuration | /workspace/:id/config | PATCH /workspace/:id/config | Read or update the configured workspace runtime shape. |
| Extensions | /plugins, /skills, /mcp, /commands | matching POST / DELETE routes | Add or remove named extensions without bundling them into a generic opaque setting. |
| Artifacts and inbox | /artifacts, /inbox | artifact reads and multipart inbox upload | Move task inputs and produced artifacts through an explicit workspace boundary. |
| Import / export | /export, /import/preview | /import | Inspect before importing; do not overwrite a workspace blindly. |
| Approvals and tokens | /approvals, /tokens | approval reply and token lifecycle routes | Keep host-owner governance visible and auditable. |
| OpenCode proxy | /opencode/* or /w/:id/opencode/* | matching supported proxy method | Reach the supported runtime sidecar through the local server boundary. |
File sessions are short-lived, batched work channels
The server provides file-session routes so a remote client can operate on a workspace without treating the filesystem as a permanently mounted drive. Create a file session, read the catalog snapshot, batch reads or writes, observe events, renew only when the session is still needed, then close it.
The protocol keeps catalog reads, batched operations, and change observation tied to one explicit session ID.
- 01Create
POST `/workspace/:id/files/sessions` with the intended access mode and retain the returned session ID.
- 02Inspect
Read the catalog snapshot and only request the paths required for the task.
- 03Mutate
Use batch read, write, or ops routes; do not issue unbounded filesystem scans from the client.
- 04Observe and close
Use catalog events when needed, then renew or delete the session explicitly.
Useful routes are POST /workspace/:id/files/sessions, POST /files/sessions/:sessionId/renew, GET /files/sessions/:sessionId/catalog/snapshot, GET /files/sessions/:sessionId/catalog/events, POST /files/sessions/:sessionId/read-batch, POST /files/sessions/:sessionId/write-batch, POST /files/sessions/:sessionId/ops, and DELETE /files/sessions/:sessionId.
Configure with explicit intent
The default config file is ~/.config/ipollowork/server.json; IPOLLOWORK_SERVER_CONFIG or --config can change its path. The real server configuration covers host and port, approval mode and timeout, workspace declarations, CORS origins, token storage, inbox/outbox behavior, sandbox advertisement, and OpenCode connection settings. Do not copy a permissive development configuration into a remote environment.
For server startup and production ownership, use Self-hosted topology. For organization resources, API keys, hosted workers, and shared connectors, use Control-plane resource map instead.