Syva Docs

Documentation

Run commands in a sandbox

Foreground exec for bounded work. Detached processes for servers and long jobs.

Foreground commands

runCommand waits for completion and returns exit code, stdout, stderr, duration, and timeout state.

TypeScript
const result = await sandbox.runCommand("python", ["--version"]);

console.log(result.exitCode);
console.log(result.stdout);
console.log(result.stderr);

Background commands

process.start returns a command id immediately. Store it if another request needs to reconnect to the same process.

TypeScript
const command = await sandbox.process.start("sleep 60");

const current = await command.refresh();
const stdout = await command.readStdout();
await command.kill();

Stream output

Streams emit stdout, stderr, and final status events. Fetch the output snapshot afterward for complete stdout and stderr strings.

TypeScript
const command = await sandbox.process.start("npm test", {
  cwd: "/workspace",
});

for await (const event of command.logs()) {
  if (event.event === "stdout" || event.event === "stderr") {
    process.stdout.write(String(event.data.data));
  }
}

const output = await command.output();
console.log(output.state, output.exitCode);

Expose a port

Declare ports at create time. After the server starts, call domain(port).

TypeScript
const sandbox = await Sandbox.create({
  image: "node-22:base",
  ports: [{ containerPort: 3000, protocol: "http" }],
});

try {
  const result = await sandbox.runCommand("node", ["--version"]);
  console.log(result.exitCode);
  console.log(result.stdout);

  await sandbox.fs.writeFile("/workspace/server.mjs", `
import http from "node:http";

http.createServer((request, response) => {
  response.end("hello from Syva");
}).listen(3000, "0.0.0.0");
`);

  const server = await sandbox.process.start("node /workspace/server.mjs");

  console.log(sandbox.domain(3000));

  const current = await server.refresh();
  console.log(current.state);

  await server.stop();
} finally {
  await sandbox.stop();
}