Run your harness in the VM

Use SSH for a harness that expects a local shell, subprocesses, or direct filesystem access. It runs in the same Assemble VM used by the execution API, with project files under /workspace.

Open the session and request access

Build the SDK and set your service credentials as described in the quickstart. From the repository root, use the CLI:

node packages/cli/dist/index.js --json open my-cli-agent
node packages/cli/dist/index.js ssh SESSION_ID --expires-in 15

Keep the id, homeDirectory, and rootDirectory fields from the JSON returned by open. Replace SESSION_ID with that id. The second command prints a temporary SSH command and its expiry. Run that command in your terminal to connect. The CLI does not open the connection automatically.

The returned command contains access credentials. Use it in your own terminal and keep it out of shared logs.

Run your own agent

Inside the VM, change to the shared project directory:

cd /workspace
pwd

SSH initially uses the VM image's ordinary login home and working directory. Managed commands instead use session.homeDirectory as HOME. To share home-based harness configuration with those commands, set it explicitly before launching your agent. In the example below, replace HOME_DIRECTORY_FROM_SESSION and ROOT_DIRECTORY_FROM_SESSION with the exact homeDirectory and rootDirectory values returned when you opened the session:

export HOME='HOME_DIRECTORY_FROM_SESSION'
cd 'ROOT_DIRECTORY_FROM_SESSION'

Both the managed home and the image's login home live on the VM disk. Project files under rootDirectory use the persistent session filesystem. The service does not modify the image's login account or shell profile.

Install and launch your harness using its normal Linux instructions. Its runtime dependencies must be included in the VM image or installed there. Supply its model credentials inside your own environment; the session product key is not a model-provider key.

For applications that need output and completion tracking, launch an installed harness through session.exec() with its CLI command. A managed execution can run for up to one hour. Interactive SSH is appropriate when you need to control the terminal yourself.

Verify the shared files

Create a file through the SSH connection:

printf 'Created over SSH\n' > /workspace/ssh-note.txt

Then read it from your machine:

node packages/cli/dist/index.js read SESSION_ID ssh-note.txt

This checks that SSH and the API address the same working directory. A later successful pause/resume test covers retention on the same VM; replacement recovery is a separate verification.

Finish this connection

Stop the agent process and exit the shell. Revoke its grant using the access ID printed when it was created:

node packages/cli/dist/index.js ssh SESSION_ID --revoke ACCESS_ID
node packages/cli/dist/index.js pause SESSION_ID

Revocation requests and active process termination are separate operations. Processes started over SSH are outside managed-command coordination. Stop them before switching writers, pausing, or deleting the session.

Exiting SSH and pausing keep the persistent session. Delete it explicitly only when you want to remove its VM and files.

Persistence and history

Files under /workspace use the same ordinary writable session filesystem as the API and provided harness. Direct writes may remain dirty until fsync or a completed background flush makes them durable. Reading a file back in the same VM does not confirm its durability after VM loss. Installed software and home-directory changes depend on the retained VM disk; keep a reproducible image or setup recipe for recovery.

Direct writes bypass managed execution boundaries. Version 1 offers no automatic per-command rollback for either SSH or API writes. Read Persistence before combining agent modes or replacing a VM.