Koyeb Sandbox SDK for JavaScript/TypeScript

Overview

The Koyeb Sandbox SDK enables you to manage and interact with ephemeral sandboxes on Koyeb, a modern cloud infrastructure provider. Sandboxes are secure, isolated environments designed to execute untrusted or user-supplied code safely.

This SDK is ideal for building online code runners, education platforms, CI/CD systems, and any application that requires secure, on-demand code execution.

• ⚡ Ephemeral environments: Create, manage, and destroy sandboxes programmatically
• 🔒 Secure execution: Run untrusted code with strong isolation
• 📁 Filesystem management: Upload / download files, create directories and more
• ⚙️ Background processes: Start and manage background processes
• 🟦 TypeScript support: Fully typed for a great developer experience

Installation

npm install @koyeb/api-client-js @koyeb/sandbox-sdk

Set your API access token before using the SDK:

export KOYEB_API_TOKEN="<your-api-token>"

Quick Start

import { Sandbox } from '@koyeb/sandbox-sdk';

async function main() {
  const sandbox = await Sandbox.create();

  const { stdout } = await sandbox.exec("echo 'Hello from Koyeb Sandbox!'");
  console.log(stdout.trim());

  await sandbox.delete();
}

main().catch(console.error);

See more examples.

Creating Sandboxes

Sandbox.create(options?)

Creates a new sandbox.

Options

| Option | Description | | ---------------------------------- | ------------------------------------------------------------------------ | | image | Docker image to boot. Defaults to koyeb/sandbox. | | name | Name shown in Koyeb and used in resource names. | | wait_ready | Wait until the sandbox becomes healthy (enabled by default) | | instance_type | Instance size to provision. Defaults to micro. | | exposed_port_protocol | Protocol used by the exposed port (one of http \| http2). | | env | Environment variables injected into the container. | | region | Koyeb region slug. Defaults to 'na' (north america). | | api_token | API token for authentication, overriding process.env.KOYEB_API_TOKEN. | | timeout | Seconds to wait while checking readiness. | | idle_timeout | Seconds before the sandbox scales to zero. Set 0 to disable sleep. | | enable_tcp_proxy | Enable TCP proxying on port 3031. | | privileged | Run the sandbox in privileged mode. | | registry_secret | Name of the Koyeb registry secret required to pull private images. | | delete_after_delay | Time to wait before automatically deleting the sandbox after creation. | | delete_after_inactivity_delay | Time to wait before automatically deleting the sandbox after inactivity. | | _experimental_enable_light_sleep | When enabled, uses idle_timeout for light_sleep and sets deep_sleep=3900. |

Sandbox.get_from_id(serviceId, apiToken?)

Load an existing Sandbox from a Koyeb service ID. Useful for long-lived integrations.

Sandbox Lifecycle & Metadata

| Method | Description | | -------------------------------------------------------- | -------------------------------------------------------------------------------- | | wait_ready(timeout?, pollInterval?, signal?) | Polls health until success or timeout. Resolves to true on success. | | wait_tcp_proxy_ready(timeout?, pollInterval?, signal?) | Polls until TCP proxy information becomes available. | | is_healthy() | Performs a /health check against the sandbox URL. | | get_sandbox_url() | Returns the HTTPS URL (https://<domain>/koyeb-sandbox). | | get_tcp_proxy_info() | Returns [host, publicPort] once the TCP proxy is ready, otherwise undefined. | | get_domain() | Fetches and caches the sandbox domain metadata. | | update_lifecycle() | Change the auto deletion properties. | | delete() | Tears down the underlying service. |

Command Execution

| Method | Description | | ---------------------------- | ------------------------------------------------------------------------------------------------------ | | exec(cmd, options?) | Runs a command and resolves with { stdout, stderr, code }. Supports cwd, env, and AbortSignal. | | exec_stream(cmd, options?) | Streams command output using Server-Sent Events. Emits stdout, stderr, and end. |

Streaming Example

const stream = sandbox.exec_stream('npm test');

stream.addEventListener('stdout', ({ data }) => {
  process.stdout.write(`${data.data}\n`);
});

stream.addEventListener('stderr', ({ data }) => {
  process.stderr.write(`${data.data}\n`);
});

stream.addEventListener('exit', ({ data }) => {
  process.stderr.write(`Exit code: ${data.code}\n`);
});

stream.addEventListener('end', () => {
  console.log('Command finished');
});

Port Exposure

| Method | Description | | ---------------------- | --------------------------------------------------------------------------------- | | expose_port(port) | Binds a sandbox port to the public domain. Resolves { port, exposed_at }. | | unexpose_port(port?) | Unbinds the exposed port. Pass a specific port or omit to unbind the current one. |

Process Management

| Method | Description | | ------------------------------- | ---------------------------------------------------------- | | launch_process(cmd, options?) | Starts a long-lived background process and returns its ID. | | kill_process(processId) | Stops a process started with launch_process. | | list_processes() | Lists processes with their status. | | kill_all_processes() | Stops every running sandbox process and returns the count. |

Filesystem Helpers

Access via sandbox.filesystem. Operations run over the sandbox API and fall back to exec only when needed.

| Method | Description | | -------------------------------------- | ----------------------------------------------------- | | mkdir(path, recursive?) | Create a directory. | | list_dir(path?) | List entries inside a directory. Defaults to .. | | delete_dir(path) | Delete a directory tree. | | write_file(path, content) | Create or replace a text file. | | write_files(files) | Bulk write helper for multiple files. | | read_file(path) | Fetch { content, encoding } for a remote file. | | rename_file(oldPath, newPath) | Rename using an internal mv command. | | rm(path, recursive?) | Remove a file or directory (rm -rf when recursive). | | exists(path) | Return true if the path exists. | | is_file(path) | Return true if the path is a regular file. | | is_dir(path) | Return true if the path is a directory. | | upload_file(localPath, remotePath) | Read a local file and upload it. | | download_file(localPath, remotePath) | Download a sandbox file to disk. |

Error Types

The SDK exports the following error classes for granular handling:

• MissingApiTokenError
• InvalidPortError
• SandboxTimeoutError
• NoSandboxSecretError
• SandboxRequestError

Contributing

Install dependencies with pnpm install and run pnpm build to compile TypeScript into lib/.

Need help? Reach out on community.koyeb.com.

License

This project is licensed under the Apache-2.0 License. See LICENSE for details.