Choose your integration
Decide where your harness runs and which session operations it needs.
A harness is the part of your agent that calls a model, chooses tools, maintains conversation state, and decides when to stop. The session supplies the environment those tools operate on.
Choose where your harness runs and which parts your application manages. Follow the quickstart to connect with an operator-issued product key and local SDK packages.
| Remote harness | Harness inside the VM | Provided harness | |
|---|---|---|---|
| Harness runs | On your infrastructure | In the session VM | Through Assemble's agent service |
| You own | Model calls, agent loop, tool adapter | Agent installation, configuration, process | Prompts and run configuration |
| Session access | Execution and file APIs | Local shell and mounted files; SSH for interactive access | The four standard Pi tools wired to session operations |
| Best fit | Existing agent services | CLI agents and local-process integrations | Applications that need a ready agent loop |
Keep your existing agent service
Use the remote harness integration when your agent already runs in a backend or worker. Map its shell and file tools to the session's execution and file operations. Keep conversation storage, model choice, and orchestration in your application.
This path gives the session service an explicit boundary around each command, including output, exit state, timeout, and cancellation. The current API does not provide transaction-level file history or rollback.
Run an existing CLI agent
Use the in-VM integration when an agent expects to spawn local processes, read files directly, or run its own terminals. Install the agent in the image or bootstrap environment and point it at the session's project directory.
A direct shell process uses the same writable session filesystem as the API. Its writes bypass managed-command coordination and may remain dirty until flushed. Version 1 does not automatically roll back failed commands. See Persistence.
Let us supply the agent loop
Use the provided harness when you want to submit a task and consume agent events. It uses Pi with four tools connected to the session API.
This integration uses the same session service as external harnesses. It starts a fresh, memory-only Pi conversation for each request.
Choose one active writer
The service allows one managed command at a time per session and blocks file API writes and lifecycle changes while that command is running. A provided-agent request reserves the session for its whole conversation. SSH processes can write outside this coordination. Coordinate your agents and terminals so only one writer changes a project at a time.