Choose a control surface

This guide helps you choose the Compozy surface for the actor in front of you: a human operator, a script, a managed Compozy agent, a trusted external MCP client, or a browser integration. Start with the actor and its trust boundary; the surfaces are not interchangeable authority shortcuts.

The short version

Actor	Trust boundary	Preferred surface	Use when
Human on the daemon host	The OS account and selected `COMPOZY_HOME` carry operator authority.	CLI	You need an explicit command, shell pipeline, or `-o json` result.
Human in the browser	The daemon's HTTP listener defines who can reach the UI and API.	Web UI	You need to scan current runtime state visually.
Managed Compozy agent	Session identity, workspace binding, tool policy, and capability gates apply.	Native `compozy__*` tool	You need a structured, policy-filtered runtime operation inside the managed session.
Trusted external MCP client	The relay binds the client to one workspace and delegates operator authority.	`compozy mcp serve`	An external agent client needs the approved Host API subset over stdio or loopback HTTP.
Local process on the daemon host	Filesystem access to the UDS socket controls local reach.	UDS	You need daemon APIs without exposing another TCP listener.
Browser or intentionally remote integration	The configured TCP listener is part of the deployment's network boundary.	HTTP/SSE	You need request/response APIs or ordered live events over Server-Sent Events.

Use CLI Reference for exact commands, API Reference for HTTP/UDS contracts, Tools for the native registry, and MCP Serve for external-client projection.

Choose by actor

A human operator is doing one task

Start with the CLI. It is explicit, scriptable, and mirrors daemon state directly.

compozy status
compozy session list
compozy session events sess_1234 --follow

What happened: the operator asked the daemon for current state, then followed the durable event stream for one session.

A managed agent needs to inspect or mutate Compozy

Prefer a callable native tool. Resolve compozy__tool_search, inspect the selected descriptor through compozy__tool_info, then invoke the returned tool reference with that live schema. Availability and risk policy are part of the result.

Use CLI or HTTP/UDS only when the native tool is absent, denied, too narrow, or explicitly requested. Never scrape the web UI or guess a tool schema from its ID.

A trusted external agent client needs Compozy

Run a foreground MCP relay bound to the intended workspace:

compozy mcp serve --workspace checkout-api

The stdio relay talks to the running daemon. It does not start another daemon or open stores directly. The spawning process receives the published operator methods for that workspace, so launch it only for a trusted client. Use the authenticated loopback HTTP mode documented in MCP Serve when the client cannot spawn stdio.

A browser or integration needs live updates

Use HTTP plus SSE. Polling hides ordering and makes recovery harder; Compozy events are already append-only runtime records.

curl http://localhost:2123/api/status
curl 'http://localhost:2123/api/workspaces/ws_alpha/sessions/sess_1234/transcript?limit=200'
curl -N \
  -H 'Last-Event-ID: 42' \
  'http://localhost:2123/api/workspaces/ws_alpha/sessions/sess_1234/stream?epoch=3&generation=7&limit=200'

What happened: the browser or integration reads a bounded transcript page, retains its epoch, generation, and applied cursor, then subscribes to fenced transcript deltas. Use the values returned by your own page instead of the example values above.

Add frames=raw when the integration needs raw persisted event rows instead of transcript frames.

A local tool should not depend on TCP

Use the UDS transport. It keeps daemon access local to the runtime home and matches the same shared API handler contracts used by HTTP.

compozy status
compozy doctor -o json

What happened: the CLI talked to the daemon over the local socket and returned structured health data without exposing a public listener.

Common decisions

Start or stop a daemon

Use the CLI:

compozy daemon start
compozy status
compozy daemon stop

Then open Daemon Operations when you need supervision, foreground logs, socket paths, or process details.

Inspect a session

Use CLI first, then web UI when visual scanning helps:

compozy session status sess_1234 -o json
compozy session history sess_1234
compozy session events sess_1234 --follow

For the lifecycle model behind those commands, read Session Lifecycle.

Let another system watch Compozy

Use HTTP/SSE. The API route map lists the implemented route families and marks which routes are generated from OpenAPI today; the guides explain when a route is the right tool.

Start with:

Let agents manage work

Inside a managed session, use the native task and autonomy tools exposed by the live registry. Read-only catalog work starts with compozy__task_list; claiming, heartbeating, completing, failing, and releasing a run use the session-bound compozy__task_run_* tools. Inspect every descriptor before the first call.

The CLI and HTTP/UDS expose equivalent operator paths when a native tool is unavailable or when a person needs to compare the same daemon state. The web UI may present that state, but it is not an agent automation interface.

Keep operator-only authority on control surfaces

Daemon lifecycle, raw secrets, provider bootstrap, MCP OAuth, trust roots, destructive repair, and cross-session terminal-state mutation stay on CLI, HTTP, or UDS unless the live registry explicitly exposes a scoped tool. compozy mcp serve does not widen this boundary; it publishes only its approved workspace-bound Host API subset.

Next steps

Use Debug a Failed or Stuck Session when the surface reports an unhealthy state.
Use Coordinate Agents over Compozy Network when one session needs to find or delegate to another.
Use CLI Reference for exact commands and flags.

On this page