Get started

Blaxel is a computing platform where AI builders can deploy AI agents easily. This tutorial demonstrates how to deploy your first workload on Blaxel.

Quickstart

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

Upon creating a workspace, Blaxel automatically adds a starter connection to a rate-limited model API to get you started. You can bring your own credentials to model providers to connect to more model APIs.

Install Blaxel CLI

Install on Mac

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 on Linux

Install Blaxel CLI by running the following command in a terminal (alternatives below):

curl -fsSL \
https://raw.githubusercontent.com/blaxel-ai/toolkit/main/install.sh \
| BINDIR=/usr/local/bin sudo -E sh

If you need to specify a version (e.g. v0.1.21):

curl -fsSL \
https://raw.githubusercontent.com/blaxel-ai/toolkit/main/install.sh \
| VERSION=v0.1.21 BINDIR=/usr/local/bin sudo -E sh

Install with cURL

Install Blaxel CLI by running the following command in a terminal (alternatives below):

curl -fsSL \
https://raw.githubusercontent.com/blaxel-ai/toolkit/main/install.sh \
| BINDIR=/usr/local/bin sudo -E sh

If you need to specify a version (e.g. v0.1.21):

curl -fsSL \
https://raw.githubusercontent.com/blaxel-ai/toolkit/main/install.sh \
| VERSION=v0.1.21 BINDIR=/usr/local/bin sudo -E sh

Install on Windows

Install a package manager (if not done already)

Python: install uv

TypeScript: install npm

Create your first resource

Blaxel is the ultimate toolkit for AI agent builders, letting you create and deploy resources on a purpose-built infrastructure for agentics.

Create an agent application

In Python, you will need to have uv installed; in TypeScript, you will need to have npm installed for this.

Let’s initialize a first app. The following command creates a pre-scaffolded local repository ready for developing and deploying your agent on Blaxel.

bl create-agent-app my-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 in /src/agent.py or /src/agent.ts. A placeholder HTTP API server is already preconfigured in /src/main.py or /src/main.ts.

Create a batch job

In Python, you will need to have uv installed; in TypeScript, you will need to have npm installed for this.

Let’s initialize a first batch job definition. The following command creates a pre-scaffolded local repository ready for developing and deploying your job on Blaxel.

bl create-job myjob

You can now develop your job and use the Blaxel SDK to leverage other Blaxel deployments in /src/index.py or /src/index.ts.

Create a sandbox

Sandboxes can be created programmatically using Blaxel SDK. Install the SDK:

pip install blaxel

Learn how to create sandboxes

Read the guide for creating and connecting to sandboxes using Blaxel SDK.

Create an MCP server

In Python, you will need to have uv 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 create-mcp-server. This will create a pre-scaffolded local repo where your entire code can be added.

bl create-mcp-server my-mcp

You can now develop your MCP server using the Blaxel SDK in /src/server.py or /src/server.ts.

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;

Agent: send a test invocation

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

Job: execute the job locally

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

MCP server: test the server

You can test it by running the following command which launches both the server and a web application (MCP Inspector, managed by MCP) locally for testing the server’s capabilities during development.

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 🌎 .

Make a first inference

Agent: send an invocation request

Run a first inference on your Blaxel agent with the following command:

bl chat my-agent

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, you can send requests to your production agent by running:

bl run agent my-agent --data '{"inputs":"Hello world!"}'

Or by directly calling the global endpoint.

Job: execute the job

MCP server: test the server

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!

Deploy serverless agents

Complete guide for deploying AI agents on Blaxel.

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.

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.

Agents Hosting

Sandboxes 🆕

Batch Jobs 🆕

MCP Servers Hosting

Model Gateway

Observability

Integrations

Administration & security

Get started

Quickstart

Learn how to create sandboxes

Next steps

Deploy serverless agents

Create agentic code sandboxes

Schedule and execute batch tasks

Enforce policies

Any question?

Get Started

Agents Hosting

Sandboxes 🆕

Batch Jobs 🆕

MCP Servers Hosting

Model Gateway

Observability

Integrations

Administration & security

​Quickstart

​Next steps

Deploy serverless agents

Create agentic code sandboxes

Schedule and execute batch tasks

Enforce policies

​Any question?

Quickstart

Next steps

Any question?