Skip to main content
Blaxel is a cloud computing infrastructure built for AI agents. Our computing platform provides compute runtimes and hosting services that AI can use — from code sandboxes to background task infrastructure.

​
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
For the most reliable solution, we recommend adapting the aforementioned Linux commands by using Windows Subsystem for Linux.First install WSL (Windows Subsystem for Linux) if not already installed. This can be done by:
  • Opening PowerShell as Administrator
  • Running: wsl --install -d Ubuntu-20.04
  • Restarting the computer
  • From the Microsoft Store, install the Ubuntu app
  • Run the command line using the aforementioned Linux installation process. Make sure to install using sudo.
2

Login

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

Create your first resource

Blaxel is the ultimate toolkit for AI agent builders. Our flagship product is the Sandbox, though you can also run the rest of your agentic workloads on our cloud.
Sandboxes can be created programmatically using Blaxel SDK. Install the SDK:

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

// Create a new sandbox
const sandbox = await SandboxInstance.create({
  name: "my-sandbox",
  image: "blaxel/prod-base:latest",   // public or custom image
  memory: 4096,   // in MB
  ports: [{ target: 3000, protocol: "HTTP" }],   // ports to expose
  region: "us-pdx-1"   // if not specified, Blaxel will choose a default region
});

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, a WebSocket endpoint is generated on Global Agentics Network to connect to the server.The server endpoint looks like this:
Connect to an MCP server

wss://run.blaxel.ai/{YOUR-WORKSPACE}/functions/{YOUR-SERVER-NAME}
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!

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.
⌘I