What is this package?

@yepcode/sandbox is a small Node.js client for YepCode sandboxes: isolated VMs you create and control over the YepCode API. It covers:

• Lifecycle via @yepcode/run’s YepCodeApi — create a sandbox, update its timeout, kill it.
• In-VM work on a running instance — runCommand, uploadFile, mkDir, and downloadFile.

Installation

npm install @yepcode/sandbox

Requirements

• Node.js >= 18
• TypeScript types ship with the package (and align with @yepcode/run where shared types are defined)

API credentials

1. Sign up at YepCode Cloud

2. Create an API token under Settings → API credentials

3. Prefer an environment variable:

   # .env
   YEPCODE_API_TOKEN=your_token_here

   You can also pass apiToken (or client credentials) in the constructor; avoid hard-coding tokens in production.

Quick start

const { YepCodeSandbox } = require("@yepcode/sandbox");

const sandboxes = new YepCodeSandbox({ apiToken: process.env.YEPCODE_API_TOKEN });

const instance = await sandboxes.create({
  imageId: "your-image-id",
  name: "my-sandbox",
  timeout: 300_000,
  publicHttpPorts: [8080],
  // `user:secret` — `secret` plain or hashed (bcrypt $2y$/$2a$, Apache MD5 $apr1$, SHA-1)
  publicHttpPortsBasicAuth: "user:password",
  metadata: { purpose: "demo" },
});

// By sandbox id on the client
// await sandboxes.update(instance.data.id, { timeout: 120_000 });
// await sandboxes.kill(instance.data.id);

// On the instance
await instance.update({ timeout: 120_000 });

await instance.mkDir("/tmp/work");
await instance.uploadFile("/tmp/work/hello.txt", Buffer.from("hello"));
const bytes = await instance.downloadFile("/tmp/work/hello.txt");

const run = await instance.runCommand({
  command: "pwd",
  args: [],
  workingDirectory: "/",
  env: { MY_VAR: "value" },
});
console.log(run.stdout.toString(), run.exitCode);

await instance.kill();

Behaviour notes

• runCommand, uploadFile, mkDir, and downloadFile wait until the instance reports ready (poll every 250 ms, up to 10 s), then reuse that readiness for later calls on the same instance.
• instance.data is the current sandbox metadata from the platform (id, imageId, connection fields, etc.); see SandboxInstance below.

API reference

YepCodeSandbox

Wrapper around YepCodeApi from @yepcode/run for sandbox lifecycle calls. create() returns a SandboxInstance tied to the same API client.

Constructor

constructor(config?: YepCodeApiConfig)

Same options as YepCodeApi in @yepcode/run (apiToken, apiHost, teamId, clientId / clientSecret, etc.).

Methods

| Method | Returns | Description | |--------|---------|-------------| | create(data: CreateSandboxInput) | Promise<SandboxInstance> | Create a sandbox and return a connected instance | | update(id: string, data: UpdateSandboxInput) | Promise | Update sandbox data by id; resolves to the updated sandbox record from the platform | | kill(id: string) | Promise | Kill sandbox by id; resolves to the updated sandbox record from the platform |

CreateSandboxInput, UpdateSandboxInput, and YepCodeApiConfig are the same types as in @yepcode/run.

SandboxInstance

One running sandbox: commands and in-VM file operations on the instance; update and kill use the linked YepCodeApi.

Prefer creating instances with YepCodeSandbox.create() so the API client is wired correctly.

data (getter)

The shape matches the sandbox model in @yepcode/run and the live API (identifiers, image, ports, metadata, timeout, connection details, and so on).

Methods

| Method | Returns | Description | |--------|---------|-------------| | update(input: UpdateSandboxInput) | Promise<SandboxInstance> | Extend timeout; refreshes data | | kill() | Promise<SandboxInstance> | Stop sandbox; refreshes data | | runCommand(input: RunCommandInput) | Promise<RunCommandResult> | Run a command (streaming stdout/stderr); waits for readiness first | | uploadFile(path: string, content: Buffer \| Uint8Array) | Promise<SandboxStorageUploadResult> | Upload bytes to a path in the sandbox | | mkDir(path: string) | Promise<SandboxStorageMkDirResult> | Create a directory | | downloadFile(path: string) | Promise<Buffer> | Read a file from the sandbox |

Types (this package)

interface RunCommandInput {
  command: string;
  args?: string[];
  workingDirectory?: string;
  env?: Record<string, string>;
  background?: boolean;
  timeoutSeconds?: number;
}

interface RunCommandResult {
  pid?: number;
  startedAt?: number;
  stdout: Buffer;
  stderr: Buffer;
  exitCode?: number;
  exited?: boolean;
  status?: number;
  error?: string;
  endStartedAt?: number;
  finishedAt?: number;
}

interface SandboxStorageUploadResult {
  success: boolean;
  absolutePath?: string;
  bytesWritten?: number;
  errorMessage?: string;
}

interface SandboxStorageMkDirResult {
  success: boolean;
  absolutePath?: string;
  errorMessage?: string;
}

Development

npm install
npm run build    # TypeScript → dist/
npm run test:ci  # Jest
npm run lint

License

This project is licensed under the MIT License — see the LICENSE file for details.