Connect to a Sandbox

Every running sandbox has a unique ID. You can use this ID to reconnect to a sandbox from a different client, process, or server. This is useful for long-running tasks, handing off sandboxes between services, or resuming work after a disconnection.

Getting the Sandbox ID

When you create a sandbox, you can retrieve its ID from the sandbox object.

import { Sandbox } from vibengine

const sandbox = await Sandbox.create()
const sandboxId = sandbox.sandboxId
console.log(Save this ID:, sandboxId)
// Example output: "sb_a1b2c3d4"

from vibengine import Sandbox

sandbox = Sandbox.create()
sandbox_id = sandbox.sandbox_id
print("Save this ID:", sandbox_id)
# Example output: "sb_a1b2c3d4"

Reconnecting to a Running Sandbox

Use Sandbox.connect() with the sandbox ID to reconnect. The sandbox must still be running (i.e., it has not timed out or been killed).

import { Sandbox } from vibengine

// Later, from a different process or server...
const sandbox = await Sandbox.connect(sb_a1b2c3d4)

// Continue using the sandbox as normal
const result = await sandbox.commands.run(echo reconnected!)
console.log(result.stdout) // "reconnected!"

from vibengine import Sandbox

# Later, from a different process or server...
sandbox = Sandbox.connect("sb_a1b2c3d4")

# Continue using the sandbox as normal
result = sandbox.commands.run(echo reconnected!)
print(result.stdout)  # "reconnected!"

Connecting to a sandbox does not reset its timeout. The sandbox continues running with its original timeout countdown. Use keepAlive to extend it if needed.

Listing Running Sandboxes

You can list all running sandboxes associated with your API key. This is helpful for finding sandbox IDs or monitoring active instances.

import { Sandbox } from vibengine

const runningSandboxes = await Sandbox.list()

for (const info of runningSandboxes) {
  console.log(`ID: ${info.sandboxId}`)
  console.log(`  Template: ${info.templateId}`)
  console.log(`  Started: ${info.startedAt}`)
  console.log(`  Metadata: ${JSON.stringify(info.metadata)}`)
}

from vibengine import Sandbox

running_sandboxes = Sandbox.list()

for info in running_sandboxes:
    print(f"ID: {info.sandbox_id}")
    print(f"  Template: {info.template_id}")
    print(f"  Started: {info.started_at}")
    print(f"  Metadata: {info.metadata}")

Filtering Sandboxes by Metadata

If you attached metadata when creating sandboxes, you can filter the list to find specific ones.

import { Sandbox } from vibengine

const allSandboxes = await Sandbox.list()

// Filter sandboxes by metadata
const userSandboxes = allSandboxes.filter(
  (s) => s.metadata?.userId === user_123
)

console.log(`User has ${userSandboxes.length} active sandboxes`)

// Connect to the first matching sandbox
if (userSandboxes.length > 0) {
  const sandbox = await Sandbox.connect(userSandboxes[0].sandboxId)
  // Use the sandbox...
}

from vibengine import Sandbox

all_sandboxes = Sandbox.list()

# Filter sandboxes by metadata
user_sandboxes = [
    s for s in all_sandboxes
    if s.metadata.get("user_id") == "user_123"
]

print(f"User has {len(user_sandboxes)} active sandboxes")

# Connect to the first matching sandbox
if user_sandboxes:
    sandbox = Sandbox.connect(user_sandboxes[0].sandbox_id)
    # Use the sandbox...

Typical Reconnection Pattern

A common pattern is to create a sandbox, store its ID (e.g., in a database), and reconnect to it later from a different request or service.

import { Sandbox } from vibengine

// --- Request 1: Create and store ---
async function startSession(userId) {
  const sandbox = await Sandbox.create({
    timeoutMs: 15 * 60 * 1000, // 15 minutes
    metadata: { userId },
  })
  // Store sandboxId in your database
  await db.sessions.create({
    userId,
    sandboxId: sandbox.sandboxId,
  })
  return sandbox.sandboxId
}

// --- Request 2: Reconnect and use ---
async function runCode(userId, code) {
  const session = await db.sessions.findByUserId(userId)
  const sandbox = await Sandbox.connect(session.sandboxId)

  const result = await sandbox.commands.run(code)
  return result.stdout
}

from vibengine import Sandbox

# --- Request 1: Create and store ---
def start_session(user_id: str) -> str:
    sandbox = Sandbox.create(
        timeout=15 * 60,  # 15 minutes
        metadata={"user_id": user_id},
    )
    # Store sandbox_id in your database
    db.sessions.create(
        user_id=user_id,
        sandbox_id=sandbox.sandbox_id,
    )
    return sandbox.sandbox_id

# --- Request 2: Reconnect and use ---
def run_code(user_id: str, code: str) -> str:
    session = db.sessions.find_by_user_id(user_id)
    sandbox = Sandbox.connect(session.sandbox_id)

    result = sandbox.commands.run(code)
    return result.stdout

If you try to connect to a sandbox that has already timed out or been killed, the SDK will raise an error. Always handle this case in production code.

Next Steps

Sandbox Lifecycle — understand timeout and cleanup behavior
Persistence — pause and resume sandboxes for long-term state
Execute Commands — run shell commands in your sandbox

Connect to a Sandbox

Connect to a Sandbox

Getting the Sandbox ID

Reconnecting to a Running Sandbox

Listing Running Sandboxes

Filtering Sandboxes by Metadata

Typical Reconnection Pattern

Next Steps

On this page