Your first session

This guide uses local SDK packages with the hosted API or your local development service. It does not require a model or agent framework.

Before you start

You need Node.js 22.19 or later, npm 11 or later, the supplied Assemble SDK checkout, and an Assemble API key.

From the repository root, install and build the packages:

npm install
npm run build

The npm workspace links @assemble-workspace/sdk locally. The package has not been published to npm.

Set ASSEMBLE_BASE_URL=https://assemble-vms-api.fly.dev and ASSEMBLE_API_KEY to your operator-issued product key in your shell or development environment. Remote service URLs must use HTTPS; local development can use http://localhost:8787. Your Assemble API key provides access to the hosted service. docs.assemble.ai serves documentation; SDK requests go to the API URL.

Create a file and run a command

Save this as quickstart.mjs in the repository root:

import { AssembleClient } from "@assemble-workspace/sdk";

const client = new AssembleClient({
  apiKey: process.env.ASSEMBLE_API_KEY ?? "",
  baseUrl: process.env.ASSEMBLE_BASE_URL ?? "",
});

const session = await client.sessions.open({ name: "my-first-session" });
await session.files.write("hello.txt", "Hello from my session!\n");

const execution = await session.exec({ command: "cat hello.txt" });
for await (const event of execution.events()) {
  if (event.type === "stdout") process.stdout.write(event.data);
  if (event.type === "stderr") process.stderr.write(event.data);
}
const result = await execution.wait();
if (result.state !== "completed" || result.exitCode !== 0) {
  throw new Error(`Command ${result.state}; exit code ${result.exitCode}`);
}

console.log(`Session ID: ${session.id}`);
await session.pause();

Run it with node quickstart.mjs. The command should print Hello from my session!, followed by the session ID. A successful execution has state completed and exit code 0.

Opening an existing name under the same owner reuses that session. It stays allocated after this script exits and remains until explicitly deleted. The default image is terminal; use image: 'browser' when your configured service has a browser image.

The file API and commands use the same writable /workspace mount. This readback checks shared file access. Read Persistence for flush behavior and the additional checks needed before VM replacement.

Return to the same files

Opening the name again resumes the environment. Read the saved file through the file API:

const reopened = await client.sessions.open({ name: "my-first-session" });
const contents = await reopened.files.read("hello.txt");
console.log(new TextDecoder().decode(contents));
await reopened.pause();

Pausing keeps the session and its files. await session.delete() permanently deletes both the VM and its session files; use it only when you want to discard that session.

Connect your agent

Choose remote tool calls, a harness in the VM, or the provided Pi harness. If the example fails, start with Troubleshooting.