---
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:
```bash
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

```toml
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)**:
```python
sandbox = await SandboxInstance.create_if_not_exists({
    "name": "my-sandbox",
    "volumes": [{"name": "my-volume", "mount_path": "/data"}]
})
```

**Agent Drive (hot-attach to running sandbox)**:
```python
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](https://docs.blaxel.ai/Sandboxes/Overview) — Create and manage compute environments
- [Deployment Reference](https://docs.blaxel.ai/deployment-reference) — Complete blaxel.toml configuration
- [CLI Reference](https://docs.blaxel.ai/cli-reference/introduction) — All `bl` commands and options

---

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