JavaScript SDK

The official Vibengine JavaScript/TypeScript SDK provides a convenient way to create and manage cloud sandboxes from your Node.js or edge runtime applications.

Installation

npm install vibengine

yarn add vibengine

pnpm add vibengine

Initialization

import { Sandbox } from "vibengine"

The SDK reads your API key from the VE_API_KEY environment variable by default. You can also pass it explicitly when creating a sandbox.

Sandbox Class

The Sandbox class is the primary interface for interacting with Vibengine cloud sandboxes.

`Sandbox.create(opts?)`

Creates a new sandbox instance and waits for it to be ready.

Parameters:

Parameter	Type	Default	Description
`template`	`string`	`"base"`	Template to use for the sandbox.
`timeoutMs`	`number`	`300000`	Sandbox timeout in milliseconds.
`envs`	`Record<string, string>`	`{}`	Environment variables for the sandbox.
`metadata`	`Record<string, string>`	`{}`	Custom metadata key-value pairs.
`apiKey`	`string`	`undefined`	API key override (uses env var if unset).

Returns: Promise<Sandbox>

import { Sandbox } from "vibengine"

// Basic creation
const sandbox = await Sandbox.create()

// With options
const sandbox = await Sandbox.create({
  template: "python-data",
  timeoutMs: 600_000,
  envs: { DATABASE_URL: "postgres://..." },
  metadata: { user: "jack", purpose: "analysis" },
})

`Sandbox.connect(sandboxId)`

Reconnects to an already running sandbox by its ID. This is useful when you need to resume interaction with a sandbox across different requests or processes.

Parameters:

Parameter	Type	Description
`sandboxId`	`string`	The unique sandbox identifier.

Returns: Promise<Sandbox>

import { Sandbox } from "vibengine"

const sandbox = await Sandbox.connect("sbx_a1b2c3d4e5")
const result = await sandbox.commands.run("echo 'reconnected!'")
console.log(result.stdout) // "reconnected!"

`sandbox.sandboxId`

The unique identifier for this sandbox instance. Use this to reconnect later with Sandbox.connect().

Type: string

const sandbox = await Sandbox.create()
console.log(sandbox.sandboxId) // "sbx_a1b2c3d4e5"

Commands

`sandbox.commands.run(cmd, opts?)`

Executes a shell command inside the sandbox and waits for it to complete.

Parameters:

Parameter	Type	Default	Description
`cmd`	`string`	—	The shell command to execute.
`opts.cwd`	`string`	`"/home"`	Working directory for the command.
`opts.envs`	`Record<string, string>`	`{}`	Additional environment variables.
`opts.timeoutMs`	`number`	`60000`	Command execution timeout in ms.

Returns: Promise<CommandResult>

interface CommandResult {
  stdout: string
  stderr: string
  exitCode: number
}

const result = await sandbox.commands.run("ls -la /home")
console.log(result.stdout)
console.log(result.exitCode) // 0

// With options
const result = await sandbox.commands.run("python main.py", {
  cwd: "/home/project",
  envs: { DEBUG: "true" },
  timeoutMs: 30_000,
})

Filesystem

`sandbox.files.read(path)`

Reads the contents of a file inside the sandbox.

Parameters:

Parameter	Type	Description
`path`	`string`	Absolute path to the file.

Returns: Promise<string>

const content = await sandbox.files.read("/home/project/config.json")
const config = JSON.parse(content)
console.log(config)

`sandbox.files.write(path, content)`

Writes content to a file inside the sandbox. Creates the file if it does not exist, or overwrites it if it does. Parent directories are created automatically.

Parameters:

Parameter	Type	Description
`path`	`string`	Absolute path to the file.
`content`	`string`	The content to write to the file.

Returns: Promise<void>

await sandbox.files.write("/home/project/main.py", `
import json

data = {"message": "Hello from Vibengine!"}
print(json.dumps(data))
`)

`sandbox.files.list(path)`

Lists the contents of a directory inside the sandbox.

Parameters:

Parameter	Type	Description
`path`	`string`	Absolute path to the directory.

Returns: Promise<FileInfo[]>

interface FileInfo {
  name: string
  type: "file" | "directory"
  size: number
}

const entries = await sandbox.files.list("/home/project")
for (const entry of entries) {
  console.log(`${entry.type}: ${entry.name} (${entry.size} bytes)`)
}

`sandbox.files.remove(path)`

Deletes a file or directory inside the sandbox.

Parameters:

Parameter	Type	Description
`path`	`string`	Absolute path to the file or directory.

Returns: Promise<void>

await sandbox.files.remove("/home/project/temp.txt")

Sandbox Lifecycle

`sandbox.kill()`

Immediately terminates the sandbox and releases all associated resources. After calling this method, the sandbox can no longer be used or reconnected to.

Returns: Promise<void>

const sandbox = await Sandbox.create()
// ... do work ...
await sandbox.kill()

`sandbox.setTimeout(timeoutMs)`

Extends or updates the timeout for the sandbox. The timeout is measured from the current moment, not from the original creation time.

Parameters:

Parameter	Type	Description
`timeoutMs`	`number`	New timeout value in milliseconds.

Returns: Promise<void>

const sandbox = await Sandbox.create({ timeoutMs: 60_000 })

// Extend to 10 more minutes from now
await sandbox.setTimeout(600_000)

`sandbox.getHostname(port?)`

Returns the hostname for accessing the sandbox. If a port is specified, returns a hostname that routes to that specific port inside the sandbox.

Parameters:

Parameter	Type	Default	Description
`port`	`number`	`undefined`	Optional port number to expose.

Returns: string

const hostname = sandbox.getHostname()
console.log(hostname) // "sbx_a1b2c3d4e5.vibengine.ai"

const webHostname = sandbox.getHostname(3000)
console.log(webHostname) // "sbx_a1b2c3d4e5-3000.vibengine.ai"

TypeScript Types

The SDK exports all types for use in your TypeScript projects:

import type {
  SandboxOpts,
  CommandResult,
  FileInfo,
} from "vibengine"

interface SandboxOpts {
  template?: string
  timeoutMs?: number
  envs?: Record<string, string>
  metadata?: Record<string, string>
  apiKey?: string
}

interface CommandResult {
  stdout: string
  stderr: string
  exitCode: number
}

interface FileInfo {
  name: string
  type: "file" | "directory"
  size: number
}

Full Example

import { Sandbox } from "vibengine"

async function main() {
  // Create a sandbox
  const sandbox = await Sandbox.create({
    template: "base",
    timeoutMs: 300_000,
  })

  console.log(`Sandbox created: ${sandbox.sandboxId}`)

  // Write a script
  await sandbox.files.write("/home/app.js", `
    const http = require("http")
    const server = http.createServer((req, res) => {
      res.end("Hello from Vibengine!")
    })
    server.listen(3000, () => console.log("Server running on port 3000"))
  `)

  // Run the script
  const result = await sandbox.commands.run("node /home/app.js &")
  console.log(result.stdout)

  // Get the public URL
  const url = sandbox.getHostname(3000)
  console.log(`App available at: https://${url}`)

  // List files in sandbox
  const files = await sandbox.files.list("/home")
  for (const f of files) {
    console.log(`  ${f.name} (${f.type})`)
  }

  // Clean up
  await sandbox.kill()
}

main()

For additional examples and guides, visit the Vibengine documentation.

JavaScript SDK

On this page