Commands

The commands API lets you execute shell commands inside a sandbox. You can run simple one-off commands, stream output in real time, run background processes, and control the execution environment.

Running a Command

Use commands.run() to execute a command and wait for it to complete.

import { Sandbox } from 'vibengine'

const sandbox = await Sandbox.create()

const result = await sandbox.commands.run('echo "Hello from Vibengine!"')
console.log(result.stdout) // "Hello from Vibengine!\n"
console.log(result.exitCode) // 0

from vibengine import Sandbox

sandbox = Sandbox.create()

result = sandbox.commands.run('echo "Hello from Vibengine!"')
print(result.stdout)  # "Hello from Vibengine!\n"
print(result.exit_code)  # 0

Handling stdout and stderr

Commands capture both standard output and standard error separately.

import { Sandbox } from 'vibengine'

const sandbox = await Sandbox.create()

// stdout
const result = await sandbox.commands.run('echo "output" && echo "error" >&2')
console.log('stdout:', result.stdout) // "output\n"
console.log('stderr:', result.stderr) // "error\n"

from vibengine import Sandbox

sandbox = Sandbox.create()

# stdout and stderr
result = sandbox.commands.run('echo "output" && echo "error" >&2')
print("stdout:", result.stdout)  # "output\n"
print("stderr:", result.stderr)  # "error\n"

Checking Exit Codes

The exit code tells you whether the command succeeded (0) or failed (non-zero).

import { Sandbox } from 'vibengine'

const sandbox = await Sandbox.create()

const result = await sandbox.commands.run('ls /nonexistent')
if (result.exitCode !== 0) {
  console.log('Command failed:', result.stderr)
}

from vibengine import Sandbox

sandbox = Sandbox.create()

result = sandbox.commands.run("ls /nonexistent")
if result.exit_code != 0:
    print("Command failed:", result.stderr)

Streaming Output

For long-running commands, you can stream stdout and stderr in real time instead of waiting for the command to finish.

import { Sandbox } from 'vibengine'

const sandbox = await Sandbox.create()

const result = await sandbox.commands.run('for i in 1 2 3 4 5; do echo "Step $i"; sleep 1; done', {
  onStdout: (data) => {
    console.log('[stdout]', data)
  },
  onStderr: (data) => {
    console.log('[stderr]', data)
  },
})

from vibengine import Sandbox

sandbox = Sandbox.create()

result = sandbox.commands.run(
    "for i in 1 2 3 4 5; do echo Step $i; sleep 1; done",
    on_stdout=lambda data: print("[stdout]", data),
    on_stderr=lambda data: print("[stderr]", data),
)

Setting the Working Directory

Specify the directory where the command should execute.

import { Sandbox } from 'vibengine'

const sandbox = await Sandbox.create()

// Create a directory and run a command inside it
await sandbox.commands.run('mkdir -p /home/user/project')
await sandbox.files.write('/home/user/project/app.js', 'console.log("hello")')

const result = await sandbox.commands.run('node app.js', {
  cwd: '/home/user/project',
})
console.log(result.stdout) // "hello\n"

from vibengine import Sandbox

sandbox = Sandbox.create()

# Create a directory and run a command inside it
sandbox.commands.run("mkdir -p /home/user/project")
sandbox.files.write("/home/user/project/app.py", 'print("hello")')

result = sandbox.commands.run("python app.py", cwd="/home/user/project")
print(result.stdout)  # "hello\n"

Environment Variables per Command

Override or add environment variables for a specific command without affecting the sandbox globally.

import { Sandbox } from 'vibengine'

const sandbox = await Sandbox.create()

const result = await sandbox.commands.run('echo "Mode: $APP_MODE"', {
  envs: {
    APP_MODE: 'testing',
    DEBUG: 'true',
  },
})
console.log(result.stdout) // "Mode: testing\n"

from vibengine import Sandbox

sandbox = Sandbox.create()

result = sandbox.commands.run(
    'echo "Mode: $APP_MODE"',
    envs={
        "APP_MODE": "testing",
        "DEBUG": "true",
    },
)
print(result.stdout)  # "Mode: testing\n"

Background Processes

Start a process that runs in the background, such as a web server.

import { Sandbox } from 'vibengine'

const sandbox = await Sandbox.create()

// Start a background process
const proc = await sandbox.commands.run('python3 -m http.server 8080', {
  background: true,
})

// The command returns immediately
console.log('Server started in background')

// Later, you can kill it
await proc.kill()

from vibengine import Sandbox

sandbox = Sandbox.create()

# Start a background process
proc = sandbox.commands.run("python3 -m http.server 8080", background=True)

# The command returns immediately
print("Server started in background")

# Later, you can kill it
proc.kill()

Setting a Command Timeout

You can set a timeout for individual commands to prevent them from running indefinitely.

import { Sandbox } from 'vibengine'

const sandbox = await Sandbox.create()

try {
  // This will timeout after 5 seconds
  await sandbox.commands.run('sleep 30', {
    timeoutMs: 5000,
  })
} catch (error) {
  console.log('Command timed out')
}

from vibengine import Sandbox

sandbox = Sandbox.create()

try:
    # This will timeout after 5 seconds
    sandbox.commands.run("sleep 30", timeout=5)
except TimeoutError:
    print("Command timed out")

Command timeout is separate from the sandbox timeout. A command can time out while the sandbox continues running.

Chaining Commands

You can chain multiple shell commands using standard shell operators.

import { Sandbox } from 'vibengine'

const sandbox = await Sandbox.create()

// Chain with && (stop on failure)
await sandbox.commands.run('apt-get update && apt-get install -y curl')

// Chain with ; (continue regardless)
await sandbox.commands.run('echo "step 1"; echo "step 2"; echo "step 3"')

// Use pipes
const result = await sandbox.commands.run('ls /usr/bin | grep python | head -5')
console.log(result.stdout)

from vibengine import Sandbox

sandbox = Sandbox.create()

# Chain with && (stop on failure)
sandbox.commands.run("apt-get update && apt-get install -y curl")

# Chain with ; (continue regardless)
sandbox.commands.run('echo "step 1"; echo "step 2"; echo "step 3"')

# Use pipes
result = sandbox.commands.run("ls /usr/bin | grep python | head -5")
print(result.stdout)

Long-running commands should either use a timeout or run as background processes to avoid blocking your application.

Next Steps

Filesystem — read and write files used by commands
Environment Variables — manage sandbox-wide environment
Internet Access — commands can access the internet

Commands

On this page