Create a Sandbox

Creating a sandbox provisions a new isolated cloud environment that is ready to use in milliseconds. You can customize the sandbox with templates, timeouts, environment variables, and metadata.

Prerequisites

Before creating a sandbox, make sure you have:

A Vibengine account and API key (VE_API_KEY)
The Vibengine SDK installed

npm install vibengine

pip install vibengine

Basic Sandbox Creation

The simplest way to create a sandbox uses the default template and settings.

import { Sandbox } from vibengine

const sandbox = await Sandbox.create()
console.log(Sandbox ID:, sandbox.sandboxId)

// Use the sandbox...

await sandbox.kill()

from vibengine import Sandbox

sandbox = Sandbox.create()
print("Sandbox ID:", sandbox.sandbox_id)

# Use the sandbox...

sandbox.kill()

Specifying a Template

Use a custom template to start with pre-installed tools and dependencies. Templates are built from Dockerfiles using the ve CLI.

import { Sandbox } from vibengine

const sandbox = await Sandbox.create(my-custom-template)

from vibengine import Sandbox

sandbox = Sandbox.create("my-custom-template")

If no template is specified, the default base template is used, which provides a minimal Ubuntu environment with common utilities.

Setting a Custom Timeout

The default sandbox timeout is 60 seconds. You can set a custom timeout (in seconds) up to a maximum of 24 hours (86400 seconds).

import { Sandbox } from vibengine

// Create a sandbox that stays alive for 10 minutes
const sandbox = await Sandbox.create({
  timeoutMs: 10 * 60 * 1000, // 10 minutes in milliseconds
})

from vibengine import Sandbox

# Create a sandbox that stays alive for 10 minutes
sandbox = Sandbox.create(timeout=10 * 60)  # 10 minutes in seconds

Passing Environment Variables

You can inject environment variables into the sandbox at creation time. These are available to all commands and processes.

import { Sandbox } from vibengine

const sandbox = await Sandbox.create({
  envs: {
    DATABASE_URL: postgresql://localhost:5432/mydb,
    API_TOKEN: sk-abc123,
    NODE_ENV: production,
  },
})

const result = await sandbox.commands.run(echo )
console.log(result.stdout) // postgresql://localhost:5432/mydb

from vibengine import Sandbox

sandbox = Sandbox.create(envs={
    "DATABASE_URL": "postgresql://localhost:5432/mydb",
    "API_TOKEN": "sk-abc123",
    "NODE_ENV": "production",
})

result = sandbox.commands.run("echo $DATABASE_URL")
print(result.stdout)  # postgresql://localhost:5432/mydb

Adding Metadata

Attach custom metadata to sandboxes for tracking and organization. Metadata is a dictionary of string key-value pairs.

import { Sandbox } from vibengine

const sandbox = await Sandbox.create({
  metadata: {
    userId: user_123,
    purpose: code-execution,
    environment: staging,
  },
})

from vibengine import Sandbox

sandbox = Sandbox.create(metadata={
    "user_id": "user_123",
    "purpose": "code-execution",
    "environment": "staging",
})

Full Configuration Example

Combine all options for complete control over sandbox creation.

import { Sandbox } from vibengine

const sandbox = await Sandbox.create({
  template: my-custom-template,
  timeoutMs: 5 * 60 * 1000,
  envs: {
    NODE_ENV: production,
    API_KEY: my-secret-key,
  },
  metadata: {
    userId: user_456,
    sessionId: sess_789,
  },
})

console.log(Sandbox ID:, sandbox.sandboxId)
console.log(Sandbox is ready!)

// Remember to clean up when done
await sandbox.kill()

from vibengine import Sandbox

sandbox = Sandbox.create(
    template="my-custom-template",
    timeout=5 * 60,
    envs={
        "NODE_ENV": "production",
        "API_KEY": "my-secret-key",
    },
    metadata={
        "user_id": "user_456",
        "session_id": "sess_789",
    },
)

print("Sandbox ID:", sandbox.sandbox_id)
print("Sandbox is ready!")

# Remember to clean up when done
sandbox.kill()

Always call kill() when you are done with a sandbox to free resources immediately. Otherwise the sandbox will remain running until the timeout expires.

Next Steps

Connect to a Sandbox — reconnect to running sandboxes
Execute Commands — run shell commands
Manage Files — work with the sandbox filesystem

Create a Sandbox

On this page