Running Commands

Overview

You can execute terminal commands inside a running sandbox to install packages, run scripts, compile code, or perform any operation you would do in a regular shell. Commands return stdout, stderr, and an exit code.

Running a Command

const result = await sandbox.commands.run("echo 'Hello, Lelantos!'");

console.log("stdout:", result.stdout);
console.log("stderr:", result.stderr);
console.log("exit code:", result.exitCode);

curl -X POST "https://SANDBOX_ID.lelantos.ai/rpc" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "exec",
    "params": {
      "cmd": "echo Hello, Lelantos!"
    }
  }'

Command Output

Every command execution returns three fields:

Field	Type	Description
`stdout`	`string`	Standard output from the command.
`stderr`	`string`	Standard error output from the command.
`exitCode`	`number`	Exit code (0 = success, non-zero = failure).

Examples

Installing packages

// Python packages
await sandbox.commands.run("pip install numpy pandas matplotlib");

// Node.js packages
await sandbox.commands.run("npm install express");

// System packages
await sandbox.commands.run("apt-get update && apt-get install -y jq");

Running scripts

// Run a Python script
await sandbox.uploadFile("/home/user/script.py", `
import json
data = {"status": "ok", "count": 42}
print(json.dumps(data))
`);

const result = await sandbox.commands.run("python /home/user/script.py");
const output = JSON.parse(result.stdout);
console.log(output.count); // 42

Chaining commands

const result = await sandbox.commands.run(
  "cd /home/user && git clone https://github.com/example/repo.git && cd repo && npm install && npm test"
);

if (result.exitCode !== 0) {
  console.error("Tests failed:", result.stderr);
}

Background Commands

For long-running processes (servers, watchers), run commands in the background:

// Start a server in the background
await sandbox.commands.run("nohup python -m http.server 8080 &");

// The command returns immediately
// Access the server at https://8080-{sandboxID}.lelantos.ai

Streaming Not Yet Available

Command output is currently returned after the command completes. Real-time streaming of stdout/stderr is not yet available but is planned for a future release.

Working Directory

Commands run in the default working directory of the sandbox (typically /home/user). Use cd within your command to change directories:

await sandbox.commands.run("cd /tmp && pwd");
// stdout: /tmp

On this page