Sessions

A session is a persistent Assemble VM and its project storage. It remains allocated until you delete it; finishing an agent run or closing an SSH connection does not delete the session. Reopen the same session for a new task or a different harness.

Each session has one primary VM with persistent project storage mounted exclusively at /workspace as an ordinary writable directory. The public API has no automatic replacement operation.

flowchart LR
  Remote[Your remote harness] --> Service[Session service]
  Provided[Provided Pi harness] --> Service
  Service --> VM[Assemble VM]
  SSH[SSH / in-VM harness] --> VM
  VM --> Disk[Session files]

VM

The VM runs commands, agents, language runtimes, package managers, and optional browser/desktop software. Its retained disk also holds the operating system and home-directory state.

A VM can be paused or stopped while retaining its disk. Replacing a VM creates a different durability boundary: VM-local changes need to be recreated or restored.

Working directory and home

session.rootDirectory is /workspace, the persistent project directory used by file operations and managed commands. session.homeDirectory contains the home-directory path that managed commands receive as HOME. Use the value returned by your session when configuring your harness.

A raw SSH connection starts with the image's ordinary login home and working directory. Change to session.rootDirectory to access shared project files. If your harness should share home-based configuration with managed commands, explicitly export HOME to session.homeDirectory before launching it. Both home directories are stored on the VM disk and need reconstruction after VM replacement. Keep persistent project files under session.rootDirectory.

Session filesystem

The file API, commands, SSH processes, and provided Pi tools all use the same writable session filesystem. Pending writes can remain buffered inside the VM until they are flushed to persistent storage. Flushed files can be retained and mounted into a replacement VM separately from the old VM's disk.

Read Persistence for durability boundaries and clean shutdown. Version 1 has no automatic per-command rollback.

Execution

An execution is one requested command or process. Useful execution output includes stdout, stderr, completion status, and an exit code. Agent runs may create many executions against the same session.

The remote execution API coordinates managed commands. In-VM processes also use the computer but can operate outside that boundary.

Agent run

An agent run is one task a harness performs using an existing session. The harness owns model calls, tool selection, and conversation state. Completing the run leaves the session and its files available for later work.

Persist any task context your own harness needs in your application or in files you deliberately save. A durable working directory alone does not reconstruct a conversation.