@pocketenv/sdk

Official JavaScript/TypeScript SDK for Pocketenv.

Installation

npm install @pocketenv/sdk
# or
bun add @pocketenv/sdk

Authentication

The SDK resolves your API token from the first available source:

1. Passed explicitly to Sandbox.configure({ token }) or Sandbox.create({ token })
2. POCKETENV_TOKEN environment variable
3. ~/.pocketenv/token.json — a JSON file with the shape { "token": "tok_..." }

This means Sandbox.configure() is optional if you have a token file or environment variable set.

Quick Start

import { Sandbox } from "@pocketenv/sdk";

// No configuration needed if ~/.pocketenv/token.json or POCKETENV_TOKEN is set
const sandbox = await Sandbox.create({ base: "openclaw" });

// Run a command
const result = await sandbox.sh`echo hello`;
console.log(result.stdout); // "hello\n"

// With interpolation
const dir = "/home/user";
const files = await sandbox.sh`ls -la ${dir}`;

// Stop and clean up
await sandbox.stop();
await sandbox.delete();

API

Sandbox.configure({ token?, baseUrl? })

Optionally set a global API token (and optional base URL) used by all subsequent calls. If omitted, the SDK falls back to POCKETENV_TOKEN or ~/.pocketenv/token.json.

Sandbox.create(options)

Create a new sandbox. Pass token inline to skip configure().

const sandbox = await Sandbox.create({
  base: "openclaw",
  name: "my-sandbox",
  token: "tok_...",
});

Sandbox.builder(base)

Fluent builder for creating sandboxes — useful when setting many options, especially multiple envs or secrets.

const sandbox = await Sandbox.builder("openclaw")
  .name("my-sandbox")
  .vcpus(4)
  .memory(8192)
  .env("NODE_ENV", "production")
  .env("PORT", "3000")
  .secret("API_KEY", process.env.API_KEY!)
  .keepAlive()
  .create();

Available builder methods: name, description, provider, topics, repo, vcpus, memory, disk, readme, env, secret, keepAlive, token, baseUrl.

Sandbox.get(id)

Fetch an existing sandbox by ID.

Sandbox.list({ limit?, offset? })

List all sandboxes.

Instance methods

Method	Description
sandbox.start({ repo?, keepAlive? })	Start the sandbox
sandbox.stop()	Stop the sandbox
sandbox.delete()	Delete the sandbox
sandbox.exec(command)	Run a raw command
sandbox.sh\command``	Run a shell command via /bin/sh -c (tagged template or string)
sandbox.expose(port, description?)	Expose a port publicly
sandbox.unexpose(port)	Remove a port exposure
sandbox.vscode()	Expose VS Code; returns the preview URL
sandbox.getSshKeys()	Get the sandbox SSH key pair
sandbox.putSshKey(publicKey, privateKey)	Set an SSH key pair (private key is encrypted automatically)
sandbox.createBackup(directory, description?, ttl?)	Create a backup of a sandbox directory
sandbox.listBackups()	List all backups for the sandbox
Sandbox.restoreBackup(backupId) (static)	Restore a sandbox from a backup

Sub-resources

• sandbox.file — write, list, get, update, delete
• sandbox.env — put, list, get, update, delete
• sandbox.secret — put, list, get, update, delete
• sandbox.volume — create, list, get, update, delete
• sandbox.ports — list
• sandbox.service — add, list, start, stop, restart, update, delete
• sandbox.tailscale — getAuthKey, setAuthKey
• sandbox.backup — create(directory, description?, ttl?), list(), restore(backupId)

Development

bun install
bun test        # run tests
bun run build   # compile to dist/

License

MIT