Set up Blaxel with an AI agent

name: blaxel
description: Use when building, deploying, and managing AI agents and their
  infrastructure. Reach for Blaxel when you need to create sandboxes for code
  execution, deploy agents as serverless endpoints, run batch jobs, host MCP
  servers, manage persistent storage, or orchestrate complex agentic workflows
  on a cloud platform designed for autonomous systems.
metadata:
  mintlify-proj: blaxel
  version: "1.0"

Blaxel Skill

Product summary

Blaxel is infrastructure for autonomous agents. It provides a cloud platform where AI agents run as primary users, with instant-launching sandboxes (microVMs resuming from standby in <25ms), serverless agent hosting, batch job execution, MCP server deployment, and persistent storage (Volumes and Agent Drive). The platform is accessed via CLI (bl), SDKs (TypeScript, Python, Go), REST APIs, and MCP servers. Key files: blaxel.toml (deployment config), .env (credentials). Primary docs: https://docs.blaxel.ai

When to use

• Creating sandboxes: When an agent needs its own isolated compute environment to run code, execute commands, or access a filesystem
• Deploying agents: When building serverless HTTP API endpoints for AI agents that process requests synchronously or asynchronously
• Running batch jobs: When scheduling parallel background tasks that may run for minutes to hours with configurable retries and timeouts
• Hosting MCP servers: When exposing tools or capabilities via the Model Context Protocol for agents to discover and invoke
• Persistent storage: When data must survive sandbox deletion (Volumes for single-writer, Agent Drive for multi-reader/writer scenarios)
• Local development: When testing agents, jobs, or MCP servers before deployment with bl serve
• Resource management: When listing, monitoring, or deleting deployed resources across your workspace

Quick reference

Essential CLI commands

Command	Purpose
bl login	Authenticate to your workspace
bl new {agent|job|mcp|sandbox}	Scaffold a new project with blaxel.toml
bl deploy	Build, push image, and deploy resource
bl serve	Run resource locally (agents, jobs, MCP servers)
bl get {sandboxes|agents|jobs|functions}	List resources in workspace
bl chat AGENT-NAME	Interactive chat with deployed agent
bl run job JOB-NAME --data '{...}'	Trigger job execution
bl connect sandbox SANDBOX-NAME	Open interactive terminal in sandbox
bl delete {sandbox|agent|job|function} NAME	Delete resource

Authentication

Set environment variables or .env file:

export BL_WORKSPACE=your-workspace-name
export BL_API_KEY=your-api-key
export BL_REGION=us-pdx-1  # optional default region

Or use browser login: bl login

blaxel.toml structure

type = "agent"  # or "job", "function", "sandbox", "volume-template"
name = "my-resource"
region = "us-pdx-1"

[build]
slim = true  # remove build-time paths from image
memoryMb = 8192

[env]
MY_VAR = "value"

[runtime]
memory = 4096  # MB; CPU = memory/2048
timeout = 900  # seconds (jobs only)
maxConcurrentTasks = 10  # jobs only

[[volumes]]
name = "my-volume"
mountPath = "/data"

[[triggers]]
type = "http"  # or "http-async", "cron"
[triggers.configuration]
path = "/webhook"

Resource types and boot times

Resource	Use case	Boot time	Max duration
Sandbox	Full compute runtime for agents	~25ms (from standby)	Hours
Agent (sync)	Fast HTTP API responses	~25ms	100 seconds
Agent (async)	Longer HTTP processing	~25ms	10 minutes
Batch Job	Background parallel tasks	~30s	24 hours
MCP Server	Tool/capability endpoint	~25ms	10 minutes

Storage options

Storage	Persistence	Sharing	Access	Best for
Sandbox filesystem	Until sandbox deletion	Single	POSIX	Scratch, temp files
Volume	Survives deletion	Single	POSIX block	Databases, agent memory
Agent Drive	Survives deletion	Multiple	POSIX + S3	Shared state, multi-sandbox

Decision guidance

When to use Sandbox vs Agent Hosting vs Batch Job

Scenario	Choose
Agent needs full OS access, long-running processes, or custom tools	Sandbox
Agent responds to HTTP requests within seconds	Agent (sync)
Agent processes HTTP requests for minutes without keeping connection open	Agent (async)
Agent schedules background work in parallel batches	Batch Job
Agent needs instant resume after weeks idle, with memory preserved	Sandbox (standby mode)

When to use Volume vs Agent Drive

Scenario	Choose
Data only needs to survive current sandbox session	Sandbox filesystem
Data must persist, only one sandbox accesses it at a time	Volume
Multiple sandboxes/agents read/write simultaneously	Agent Drive
Need high-performance block storage for databases	Volume
Need shared filesystem across tenants or sessions	Agent Drive

When to use bl deploy vs bl push

Scenario	Choose
Build image AND create/update resource in one step	bl deploy
Only build and push image to registry, no resource creation	bl push
Skip image rebuild on redeploy	bl deploy --skip-build

Workflow

Deploy a new agent

1. Scaffold: bl new agent my-agent
2. Develop: Edit /src/main.py or /src/main.ts with your agent logic; expose HTTP endpoint
3. Configure: Edit blaxel.toml with name, region, memory, environment variables
4. Test locally: bl serve then POST to http://localhost:1338 with {"inputs": "..."}
5. Deploy: bl deploy (builds image, pushes, creates resource, streams logs)
6. Query: bl chat my-agent or call the global endpoint with API key

Create and use a sandbox

1. Create: Use SDK SandboxInstance.createIfNotExists({name, image, memory, region}) or bl new sandbox my-sandbox && bl deploy
2. Connect: bl connect sandbox my-sandbox for interactive terminal
3. Execute: Use SDK to run processes, read/write files, or access via REST API
4. Attach storage: Volumes at creation time; Agent Drive after creation with sandbox.drives.mount()
5. Manage lifecycle: Sandbox auto-scales to standby after 15s inactivity; manually delete with bl delete sandbox my-sandbox

Deploy a batch job

1. Scaffold: bl new job my-job
2. Develop: Edit /src/index.py or /src/index.ts to process task array
3. Configure: Set maxConcurrentTasks, timeout, maxRetries in blaxel.toml
4. Test: bl serve then POST {"tasks": [{...}, {...}]}
5. Deploy: bl deploy
6. Trigger: bl run job my-job --data '{"tasks": [...]}' or call endpoint

Host an MCP server

1. Scaffold: bl new mcp my-server
2. Develop: Define tools in /src/server.py or /src/server.ts following MCP spec
3. Test: pnpm inspect (TypeScript) or BL_DEBUG=true uv run mcp dev src/server.py (Python)
4. Deploy: bl deploy
5. Connect: Agents call https://run.blaxel.ai/{workspace}/functions/{server-name}/mcp

Attach persistent storage

Volume (at sandbox creation):

sandbox = await SandboxInstance.create_if_not_exists({
    "name": "my-sandbox",
    "volumes": [{"name": "my-volume", "mount_path": "/data"}]
})

Agent Drive (hot-attach to running sandbox):

drive = await AgentDrive.get("my-drive")
await sandbox.drives.mount(drive, mount_path="/shared")

Common gotchas

• Region mismatch: Volumes and sandboxes must be in the same region. Set region in blaxel.toml or use BL_REGION env var
• Standby timeout: WebSocket/TCP connections idle for 15 minutes trigger standby; use ping/pong or keep-alive to prevent
• Reserved ports: Ports 80, 443, 8080 are reserved; expose other ports in ports array at sandbox creation
• Image slimming: By default slim = true removes build-time files (caches, compilers); set to false if tools are needed at runtime
• External connections lost on standby: Database connections, message queues, HTTP pools close when sandbox enters standby; reconnect on resume
• Sandbox filesystem not durable: ~50% of memory is writable tmpfs; data is lost on deletion. Use Volumes or Agent Drive for persistence
• Agent Drive in preview: Currently only available in us-was-1 region
• Secrets vs env vars: [env] in blaxel.toml are NOT secrets; use bl deploy -s KEY=value for secrets
• Monorepo deployments: Use bl deploy -d subdirectory or bl deploy -R for recursive deployment
• Non-interactive CI: Use bl deploy --yes or --wait for CI/CD pipelines; set BL_API_KEY env var

Verification checklist

Before deploying or submitting work:

• Authenticated: bl login succeeded or BL_API_KEY is set
• Configuration valid: blaxel.toml has required fields (type, name optional but recommended)
• Region specified: region in blaxel.toml or BL_REGION env var set (required for volumes)
• Local test passed: bl serve runs without errors; test endpoint responds correctly
• Image builds: bl deploy completes build phase without errors
• Resource deployed: Status shows DEPLOYED (check with bl get agents/jobs/functions/sandboxes)
• Endpoint accessible: Can query agent/job/MCP server from CLI or API
• Storage attached: If using volumes, verify mount path exists in running resource
• Secrets injected: Sensitive values passed via -s flag, not in blaxel.toml
• Logs clean: No warnings or errors in deployment logs

Resources

Comprehensive navigation: https://docs.blaxel.ai/llms.txt

Critical documentation:

• Sandboxes Overview — Create and manage compute environments
• Deployment Reference — Complete blaxel.toml configuration
• CLI Reference — All bl commands and options

---

For additional documentation and navigation, see: https://docs.blaxel.ai/llms.txt