Getting started with the SDK

This guide introduces the Python, TypeScript, and Rust SDKs through a small example that creates a VM and runs a command. Choose a language below for its installation requirements, example, and explanation of the result.

The API references describe Capsem 0.7.1. The TypeScript example works with the published npm SDK 0.7.0; until the Python and Rust 0.7.1 packages are published, their installation instructions use the matching source revision.

About

Use the Capsem SDK to create a VM, run commands, and inspect its activity from your application.

Installation

Requires Python 3.11 or later. This example targets Capsem 0.7.1. Until its Python package is published, install the SDK from the 0.7.1 source revision; PyPI’s capsem 0.3.2 does not provide this API.

python -m pip install "capsem @ git+https://github.com/google/capsem.git@3c17b44f7a4c0457cb4b168df829daf293415c12#subdirectory=sdk/python"

Install Capsem and start it on your computer before using the SDK.

Usage

Hypervisor() connects to Capsem running on your computer without requiring you to copy a gateway URL or token.

Once Capsem is running, create a VM and run a command inside it. Use an unused VM name in place of sdk-demo.

Run these direct-await statements in a notebook or IPython.

from capsem import Hypervisor

capsem = Hypervisor()
vm = await capsem.create(name="sdk-demo", image="claude-code")
result = await vm.exec("echo hello", timeout_secs=60)
print(result)
await vm.stop()
await capsem.close()

name keeps the VM for later use: stopping it preserves your work so you can start it again or duplicate it. image selects a Capsem prebuilt container image or your own OCI image when permitted by your administrator. Learn about image selection.

The example runs echo hello, displays its output, and leaves sdk-demo stopped with its work preserved.

Pass labels={"suite": "eval"} to create(...) to attach advisory metadata. VM inventory includes those labels. Forks inherit them by default; fork(name, labels={}) clears them and a nonempty map replaces them.

Use managed scopes to remove temporary VMs automatically. Look up methods and options in the Python SDK reference, and handle failed commands with Errors and recovery.

About

Use the Capsem SDK to create a VM, run commands, and inspect its activity from your application.

Installation

Requires Node.js 20 or later for this example.

npm install @capsem/sdk@0.7.0

Install Capsem and start it on your computer before using the SDK.

Usage

new Hypervisor() connects to Capsem running on your computer in Node.js without requiring you to copy a gateway URL or token.

Once Capsem is running, create a VM and run a command inside it. Use an unused VM name in place of sdk-demo.

Use a Node.js ES module with top-level await.

import {decodeExecOutput, Hypervisor} from '@capsem/sdk';

const capsem = new Hypervisor();
const vm = await capsem.create({name: 'sdk-demo', image: 'claude-code'});
const result = await vm.exec('echo hello', {timeout_secs: 60});
console.log(new TextDecoder().decode(decodeExecOutput(result.stdout)));
await vm.stop();
capsem.close();

The example runs echo hello, displays its output, and leaves sdk-demo stopped with its work preserved.

Use managed scopes to remove temporary VMs automatically. Look up methods and options in the TypeScript SDK reference, and handle failed commands with Errors and recovery.

About

Use the Capsem SDK to create a VM, run commands, and inspect its activity from your application.

Installation

This example targets Capsem 0.7.1 and Rust 1.91 or later. Until the SDK is published on crates.io, add it from the 0.7.1 source revision:

cargo add capsem-sdk --git https://github.com/google/capsem.git --rev 3c17b44f7a4c0457cb4b168df829daf293415c12

Install Capsem and start it on your computer before using the SDK.

Usage

Hypervisor::local() connects to Capsem running on your computer without requiring you to copy a gateway URL or token.

Once Capsem is running, create a VM and run a command inside it. Use an unused VM name in place of sdk-demo.

Use these statements inside your application’s async context returning Result<(), Box<dyn std::error::Error>>.

use capsem_sdk::{CreateOptions, Hypervisor};

let capsem = Hypervisor::local()?;
let vm = capsem.create(CreateOptions {
    name: Some("sdk-demo".into()),
    image: Some("claude-code".into()),
    ..Default::default()
}).await?;
let result = vm.exec("echo hello", Some(60)).await?;
println!("{}", String::from_utf8_lossy(&result.stdout.decode()?));
vm.stop().await?;

The example runs echo hello, displays its output, and leaves sdk-demo stopped with its work preserved.

For a guest browser request, call browser::BrowserCallback::prepare(&vm, &request.url).await before opening the URL in the client’s browser. Retain the returned handle while the browser signs in, then call close().await when cancelling or replacing the attempt. Ordinary web links return None. A callback accepts one matching path/state on the client’s exact loopback port and returns it through an authenticated workload preview; no raw port is published. The listener expires after ten minutes. Do not log the URL, state, callback query or preview credentials.

This callback transport currently requires a local gateway. Hosted preview origins must become client-reachable before remote loopback callbacks can be enabled; the SDK refuses that case instead of listening on the server’s host.

For more, use the SDK guides or the Rust SDK reference. Use managed scopes to remove temporary VMs automatically. Look up methods and options in the Rust SDK reference, and handle failed commands with Errors and recovery.