Guides / SDKs / Overview

SDKs in five languages

kosa8 has an official SDK for Python, TypeScript, Go, Ruby and Java. Each one lets your program create sealed machines, run code in them, save their state and roll it back. All five do the same things with the same names, so you can switch languages without relearning anything.

In plain words

When an AI agent writes code and runs it, that code can do anything your user account can do. It can delete files, read your SSH keys, or send your API keys to someone else. kosa8 stops that by running the code in a sandbox: a small, separate computer that boots in seconds on your own machine. Code in the sandbox cannot see your files unless you share them, and cannot reach the internet unless you allow it.

The kosa8 app (a background program called the daemon) runs those sandboxes. An SDK is a library your own program uses to talk to it. With a few lines of code you can:

• Create a sandbox, choosing how much CPU, memory and network it gets.
• Run commands in it and read their output, live or when they finish.
• Take a checkpoint, a save point, before a risky step, and rewind to it if the step goes wrong. Running programs come back exactly where they were.
• Fork a sandbox into several copies and try different ideas at once, then keep the one that worked (explore).
• Delete it when you are done, optionally overwriting its disks.

Everything happens on your machine. Nothing is uploaded, and there is no account to create.

Install

First install kosa8 itself (Install) and make sure it is running (kosa8 daemon start). Then add the SDK for your language:

None of the SDKs has a runtime dependency. Each uses only its language's standard library, so adding one brings nothing else into your build. All are MIT licensed, and the source is on GitHub: kosa8-py, kosa8-js, kosa8-go, kosa8-rb, kosa8-java.

The same program in every language

Create a sandbox with no network, run a command, delete it.

# Python
import kosa8
k = kosa8.Kosa8Client()
k.create_sandbox(name="demo", egress="deny")
k.pull_into_sandbox("demo", "alpine:latest")
print(k.run("demo", "alpine:latest", ["echo", "hello"]).stdout)
k.delete_sandbox("demo")

// TypeScript
import { Kosa8Client } from "@kosa8/sdk";
const k = new Kosa8Client();
await k.createSandbox({ name: "demo", egress: "deny" });
await k.pullIntoSandbox("demo", "alpine:latest");
console.log((await k.run("demo", "alpine:latest", ["echo", "hello"])).stdout);
await k.deleteSandbox("demo");

// Go
k, _ := kosa8.New(kosa8.Options{})
k.CreateSandbox(ctx, kosa8.CreateOptions{Name: "demo", Egress: "deny"})
k.PullIntoSandbox(ctx, "demo", "alpine:latest")
res, _ := k.Run(ctx, "demo", "alpine:latest", []string{"echo", "hello"}, nil)
fmt.Print(res.Stdout())
k.DeleteSandbox(ctx, "demo", kosa8.DeleteOptions{})

# Ruby
require "kosa8"
k = Kosa8::Client.new
k.create_sandbox(name: "demo", egress: "deny")
k.pull_into_sandbox("demo", "alpine:latest")
puts k.run("demo", "alpine:latest", ["echo", "hello"]).stdout
k.delete_sandbox("demo")

// Java
Kosa8Client k = Kosa8Client.builder().build();
k.createSandbox(new Options.Create().name("demo").egress("deny"));
k.pullIntoSandbox("demo", "alpine:latest");
System.out.print(k.run("demo", "alpine:latest", List.of("echo", "hello")).stdout());
k.deleteSandbox("demo");

The names follow each language's own style (create_sandbox in Python and Ruby, createSandbox in TypeScript and Java, CreateSandbox in Go), but the operations, their options and what they return are the same.

What every SDK covers

A few words you will see

Daemon

The kosa8 background program, kosa8d. The SDKs send it requests over a local socket file, ~/.kosa8/run/kosa8.sock.

Sandbox

A small virtual machine with its own disk, memory and network rules.

Image

A container image such as python:3.12-alpine. Code runs in a container made from an image, inside the sandbox.

Egress

What the sandbox may reach on the network: deny (nothing), any, fakenet (a fake internet for malware analysis) or allow:pypi.org,github.com (only those hosts).

Snapshot

A saved copy of a running sandbox: memory, running programs and disks.

Checkpoint

A snapshot on a sandbox's own undo stack, named <sandbox>-ckpt-N. Ten are kept per sandbox.

Fork

Several live copies of one sandbox, made from a single snapshot.

Approval

A signature from a person, required by your organisation's policy before some actions. You pass it with the call that needs it.

Where to go next