Process execution

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

Learn more about authentication on Blaxel

The Blaxel SDK requires two environment variables to authenticate:

Variable	Description
`BL_WORKSPACE`	Your Blaxel workspace name
`BL_API_KEY`	Your Blaxel API key

You can create an API key from the Blaxel console. Your workspace name is visible in the URL when you log in to the console (e.g. app.blaxel.ai/{workspace}).Set them as environment variables or add them to a .env file at the root of your project:

export BL_WORKSPACE=my-workspace
export BL_API_KEY=my-api-key

The Blaxel SDK does not accept credentials as constructor arguments. Credentials must come from environment variables, a .env file, or a local CLI login session (see below).When developing locally, you can also log in to your workspace with Blaxel CLI (as shown above). This allows you to run Blaxel SDK functions that will automatically connect to your workspace without additional setup. When you deploy on Blaxel, authentication is handled automatically — no environment variables needed.

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!'"
});

from blaxel.core import SandboxInstance

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

# Execute command
process = await sandbox.process.exec({
  "command": "echo 'Hello, World!'"
})

By default, exec returns after starting the process without waiting for it to finish. Its output may not be available yet.

Get command output

Set waitForCompletion: true ("wait_for_completion": True in Python) to wait for the command to finish. The result then holds its stdout, stderr, and exitCode (exit_code in Python):

const result = await sandbox.process.exec({
  command: "ls /",
  waitForCompletion: true
});

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

result = await sandbox.process.exec({
  "command": "ls /",
  "wait_for_completion": True
})

print(result.exit_code)
print(result.stdout)
print(result.stderr)

The logs field holds stdout and stderr together. A command that exits with a non-zero code does not raise an error: its status is failed, so check the exit code. Set timeout to bound how long the call waits. For longer commands, see Wait for process completion. Process execution logs are also visible in the Blaxel Console. Refer to the Logs section of the sandbox detail page, as shown below:

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"
});

from blaxel.core import SandboxInstance

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

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

workingDir is a JSON request-body field, not a URL path. Pass a normal absolute filesystem path such as "/workspace"; do not URL-encode it as "%2Fworkspace". In Python, the equivalent field is working_dir.

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");

process = await sandbox.process.exec({
  "name": "hello-process",
  "command": "echo 'Hello, World!'"
})
process_info = 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") {
  // ...
}

completed_process = await sandbox.process.get("hello-process")
if completed_process.status == "completed":
    # ...

The exit code of the process is available in the exitCode parameter (exit_code in Python) 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")

await sandbox.process.kill("test")

Long-running processes

Blaxel Sandboxes are great for long-running processes. Processes you launch detach by design: their stdout and stderr are redirected to files and the process is monitored by background workers in the sandbox, so it survives independently of your client connection. By default, the general sandbox lifecycle rules still apply: the sandbox only stays awake while a connection is maintained and will suspend after a few seconds of inactivity. Use keepAlive to override this for the duration of a process. Two independent flags let you tune how the behavior works.

waitForCompletion (default: false) controls only whether the SDK call blocks until the process exits and returns its output. It has no effect on the process or sandbox lifetime.
keepAlive (default: none) controls only whether the sandbox stays awake (auto-standby/scale-to-zero disabled) while the process runs, even with no active client connection. A counter tracks running keepAlive processes and is decremented automatically when each one completes, letting the sandbox return to standby on its own. See Sandbox keep-alive for details.

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: 60 // 60 seconds
});

process = await sandbox.process.exec({
  "name": "build-process",
  "command": "npm run build",
  "wait_for_completion": True,
  "timeout": 60  # 60 seconds
})

When waiting for completion, the process execution object contains the command’s output: stdout, stderr, and both combined in logs. Also, notice the timeout parameter which allows you to set the process timeout duration in seconds.

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.

For processes without keepAlive: true, the timeout parameter does not kill the process. It only bounds how long the API call waits when using waitForCompletion (or waitForPorts); once the timeout elapses, an error is returned but the process keeps running in the background. Non-keepAlive processes have no auto-kill timeout and run until they complete on their own. To auto-kill a process after a duration, use keepAlive: true together with a timeout (see Sandbox keep-alive).

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
});

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", max_wait=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. exec returns as soon as the ports are open, and the process keeps running in the background.

const process = await sandbox.process.exec({
  name: "dev-server",
  command: "npm run dev -- --host $HOST --port 3000",
  waitForPorts: [3000],
  timeout: 60
});

process = await sandbox.process.exec({
  "name": "dev-server",
  "command": "npm run dev -- --host $HOST --port 3000",
  "wait_for_ports": [3000],
  "timeout": 60
})

A port counts as open once the server listens on the address in HOST (or on all interfaces). A server bound only to localhost isn’t reachable from outside the sandbox, so it doesn’t count. timeout bounds how long the call waits for the ports. Keep it under 120 seconds: a request that stays open that long is cut off by the gateway with a 504 error instead of the timeout error. If the process fails before its ports open (it exits with a non-zero code or is killed), the call fails right away instead of waiting out the timeout. The error includes the exit code and the last lines of the process’s output:

try {
  await sandbox.process.exec({
    name: "dev-server",
    command: "npm run dev -- --host $HOST --port 3000",
    waitForPorts: [3000],
    timeout: 60
  });
} catch (error) {
  // e.g. "process exited with code 1 before ports [3000] opened; last output: ..."
  console.error(error.message);
}

try:
    await sandbox.process.exec({
        "name": "dev-server",
        "command": "npm run dev -- --host $HOST --port 3000",
        "wait_for_ports": [3000],
        "timeout": 60
    })
except Exception as error:
    # e.g. "process exited with code 1 before ports [3000] opened; last output: ..."
    print(error)

Don’t end the command with &. The shell exits straight away and the server it put in the background isn’t tracked as part of the process, so the call waits until timeout and a startup crash isn’t reported. Failing fast needs sandbox-api 0.2.62 or later; custom images pick it up when rebuilt.

Process stdin

By default, a process has no stdin: it reads end-of-file as soon as it starts. Start it with stdin: true to give it a writable pipe, then send input with writeStdin and close the pipe with closeStdin. Use this to drive programs that read from stdin, such as stdio MCP servers and other JSON-RPC programs. The pipe passes your bytes through unchanged. Unlike the interactive terminal, there is no TTY in between, so nothing is echoed back or rewritten.

Process stdin needs @blaxel/core 0.3.19 or later in TypeScript, blaxel 0.4.9 or later in Python, and sandbox-api 0.2.56 or later in the sandbox. Custom images pick it up when rebuilt.

Write to a process

Start the process with a name and stdin: true, write to it, then close stdin to send end-of-file:

await sandbox.process.exec({
  name: "sort",
  command: "sort",
  stdin: true
});

await sandbox.process.writeStdin("sort", "cherry\napple\nbanana\n");
await sandbox.process.closeStdin("sort");

await sandbox.process.wait("sort");
const output = await sandbox.process.logs("sort", "stdout");
// "apple\nbanana\ncherry\n"

await sandbox.process.exec({
  "name": "sort",
  "command": "sort",
  "stdin": True
})

await sandbox.process.write_stdin("sort", "cherry\napple\nbanana\n")
await sandbox.process.close_stdin("sort")

await sandbox.process.wait("sort")
output = await sandbox.process.logs("sort", "stdout")
# "apple\nbanana\ncherry\n"

writeStdin (write_stdin in Python) takes a string or bytes and writes them as is, so include the trailing newline your program expects. closeStdin (close_stdin in Python) can be called more than once.

Run a stdio MCP server

A stdio MCP server reads JSON-RPC messages from stdin and writes one reply per line to stdout. Send each message with writeStdin, and read the replies by streaming the process’s stdout:

await sandbox.process.exec({
  name: "mcp-fs",
  command: "npx -y @modelcontextprotocol/server-filesystem /tmp",
  stdin: true
});

// Each stdout line is one JSON-RPC message from the server
const pending = new Map<number, (message: any) => void>();
const stream = sandbox.process.streamLogs("mcp-fs", {
  onStdout: (line) => {
    const message = JSON.parse(line);
    pending.get(message.id)?.(message);
  }
});

const send = (message: object) =>
  sandbox.process.writeStdin("mcp-fs", JSON.stringify(message) + "\n");
const request = (id: number, method: string, params: object = {}) =>
  new Promise<any>((resolve) => {
    pending.set(id, resolve);
    void send({ jsonrpc: "2.0", id, method, params });
  });

await request(1, "initialize", {
  protocolVersion: "2025-06-18",
  capabilities: {},
  clientInfo: { name: "my-client", version: "1.0.0" }
});
await send({ jsonrpc: "2.0", method: "notifications/initialized" });
const tools = await request(2, "tools/list");

// Closing stdin shuts the server down
await sandbox.process.closeStdin("mcp-fs");
stream.close();

import asyncio
import json

await sandbox.process.exec({
  "name": "mcp-fs",
  "command": "npx -y @modelcontextprotocol/server-filesystem /tmp",
  "stdin": True
})

# Each stdout line is one JSON-RPC message from the server
pending = {}

def on_stdout(line):
    message = json.loads(line)
    reply = pending.pop(message.get("id"), None)
    if reply:
        reply.set_result(message)

stream = sandbox.process.stream_logs("mcp-fs", {"on_stdout": on_stdout})

async def send(message):
    await sandbox.process.write_stdin("mcp-fs", json.dumps(message) + "\n")

async def request(request_id, method, params=None):
    reply = asyncio.get_running_loop().create_future()
    pending[request_id] = reply
    await send({"jsonrpc": "2.0", "id": request_id, "method": method, "params": params or {}})
    return await reply

await request(1, "initialize", {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": {"name": "my-client", "version": "1.0.0"}
})
await send({"jsonrpc": "2.0", "method": "notifications/initialized"})
tools = await request(2, "tools/list")

# Closing stdin shuts the server down
await sandbox.process.close_stdin("mcp-fs")
stream.close()

The first npx run downloads the server package, so the first reply can take several seconds.

Stdin errors and restarts

Sequential writes keep their order, and two concurrent writes never mix inside a message. The SDK does not retry a failed write, since a duplicate would corrupt the stream. A write fails with:

409 if the process was started without stdin: true, or its stdin is closed
413 if the data is larger than 8 MiB
503 if the process stopped reading and the pipe stayed full for 10 seconds

After a 503, part of the data may have gone through, so restart the process. The pipe survives sandbox standby and resume. With restartOnFailure, each restart gets a new pipe, and data written between the failure and the restart is lost. If the sandbox API itself restarts, the process reads end-of-file and writes fail with 409: restart the process and redo your protocol’s handshake. Over the Sandbox API, start the process with "stdin": true on POST /process, then write to its stdin with POST /process/{identifier}/stdin and the raw bytes as the request body, and close its stdin with DELETE /process/{identifier}/stdin.

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 $HOST --port 8000",
  restartOnFailure: true,
  maxRestarts: 5
});

process = await sandbox.process.exec({
  "name": "start-server",
  "command": "uvicorn main:app --reload --host $HOST --port 8000",
  "restart_on_failure": True,
  "max_restarts": 5
})

Sandbox keep-alive

By default, sandboxes automatically switch to standby when there is no active connection to save resources. However, it is possible to adjust this behavior 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 long-running task actively running within the sandbox environment even when it is not serving requests. You can include additional keep-alive metadata when launching a new process:

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 $HOST --port 3000",
  keepAlive: true,        // Prevents auto-standby while the process runs
  timeout: 3600           // Auto-kill the process after 1 hour. Set 0 to not auto-kill.
});

from blaxel.core import SandboxInstance

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 $HOST --port 3000",
  "keep_alive": True,        # Prevents auto-standby
  "timeout": 3600            # Auto-kill after 1 hour
})

The auto-kill timeout and its 600-second default only apply to processes started with keepAlive: true. If a keepAlive process is started without a timeout, it defaults to 600 seconds (10 minutes) and is automatically terminated when the timeout elapses. To run a keepAlive process indefinitely with no auto-kill, set timeout: 0. The table below summarizes how keepAlive and timeout interact:

Configuration	Process auto-kill behavior	`timeout` parameter effect
`keepAlive` not set (default)	Never auto-killed. Runs until it completes on its own.	Only bounds how long the API waits when using `waitForCompletion` or `waitForPorts`. Does not terminate the process.
`keepAlive: true`, no `timeout`	Auto-killed after 600 seconds (10 minutes).	—
`keepAlive: true`, `timeout: 0`	Never auto-killed. Runs until it completes on its own.	—
`keepAlive: true`, `timeout: N`	Auto-killed after N seconds.	—

You can run multiple processes, and the sandbox will stay active until all of them complete:

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
});

from blaxel.core import SandboxInstance

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

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

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

Disable process telemetry logging

By default, process stdout and stderr are exported as structured telemetry logs (visible in external observability systems). You can disable this telemetry export by setting the SANDBOX_DISABLE_PROCESS_LOGGING environment variable inside the sandbox. When set to true or 1, structured telemetry output is suppressed for all processes. File-based logging and real-time log streaming via the SDK remain fully functional and are not affected. Set this variable in your Dockerfile or at sandbox creation time:

ENV SANDBOX_DISABLE_PROCESS_LOGGING=true

Alternatively, you can disable process logging for sandboxes at workspace level using the Blaxel Console, in the Workspace settings section.

This only suppresses the structured telemetry export. You can still retrieve process logs via the SDK’s process.logs() method and stream them in real-time.

Process statuses

A process can have any of the following statuses:

running
completed
failed
killed
stopped

Get Started

Sandboxes

Agent Drive

Volumes

Batch Jobs

Applications

MCP Servers Hosting

Model Gateway

Observability

Integrations

Administration & security

Troubleshooting

Execute processes and commands

Execute command

Get command output

Set the working directory

Use process names

Kill process

Long-running processes

Wait for process completion

Wait for ports

Process stdin

Write to a process

Run a stdio MCP server

Stdin errors and restarts

Auto-restart

Restart process on failure

Sandbox keep-alive

Disable process telemetry logging

Process statuses

​Execute processes and commands

​Execute command

​Get command output

​Set the working directory

​Use process names

​Kill process

​Long-running processes

​Wait for process completion

​Wait for ports

​Process stdin

​Write to a process

​Run a stdio MCP server

​Stdin errors and restarts

​Auto-restart

​Restart process on failure

​Sandbox keep-alive

​Disable process telemetry logging

​Process statuses

Execute processes and commands

Execute command

Get command output

Set the working directory

Use process names

Kill process

Long-running processes

Wait for process completion

Wait for ports

Process stdin

Write to a process

Run a stdio MCP server

Stdin errors and restarts

Auto-restart

Restart process on failure

Sandbox keep-alive

Disable process telemetry logging

Process statuses