Getting started with the SDK

Python

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.

python -m pip install capsem

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

Usage

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.

For more, use the SDK guides or the Python SDK reference.

TypeScript

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

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

Usage

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 {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(String(result));
await vm.stop();
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.

For more, use the SDK guides or the TypeScript SDK reference.

Rust

About

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

Installation

Add the SDK to your Rust project:

cargo add capsem-sdk

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

Usage

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 a Result.

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!("{result}");
vm.stop().await?;

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.

For more, use the SDK guides or the Rust SDK reference.