Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.blaxel.ai/llms.txt

Use this file to discover all available pages before exploring further.

Blaxel is a perpetual sandbox platform built for AI agents. Our computing platform lets you keep infinite, secure sandboxes on automatic standby while co-hosting your agents for near instant latency.
Using Cursor, Claude Code, Codex, Goose, or another AI coding agent?Install the Blaxel Skill to give your agent the ability to deploy AI agents, create sandboxes for code execution, host MCP servers, run batch jobs, and more…all using simple prompts, zero code required!
npx skills add blaxel-ai/agent-skills

​
Quickstart

Welcome there! 👋 Make sure you have created an account on Blaxel (here → https://app.blaxel.ai), and created a first workspace (you’ll need the workspace ID).
1

Install Blaxel CLI

To install Blaxel CLI, you must use Homebrew: make sure it is installed on your machine. We are currently in the process of supporting additional installers. Check out the cURL method down below for general installation.
Install Blaxel CLI by running the two following commands successively in a terminal:

brew tap blaxel-ai/blaxel



brew install blaxel
Install Blaxel CLI by running the following command in a terminal (non-sudo alternatives below):
curl -fsSL \
https://raw.githubusercontent.com/blaxel-ai/toolkit/main/install.sh \
| BINDIR=/usr/local/bin sudo -E sh
If you need a non-sudo alternative (it will ask you questions to configure):
curl -fsSL \
https://raw.githubusercontent.com/blaxel-ai/toolkit/main/install.sh \
| sh
If you need to install a specific version (e.g. v0.1.21):
curl -fsSL \
https://raw.githubusercontent.com/blaxel-ai/toolkit/main/install.sh \
| VERSION=v0.1.21 sh
Install Blaxel CLI by running the following command in a terminal (non-sudo alternatives below):
curl -fsSL \
https://raw.githubusercontent.com/blaxel-ai/toolkit/main/install.sh \
| BINDIR=/usr/local/bin sudo -E sh
If you need a non-sudo alternative (it will ask you questions to configure):
curl -fsSL \
https://raw.githubusercontent.com/blaxel-ai/toolkit/main/install.sh \
| sh
If you need to install a specific version (e.g. v0.1.21):
curl -fsSL \
https://raw.githubusercontent.com/blaxel-ai/toolkit/main/install.sh \
| VERSION=v0.1.21 sh
Run the following command in PowerShell:
powershell -Command "irm https://raw.githubusercontent.com/blaxel-ai/toolkit/main/install.ps1 | iex"
Alternatively, you can use Windows Subsystem for Linux (WSL) and follow the Linux installation instructions.
2

Login

Open a terminal and login to Blaxel using this command:
bl login
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.
3

Create your first resource

Blaxel is the ultimate toolkit for AI agent builders. Our flagship product is the sandbox, although we also offer other services for the rest of your agentic workloads on our infrastructure.Sandboxes are secure, instant-launching compute environments that you can use for running AI code. Blaxel lets you keeps sandboxes on automatic standby with optimized agent hosting for near instant latency.With Blaxel sandboxes, you get:
  • Automatic scale-to-zero after 5s inactivity, resume from standby under 25ms even after weeks.
  • Micro-VMs with full access to file system, processes and logs — and native support for Zero Data Retention (ZDR).
  • Preview URLs with your own custom domain.
Sandboxes can be created programmatically using Blaxel SDK. Install the SDK:

pip install blaxel
Create your first sandbox:
import { SandboxInstance } from "@blaxel/core";

async function main() {
  // Create a new sandbox
  const sandbox = await SandboxInstance.createIfNotExists({
    name: "my-sandbox",
    image: "blaxel/base-image:latest",   // public or custom image
    memory: 4096,   // in MB
    ports: [{ target: 3000, protocol: "HTTP" }],   // ports to expose
    labels: { env: "dev", project: "my-project" }, // labels
    region: "us-pdx-1"   // deployment region
  });
  console.log("Sandbox created: ", {sandbox});
}

main().catch(console.error);

Learn how to manage sandboxes

Read the complete guide for creating & connecting to sandboxes using Blaxel SDK.
Or deploy another type of resource:
Deploy your agent’s components on a purpose-built computing infrastructure for agentics.
1

Create the resource

In Python, you will need to have pip installed; in TypeScript, you will need to have npm installed for this.
Let’s initialize a first app. The following command initializes a new pre-scaffolded local repository ready for developing and deploying your agent on Blaxel.
bl new agent
You can now develop your agent application using any framework you want (or none), and use the Blaxel SDK to leverage other Blaxel deployments. A placeholder HTTP API server is already preconfigured in /src/main.py or /src/main.ts.
In Python, you will need to have pip installed; in TypeScript, you will need to have npm installed for this.
Let’s initialize a first batch job definition. The following command initializes a new pre-scaffolded local repository ready for developing and deploying your job on Blaxel.
bl new job
You can now develop your job and use the Blaxel SDK to leverage other Blaxel deployments in /src/index.py or /src/index.ts.
In Python, you will need to have pip installed; in TypeScript, you will need to have npm installed for this.
You can quickly initialize a new MCP server from scratch by using CLI command bl new. This initializes a new pre-scaffolded local repo where your entire code can be added.
bl new mcp
You can now develop your MCP server using the Blaxel SDK in /src/server.py or /src/server.ts.
2

Test and deploy your workload

Run the following command to serve your workload locally, replacing <<DIRECTORY-NAME>> with the name of the workload’s root directory:
cd <<DIRECTORY-NAME>>;
bl serve;
Query your agent locally by making a POST request to this endpoint: http://localhost:1338 with the following payload format: {"inputs": "Hello world!"}:
curl -X POST -H "Content-Type: application/json" -d '{"inputs": "Hello world!"}' http://localhost:1338
Execute your job locally by making a POST request to this endpoint: http://localhost:1338 with the following payload format: {"tasks": [{"param1": "value1"}]}
curl -X POST -H "Content-Type: application/json" -d '{"tasks": [{"name": "John"}, {"name": "Jane"}]}' http://localhost:1338
You can test it by running the following command which launches both the MCP server and a web application to query it (MCP Inspector, managed by MCP) locally.

pnpm inspect
The web application is accessible at: http://127.0.0.1:6274. Alternatively, you can just simply serve the server locally by running bl serve --hotreload.
To push to Blaxel, run the following command. Blaxel will handle the build and deployment:
bl deploy
Your workload is made available as a serverless auto scalable global endpoint 🌎.
3

Query your deployment

Run an inference from a terminal with the following command:
bl chat <<AGENT-NAME>>
This gives you a chat-like interface where you can interact with your agent. To use this when serving locally, just add option --local.Alternatively, just call the global endpoint.
Trigger an execution of your batch job from a terminal by running:
# Run a job using Blaxel CLI with --data argument
bl run job <<JOB-NAME>> --data '{"tasks": [{"name": "John"}, {"name": "Jane"}]}'
Alternatively, just call the global endpoint.
When you deploy an MCP server on Blaxel, an HTTP endpoint is generated on Global Agentics Network to connect to the server.The server endpoint looks like this:
Connect to an MCP server

https://run.blaxel.ai/{YOUR-WORKSPACE}/functions/{YOUR-SERVER-NAME}/mcp
Read more about how to connect to the server here.

​
Next steps

You are ready to run AI with Blaxel! Here’s a curated list of guides which may be helpful for you to make the most of Blaxel, but feel free to explore the product on your own!

Connect your coding agent to Blaxel

Let your AI coding assistant (Cursor, Claude Code, Windsurf…) create and manage Blaxel resources using natural language.

Create agentic code sandboxes

Complete guide for spawning sandboxed VMs for your agents to access.

Schedule and execute batch tasks

Complete guide for creating and running batch jobs from your agents.

Host serverless agents

Complete guide for deploying AI agents on Blaxel.

Enforce policies

Complete guide for managing deployment and routing policies on the Global Agentics Network.

​
Any question?

Although we designed this documentation to be as comprehensive as possible, you are welcome to contact support@blaxel.ai or the community on Discord with any questions or feedback you have.
Last modified on May 19, 2026