Skip to main content
Logging provides developers with visibility into process outputs within sandboxes. You can retrieve logs either in batch or streaming.
Complete code examples demonstrating all operations are available on Blaxel’s GitHub: in TypeScript, in Python, and in Go.
The Blaxel SDK requires two environment variables to authenticate:
VariableDescription
BL_WORKSPACEYour Blaxel workspace name
BL_API_KEYYour 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
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.

​
In batch

​
Retrieve from the execution object

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. Both standard output (stdout) and standard error (stderr) are surfaced: 
import { SandboxInstance } from "@blaxel/core";

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

const process = await sandbox.process.exec({
  name: "hello-process",
  command: "echo 'Hello, World!'",
  waitForCompletion: true
});
console.log(process.logs);

​
Retrieve from a completed process name or ID

Retrieve logs for a specific process (using either its name or process ID) after it has completed execution. By default, this retrieves standard output (stdout) only: 
const process = await sandbox.process.exec({
  name: "hello-process",
  command: "echo 'Hello, World!'"
});

const logs = await sandbox.process.logs("hello-process");
To retrieve standard error (stderr): 
const errorLogs = await sandbox.process.logs("hello-process", "stderr");
To retrieve both stderr and stdout: 
const allLogs = await sandbox.process.logs("hello-process", "all");

​
Streaming

​
Retrieve via a callback function

The callback handlers receive log entries in real-time as they’re generated by the process:
  • onLog/on_log: Receives complete log objects with additional metadata
This method ensures you get a full view, as it first backfills with all past logs before beginning the real-time stream. This approach is ideal for long-running processes where you need to monitor progress or respond to specific log events during execution. 
await sandbox.process.exec({
  name: "streaming-demo",
  command: "echo 'Starting process'; sleep 2; echo 'Processing...'; sleep 2; echo 'Completed!
  onLog: (log) => {
    console.log(`LOG: ${JSON.stringify(log)}`);
  }
});

​
Retrieve from a process name or ID

Stream logs for a specific process (using either its name or process ID): 
// Start a long-running process
await sandbox.process.exec({
  name: "stream-demo",
  command: "sh -c 'for i in $(seq 1 5); do echo \"Output $i\"; sleep 1; done'"
});

const stream = sandbox.process.streamLogs("stream-demo", {
  onLog: (log) => console.log("Log:", log),
  onStdout: (stdout) => console.log("Stdout:", stdout),
  onStderr: (stderr) => console.log("Stderr:", stderr)
});

// Wait for completion and cleanup
await sandbox.process.wait("stream-demo");
stream.close();
Last modified on April 10, 2026