tos-sandbox

TypeScript/JavaScript SDK for TOS Sandbox — create and manage isolated container environments for AI agents, code execution, and development.

Install

npm install tos-sandbox

Quick Start

import { SandboxClient } from 'tos-sandbox'

const client = new SandboxClient({
  token: 'tos_...', // TOS Service Token
})

// Create a sandbox
const sbx = await client.create({
  image: 'node:22-bookworm',
  resource: { cpu: '1', memory: '1Gi' },
  timeoutSeconds: 21600, // 6h
})

// Run commands
const result = await client.exec(sbx.id, 'echo "Hello from sandbox"')
console.log(result.stdout)

// Read and write files
await client.writeFiles(sbx.id, [
  { path: '/workspace/index.js', content: 'console.log("hi")' },
])
const content = await client.readFile(sbx.id, '/workspace/index.js')

// Get preview URL (for dev servers)
const previewUrl = client.getPreviewUrl(sbx.id, 3000)
// → https://{id}-3000.sandbox.tos.smartx.com/

// Clean up
await client.delete(sbx.id)

API

new SandboxClient(options)

| Option | Type | Default | Description | |--------|------|---------|-------------| | token | string | required | TOS Service Token | | baseUrl | string | https://sandbox.tos.smartx.com | Sandbox service URL |

Methods

| Method | Description | |--------|-------------| | create(opts) | Create a sandbox | | list(filter?) | List sandboxes | | get(id) | Get sandbox info | | delete(id) | Delete a sandbox | | renew(id, timeoutSeconds) | Extend sandbox expiration | | exec(id, command, opts?) | Execute a command | | readFile(id, path) | Read a file | | writeFiles(id, files) | Write files | | getEndpointUrl(id, port) | Get internal endpoint URL | | getPreviewUrl(id, port) | Get public preview URL |

Preview URLs

After starting a dev server inside a sandbox, use getPreviewUrl() to get a publicly accessible URL:

https://{sandboxId}-{port}.sandbox.tos.smartx.com/

Preview URLs are public — the sandbox ID (UUID) serves as the access token.

License

MIT