agentkernel

Node.js SDK for agentkernel — run AI coding agents in secure, isolated microVMs.

Install

``bash
npm install agentkernel
`

Requires Node.js 20+. Zero HTTP dependencies (uses native fetch).

Quick Start

`typescript
import { AgentKernel } from "agentkernel";

const client = new AgentKernel();

// Run a command in a temporary sandbox
const result = await client.run(["echo", "hello"]);
console.log(result.output); // "hello\n"
`

Sandbox Sessions

Create a persistent sandbox with automatic cleanup:

`typescript
await using sb = await client.sandbox("my-project", {
image: "python:3.12-alpine",
});

await sb.run(["pip", "install", "numpy"]);
const result = await sb.run(["python3", "-c", "import numpy; print(numpy.__version__)"]);
console.log(result.output);
// sandbox auto-removed when scope exits
`

Exec Options

Run commands with a working directory, environment variables, or as root:

`typescript
const result = await client.execInSandbox("my-sandbox", ["npm", "start"], {
workdir: "/app",
env: ["NODE_ENV=production"],
sudo: true,
});
`

Works on sandbox sessions too:

`typescript
await using sb = await client.sandbox("dev");
await sb.run(["pip", "install", "-r", "requirements.txt"], {
workdir: "/app",
sudo: true,
});
`

Git Source Cloning

Clone a git repo into the sandbox at creation time:

`typescript
const sb = await client.createSandbox("my-project", {
image: "node:20-alpine",
source_url: "https://github.com/user/repo.git",
source_ref: "main",
});
`

Persistent Volumes

Mount volumes that persist across sandbox restarts:

`typescript
// First create volumes via CLI: agentkernel volume create mydata

const sb = await client.createSandbox("my-project", {
image: "node:20-alpine",
volumes: ["mydata:/data", "cache:/tmp/cache:ro"],
});

// Data in /data persists across sandbox restarts
await sb.run(["sh", "-c", "echo hello > /data/test.txt"]);
`

File Operations

Read, write, and delete files in a sandbox:

`typescript
// Write a file
await client.writeFile("my-sandbox", "app/main.py", "print('hello')");

// Read a file
const file = await client.readFile("my-sandbox", "app/main.py");
console.log(file.content);

// Delete a file
await client.deleteFile("my-sandbox", "app/main.py");

// Batch write multiple files at once
await client.writeFiles("my-sandbox", {
"/app/index.js": "console.log('hi')",
"/app/package.json": '{"name":"app"}',
});
`

Detached Commands

Run long-lived processes in the background and retrieve their output later:

`typescript
// Start a background process
const cmd = await client.execDetached("my-sandbox", ["python3", "train.py"]);
console.log(Started: ${cmd.id} (pid ${cmd.pid}));

// Check status
const status = await client.detachedStatus("my-sandbox", cmd.id);
console.log(status.status); // "running" | "completed" | "failed"

// Get logs
const logs = await client.detachedLogs("my-sandbox", cmd.id);
console.log(logs.stdout);

// Get stderr only
const stderr = await client.detachedLogs("my-sandbox", cmd.id, "stderr");

// List all detached commands
const all = await client.detachedList("my-sandbox");

// Kill a running command
await client.detachedKill("my-sandbox", cmd.id);
`

Streaming

`typescript
for await (const event of client.runStream(["python3", "script.py"])) {
if (event.type === "output") process.stdout.write(String(event.data.data));
}
`

Configuration

`typescript
const client = new AgentKernel({
baseUrl: "http://localhost:18888", // default
apiKey: "sk-...", // optional
timeout: 30000, // default: 30s
});
`

Or use environment variables:

`bash
export AGENTKERNEL_BASE_URL=http://localhost:18888
export AGENTKERNEL_API_KEY=sk-...
`

API

$3

Health check. Returns "ok".

$3

Run a command in a temporary sandbox.

`typescript
await client.run(["echo", "hello"]);
await client.run(["python3", "-c", "print(1)"], {
image: "python:3.12-alpine",
profile: "restrictive",
fast: false,
});
`

$3

Run a command with SSE streaming output. Returns an AsyncGenerator.

$3

List all sandboxes.

$3

Create a new sandbox. Options: image, vcpus, memory_mb, profile, source_url, source_ref, volumes.

$3

Get sandbox info.

$3

Remove a sandbox.

$3

Run a command in an existing sandbox. Options: env, workdir, sudo.

$3

Read a file from a sandbox.

$3

Write a file to a sandbox.

$3

Delete a file from a sandbox.

$3

Write multiple files to a sandbox in one request. files is a Record of path to content.

$3

Start a detached (background) command. Returns a DetachedCommand.

$3

Get the status of a detached command.

$3

Get stdout/stderr from a detached command. Pass "stderr" to get only stderr.

$3

Kill a detached command.

$3

List all detached commands in a sandbox.

$3

Create a sandbox session with automatic cleanup. Returns a SandboxSession that implements AsyncDisposable`.

License

MIT