|
| 1 | + |
| 2 | +# Node.js SDK |
| 3 | + |
| 4 | +Official Node.js client for agentkernel. Zero HTTP dependencies — uses native `fetch`. |
| 5 | + |
| 6 | +- **Package**: [`agentkernel`](https://www.npmjs.com/package/agentkernel) |
| 7 | +- **Source**: [`sdk/nodejs/`](https://github.com/thrashr888/agentkernel/tree/main/sdk/nodejs) |
| 8 | +- **Requires**: Node.js 20+ |
| 9 | + |
| 10 | +## Install |
| 11 | + |
| 12 | +```bash |
| 13 | +npm install agentkernel |
| 14 | +``` |
| 15 | + |
| 16 | +## Quick Start |
| 17 | + |
| 18 | +```typescript |
| 19 | +import { AgentKernel } from "agentkernel"; |
| 20 | + |
| 21 | +const client = new AgentKernel(); |
| 22 | + |
| 23 | +// Run a command in a temporary sandbox |
| 24 | +const result = await client.run(["echo", "hello"]); |
| 25 | +console.log(result.output); // "hello\n" |
| 26 | +``` |
| 27 | + |
| 28 | +## Configuration |
| 29 | + |
| 30 | +```typescript |
| 31 | +const client = new AgentKernel({ |
| 32 | + baseUrl: "http://localhost:8080", // default |
| 33 | + apiKey: "sk-...", // optional |
| 34 | + timeout: 30000, // default: 30s |
| 35 | +}); |
| 36 | +``` |
| 37 | + |
| 38 | +Or use environment variables: |
| 39 | + |
| 40 | +```bash |
| 41 | +export AGENTKERNEL_BASE_URL=http://localhost:8080 |
| 42 | +export AGENTKERNEL_API_KEY=sk-... |
| 43 | +``` |
| 44 | + |
| 45 | +## Running Commands |
| 46 | + |
| 47 | +### Basic Execution |
| 48 | + |
| 49 | +```typescript |
| 50 | +const result = await client.run(["python3", "-c", "print(1 + 1)"]); |
| 51 | +console.log(result.output); // "2\n" |
| 52 | +``` |
| 53 | + |
| 54 | +### With Options |
| 55 | + |
| 56 | +```typescript |
| 57 | +const result = await client.run(["npm", "test"], { |
| 58 | + image: "node:22-alpine", |
| 59 | + profile: "restrictive", |
| 60 | + fast: false, |
| 61 | +}); |
| 62 | +``` |
| 63 | + |
| 64 | +### Streaming Output |
| 65 | + |
| 66 | +Returns an `AsyncGenerator<StreamEvent>` for real-time output: |
| 67 | + |
| 68 | +```typescript |
| 69 | +for await (const event of client.runStream(["python3", "script.py"])) { |
| 70 | + switch (event.type) { |
| 71 | + case "output": |
| 72 | + process.stdout.write(String(event.data.data)); |
| 73 | + break; |
| 74 | + case "done": |
| 75 | + console.log("Exit code:", event.data.exit_code); |
| 76 | + break; |
| 77 | + case "error": |
| 78 | + console.error("Error:", event.data.message); |
| 79 | + break; |
| 80 | + } |
| 81 | +} |
| 82 | +``` |
| 83 | + |
| 84 | +## Sandbox Management |
| 85 | + |
| 86 | +### Create and Execute |
| 87 | + |
| 88 | +```typescript |
| 89 | +// Create a sandbox |
| 90 | +const sandbox = await client.createSandbox("my-project", { |
| 91 | + image: "python:3.12-alpine", |
| 92 | +}); |
| 93 | + |
| 94 | +// Execute commands |
| 95 | +const result = await client.execInSandbox("my-project", ["pip", "install", "numpy"]); |
| 96 | + |
| 97 | +// Get info |
| 98 | +const info = await client.getSandbox("my-project"); |
| 99 | + |
| 100 | +// List all |
| 101 | +const sandboxes = await client.listSandboxes(); |
| 102 | + |
| 103 | +// Remove |
| 104 | +await client.removeSandbox("my-project"); |
| 105 | +``` |
| 106 | + |
| 107 | +### Sandbox Sessions (Recommended) |
| 108 | + |
| 109 | +The `sandbox()` method returns a `SandboxSession` that implements `AsyncDisposable`. The sandbox is automatically removed when the scope exits: |
| 110 | + |
| 111 | +```typescript |
| 112 | +await using sb = await client.sandbox("my-project", { |
| 113 | + image: "python:3.12-alpine", |
| 114 | +}); |
| 115 | + |
| 116 | +await sb.run(["pip", "install", "numpy"]); |
| 117 | +const result = await sb.run(["python3", "-c", "import numpy; print(numpy.__version__)"]); |
| 118 | +console.log(result.output); |
| 119 | +// sandbox auto-removed when scope exits |
| 120 | +``` |
| 121 | + |
| 122 | +For environments without `await using` support: |
| 123 | + |
| 124 | +```typescript |
| 125 | +const sb = await client.sandbox("my-project"); |
| 126 | +try { |
| 127 | + const result = await sb.run(["echo", "hello"]); |
| 128 | + console.log(result.output); |
| 129 | +} finally { |
| 130 | + await sb[Symbol.asyncDispose](); |
| 131 | +} |
| 132 | +``` |
| 133 | + |
| 134 | +## Error Handling |
| 135 | + |
| 136 | +```typescript |
| 137 | +import { AgentKernelError } from "agentkernel"; |
| 138 | + |
| 139 | +try { |
| 140 | + await client.run(["bad-command"]); |
| 141 | +} catch (error) { |
| 142 | + if (error instanceof AgentKernelError) { |
| 143 | + console.log(error.status); // HTTP status code |
| 144 | + console.log(error.message); // Error message from server |
| 145 | + } |
| 146 | +} |
| 147 | +``` |
| 148 | + |
| 149 | +## API Reference |
| 150 | + |
| 151 | +| Method | Returns | Description | |
| 152 | +|--------|---------|-------------| |
| 153 | +| `health()` | `Promise<string>` | Health check | |
| 154 | +| `run(command, options?)` | `Promise<RunOutput>` | Run command in temporary sandbox | |
| 155 | +| `runStream(command, options?)` | `AsyncGenerator<StreamEvent>` | Run with streaming output | |
| 156 | +| `listSandboxes()` | `Promise<SandboxInfo[]>` | List all sandboxes | |
| 157 | +| `createSandbox(name, options?)` | `Promise<SandboxInfo>` | Create a sandbox | |
| 158 | +| `getSandbox(name)` | `Promise<SandboxInfo>` | Get sandbox info | |
| 159 | +| `removeSandbox(name)` | `Promise<void>` | Remove a sandbox | |
| 160 | +| `execInSandbox(name, command)` | `Promise<RunOutput>` | Execute in existing sandbox | |
| 161 | +| `sandbox(name, options?)` | `Promise<SandboxSession>` | Scoped session with auto-cleanup | |
0 commit comments