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 and in Python.
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.

​
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();
⌘I