Process execution

Execute and manage processes in your sandboxes with Blaxel SDK. Run shell commands, retrieve process information, and control process execution.

​

Execute processes and commands

​

Execute command

Execute shell commands using the TypeScript SDK:

import { SandboxInstance } from "@blaxel/core";

const sandbox = await SandboxInstance.get("my-sandbox")

const process = await sandbox.process.exec({command: "echo 'Hello world'"})

if (process.status === "completed") {
  throw new Error("Process did complete without waiting");
}

​

Use process names

When starting a process (running a command), you can specify a process name. This lets you interact with the process—such as retrieving logs or process information—without needing to store the process ID on your end.

const process = await sandbox.process.exec({
  name: "test",
  command: "echo 'Hello world'",
})

You can use either the process name or the process ID to get information about the process:

await new Promise((resolve) => setTimeout(resolve, 10));

const completedProcess = await sandbox.process.get("test");

if (completedProcess.status !== "completed") {
  throw new Error("Process did not complete");

You can also use the process ID or name to retrieve logs of your processes.

​

Wait for process completion

You can wait for process completion when executing it:

const process = await sandbox.process.exec({
  name: "test",
  command: "echo 'Hello world'",
  waitForCompletion: true,
  timeout: 100
})

Notice the timeout parameter which allows to set a timeout duration on the process.

You can also wait for a process after it has started:

/// Wait for the process to finish (for max 120 seconds, checking every 1 second)
await sandbox.process.wait(”test”, { maxWait: 120000, interval: 1000 })

Set a long completion duration if your process is expected to take longer.

​

Wait for ports

In some cases, you may want to wait for a port to be opened while running — for example if you are running npm run dev and want to wait for port 3000 to be open.

const process = await sandbox.process.exec({
  name: "test",
  command: "echo 'Hello world'",
  waitForPorts: [3000]
})

​

Kill process

Kill a process immediately by running:

await sandbox.process.kill("test")

​

Process statuses

A process can have either of the following status:

• running
• completed
• failed
• killed
• stopped

​

Call a sandbox on a specific port

You can call your sandbox on a specific port by using a URL that follows this format. This is useful when you need to expose specific services or applications running in your sandbox:

https://run.blaxel.ai/{workspace_id}/sandboxes/{sandbox_id}/port/{port_number}