Orchestrator and sandbox

Run iPolloWork as a CLI host, resolve verified sidecars, and add a deliberate Docker or Apple container boundary when the task requires it.

ipollowork-orchestrator is the CLI-first host for iPolloWork Server and OpenCode. Use it when the product needs a host runtime without the Electron UI, when a remote client must pair to a workspace, or when an operator needs one status surface for both sidecars.

Host topologyThe orchestrator owns process assembly; the server owns workspace access

Do not collapse sidecar download policy, workspace authority, and sandbox mounts into a single unrestricted host process.

Orchestrator CLI

Process assembly and operator output

Start / serve

Starts iPolloWork Server and OpenCode with shared health and lifecycle observation.

Status / pairing

Prints connection information while redacting live credentials by default.

Sidecar resolution

Verified runtime sources

Server and OpenCode

Resolve from bundled, downloaded, or explicitly external sources.

Manifest check

Downloaded sidecars use a SHA-256 manifest; development overrides are explicit.

Execution boundary

Host or container

Workspace mount

The chosen workspace is the central filesystem boundary.

Optional sandbox

Docker or Apple container sidecars can add a Linux execution boundary.

Start a host intentionally

Install the CLI globally when a standalone host is the desired deployment unit:

npm install -g ipollowork-orchestrator
ipollowork start --workspace /path/to/workspace --approval auto

Use ipollowork serve --workspace /path/to/workspace or --no-tui when log-only operation is preferred. In a checked-out repository, source development can use the package's development command with explicit local sidecars:

pnpm --filter ipollowork-orchestrator dev -- \
  start --workspace /path/to/workspace --approval auto --allow-external

--allow-external is a development override, not a neutral production default. It makes the sidecar source visible rather than silently taking an arbitrary binary from the machine.

Sidecar policy is a release decision

Sidecar resolutionResolve a runtime source before accepting its process boundary

The host should report what was resolved, then health-check the complete path.

01Select source
Use the source policy: automatic, bundled, downloaded, or explicitly external.
02Verify artifact
Downloaded sidecars are retrieved through the orchestrator manifest with SHA-256 verification.
03Start pair
Start iPolloWork Server and OpenCode, keeping the workspace directory explicit.
04Prove use
Run host status and exercise the client path that will actually use the runtime.

The CLI supports --sidecar-dir or IPOLLOWORK_SIDECAR_DIR for the cache location, --sidecar-base-url and --sidecar-manifest for an approved artifact source, --sidecar-source for iPolloWork Server selection, and --opencode-source for OpenCode selection. --verbose or IPOLLOWORK_VERBOSE=1 makes the resolved-binary diagnostics visible.

Use sandbox mode when the task needs a container boundary

# Choose a supported backend automatically
ipollowork start --sandbox auto --workspace /path/to/workspace --approval auto

# Choose one deliberately
ipollowork start --sandbox docker --workspace /path/to/workspace --approval auto
ipollowork start --sandbox container --workspace /path/to/workspace --approval auto

--sandbox auto prefers Apple container on supported arm64 Macs and otherwise Docker. Docker requires the docker CLI; Apple container mode requires the container CLI. In sandbox mode, Linux-targeted sidecars are resolved as downloaded artifacts and arbitrary custom --*-bin overrides are not supported.

Extra mounts are allowlisted. Add only the data needed by the task, and declare an explicit name and read-only mode where appropriate:

ipollowork start --sandbox auto \
  --sandbox-mount "/path/on/host:datasets:ro" \
  --workspace /path/to/workspace

The host validates additional mounts against ~/.config/ipollowork/sandbox-mount-allowlist.json unless IPOLLOWORK_SANDBOX_MOUNT_ALLOWLIST selects another allowlist. A container is not permission to mount arbitrary host data.

Multi-workspace router mode

When several workspaces need the same agent host, use the daemon rather than starting one unmanaged OpenCode process per directory:

ipollowork daemon start
ipollowork workspace add /path/to/workspace-a
ipollowork workspace add /path/to/workspace-b
ipollowork workspace list --json

The router keeps one OpenCode process and switches workspaces just in time using the requested directory. Use IPOLLOWORK_DATA_DIR or --data-dir to isolate router state in tests. Dispose a materialized workspace instance explicitly when its lifecycle ends.

Operational checks

Use ipollowork status --ipollowork-url http://<host>:8787 --opencode-url http://<host>:4096 for the paired runtime. A smoke check can start services, verify health and SSE events, and exit cleanly:

ipollowork start --workspace /path/to/workspace --check --check-events

For JSON, correlation-ready logging set IPOLLOWORK_LOG_FORMAT=json and supply --run-id when your operations system needs a stable correlation value. Continue with Observability and recovery for the release gate and incident path.