Skip to main content
Execute and manage processes in your sandboxes with Blaxel SDK. Run shell commands, retrieve process information, and control process execution.
Complete code examples demonstrating all operations are available on Blaxel’s GitHub: in TypeScript, in Python, and in Go.

​
Execute processes and commands

The Blaxel SDK authenticates with your workspace using credentials from these sources, in priority order:
  1. when running on Blaxel, authentication is handled automatically
  2. variables in your .env file (BL_WORKSPACE and BL_API_KEY, or see this page for other authentication options).
  3. environment variables from your machine
  4. configuration file created locally when you log in through Blaxel CLI (or deploy on Blaxel)
When developing locally, the recommended method is to just log in to your workspace with Blaxel CLI. This allows you to run Blaxel SDK functions that will automatically connect to your workspace without additional setup. When you deploy on Blaxel, this connection persists automatically.When running Blaxel SDK from a remote server that is not Blaxel-hosted, we recommend using environment variables as described in the third option above.

​
Execute command

Execute shell commands: 
import { SandboxInstance } from "@blaxel/core";

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

// Execute command
const process = await sandbox.process.exec({
  command: "echo 'Hello, World!'"
});
Logs for a process are available in the process execution object if the process is started with the waitForCompletion: true / "wait_for_completion": True parameter. Process execution logs are also visible in the Blaxel Console. Refer to the Logs section of the sandbox detail page, as shown below: process logs

​
Set the working directory

Set the working directory for subsequent commands: 
import { SandboxInstance } from "@blaxel/core";

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

// Execute command
const process = await sandbox.process.exec({
  workingDir: "/app",
  command: "ls -al"
});

​
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: "hello-process",
  command: "echo 'Hello, World!'"
});
const processInfo = await sandbox.process.get("hello-process");
You can use either the process name or the process ID to get information about the process: 
const completedProcess = await sandbox.process.get("hello-process");
if (completedProcess.status === "completed") {
  // ...
}
The exit code of the process is available in the exitCode parameter of the process execution object returned by the process.exec and process.get methods. You can also use the process ID or name to retrieve logs of your processes.

​
Kill process

Kill a process immediately by running: 
await sandbox.process.kill("test")

​
Long-running processes

​
Wait for process completion

You can wait for process completion when executing it: 
const process = await sandbox.process.exec({
  name: "build-process",
  command: "npm run build",
  waitForCompletion: true,
  timeout: 60000 // 60 seconds
});
When waiting for completion, the process execution object will contain a .logs object which surfaces both stdout and stderr. Also, notice the timeout parameter which allows to set a timeout duration on the process.
When using waitForCompletion, Blaxel enforces a timeout limit of 60 seconds. Don’t set your timeout longer than this. For longer waiting periods, use the process-watching option described below.
You can also wait for a process after it has started: 
await sandbox.process.exec({
  name: "long-task",
  command: "sleep 10"
});

// Wait for completion (max 10 minutes, check every 5 seconds)
await sandbox.process.wait("long-task", {
  maxWait: 600000,
  interval: 5000
});
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: "dev-server",
  command: "npm run dev -- --port 3000 &",
  waitForPorts: [3000]
});

​
Auto-restart

​
Restart process on failure

You can restart a process if it fails, up to a maximum number of restart attempts: 
const process = await sandbox.process.exec({
  name: "start-server",
  command: "npm run dev -- --host 0.0.0.0 --port 8000",
  restartOnFailure: true,
  maxRestarts: 5
});

​
Sandbox keep-alive

This is an alpha feature that may change or be removed in future. It can only be used with specified versions of the sandbox API and the Blaxel TypeScript SDK.
By default, sandboxes automatically switch to standby after a few seconds of inactivity to save resources. However, it is possible to adjust this behaviour and keep the sandbox running when you launch a process, even if there isn’t an active connection to it. This is typically used to keep a server running in the sandbox environment even when it is not serving requests. To use this feature, you must first:
  • build or rebuild your custom sandbox image with a specific version of the sandbox API that supports the keep-alive feature: 
    # Required sandbox-api version with keepAlive support
COPY --from=ghcr.io/blaxel-ai/sandbox:develop-6a4e7c3 /sandbox-api /usr/local/bin/sandbox-api
  • use a specific development version of the Blaxel TypeScript SDK: 
    npm install @blaxel/core@0.2.63-dev.68
With these changes, you can include additional keep-alive metadata when launching a new sandbox:
TypeScript
import { SandboxInstance } from "@blaxel/core";

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

// Start a dev server that keeps the sandbox awake
await sandbox.process.exec({
  name: "dev-server",
  command: "npm run dev -- --hostname 0.0.0.0 --port 3000",
  keepAlive: true,        // Prevents auto-standby
  timeout: 3600           // Auto-kill after 1 hour
});
If a timeout value is not specified, it defaults to 600 seconds. For processes that should run indefinitely until they complete naturally, set the timeout to 0. You can run multiple processes, and the sandbox will stay active until all of them complete:
TypeScript
import { SandboxInstance } from "@blaxel/core";

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

await sandbox.process.exec({
  name: "api-server",
  command: "npm run start:api",
  keepAlive: true,
  timeout: 3600
});

await sandbox.process.exec({
  name: "worker",
  command: "npm run start:worker",
  keepAlive: true,
  timeout: 3600
});

​
Process statuses

A process can have either of the following status:
  • running
  • completed
  • failed
  • killed
  • stopped