Use when creating cloud sandboxes (microVMs) to run code, start dev servers, and generate live preview URLs. Also covers deploying AI agents, MCP servers, batch jobs, and Agent Drives (shared filesystems) on Blaxel's serverless infrastructure. Reach for this skill when you need isolated compute envi

Blaxel Skill Reference What is Blaxel Blaxel (https://blaxel.ai) is a cloud platform that gives AI agents their own compute environments. Its flagship product is perpetual sandboxes: instant launching microVMs that resume from standby in under 25ms and scale to zero after a few seconds of inactivity. You use Blaxel primarily to: Spin up a sandbox, install dependencies, run a dev server, and expose a live preview URL Build and deploy sandbox templates (custom Docker images) for reusable environments Deploy AI agents, MCP servers, and batch jobs as serverless endpoints SDKs: TypeScript ( @blaxel/core ) and Python ( blaxel ) CLI: bl (install from https://docs.blaxel.ai/cli reference/introduction) Docs: https://docs.blaxel.ai Authentication The SDK authenticates using these sources in priority order: 1. Blaxel CLI, when logged in 2. Environment variables in .env file ( BL WORKSPACE , BL API KEY ) 3. System environment variables 4. Blaxel configuration file ( ~/.blaxel/config.yaml ) Log in locally (recommended for development): Or set environment variables (for remote/CI environments): When running on Blaxel itself, authentication is automatic. Sandbox workflow (primary use case) This is the most common workflow: create a sandbox, run commands in it, and get a preview URL. Step 1: Create a sandbox Use a public image from the Blaxel Hub (https://github.com/blaxel ai/sandbox/tree/main/hub): blaxel/base image:latest — minimal Linux blaxel/node:latest — Node.js blaxel/nextjs:latest — Next.js blaxel/vite:latest — Vite blaxel/expo:latest — Expo (React Native) blaxel/py app:latest — Python Or use a custom template image you deployed yourself. Declare the ports you need at creation time. Ports cannot be added after creation. Ports 80, 443, and 8080 are reserved. Use createIfNotExists / create if not exists to reuse an existing sandbox by name or create a new one. Always prefer this over a get then create fallback. Deleted sandboxes are kept in TERMINATED state for a few minutes (so their logs stay accessible), which means a plain get can return a dead sandbox whose gateway and preview URLs fail with workload not found. createIfNotExists checks the status for you and recreates the sandbox when the existing record is FAILED , TERMINATED , TERMINATING , or DELETING . As of @blaxel/core 0.2.88 / blaxel 0.2.55, it also waits out the brief DELETING window right after a delete, so delete then recreate works directly. On older SDK versions that window can throw "Unable to create sandbox after 3 attempts" — wait a moment and retry, or upgrade. If you must use get , check sandbox.status before reusing the instance. Step 2: Write files and run commands IMPORTANT: Dev servers must bind to 0.0.0.0 (not localhost ) to be reachable through preview URLs. Use host 0.0.0.0 or the HOST env variable. Step 3: Create a preview URL For private previews, set public: false and create a token: Step 4: Manage the sandbox Sandbox templates (custom images) When you need a reusable environment (e.g. an Astro project with all deps pre installed), create a template: This creates: blaxel.toml , Dockerfile , entrypoint.sh , Makefile . Customize the Dockerfile. Always include the sandbox api binary: The entrypoint.sh must start the sandbox api: Deploy the template: Then retrieve the IMAGE ID and use it to create sandboxes: Tutorials and Examples Sandboxes Astro: https://docs.blaxel.ai/Tutorials/Astro Expo: https://docs.blaxel.ai/Tutorials/Expo Next.js: https://docs.blaxel.ai/Tutorials/Nextjs Agents Overview: https://docs.blaxel.ai/Tutorials/Agents Overview Core CLI commands For CLI commands that may prompt for input (like confirmations), add y to auto confirm when running in non interactive / no TTY environments (e.g. scripts, CI, agents). Command Purpose bl login Authenticate to workspace bl new sandbox\ agent\ job\ mcp NAME Initialize new resource from template bl deploy Build and deploy resource to Blaxel bl deploy d DIR Deploy from a specific directory bl serve Run resource locally for testing bl serve hotreload Run locally with hot reload bl get sandboxes\ agents\ jobs\ functions List resources bl get sandbox NAME watch Watch a sandbox deployment status bl delete sandbox\ agent\ job\ function NAME Remove resource bl connect sandbox NAME Open interactive terminal in sandbox bl chat AGENT NAME Interactive chat with deployed agent bl run job NAME data JSON Execute a deployed batch job blaxel.toml structure Important gotchas Ports must be declared at sandbox creation time — they cannot be added later Ports 80, 443, 8080 are reserved by Blaxel Dev servers must bind to 0.0.0.0 , not localhost , for preview URLs to work ~50% of sandbox memory is reserved for the in memory filesystem (tmpfs). Use volumes for extra storage Sandboxes auto scale to zero after ~5s of inactivity. State is preserved in standby and resumes in <25ms Deleted sandboxes stay visible in TERMINATED state for a few minutes (for log access). A plain get can return one; use createIfNotExists or check sandbox.status before reuse Process timeout is in seconds (default 600). It bounds waitForCompletion : when exceeded, the call throws a timeout error (HTTP 422) but the process keeps running — re attach with process.get / process.wait instead of assuming it failed. With keepAlive it auto kills the process after the timeout (0 = no auto kill). Ordinary long running processes (e.g. dev servers started with waitForPorts ) are not auto killed by it waitForCompletion holds the HTTP request open while the process runs (and is capped at ~58s over the sandbox MCP server). For long processes, start without it and block with process.wait(name, { maxWait }) instead process.exec also accepts env (per process environment variables), restartOnFailure , and maxRestarts Every process stdout/stderr line is exported as telemetry by default — heavy log volume causes real CPU contention. See "Disable process log export" below Secrets should never go in [env] — use the Variables and secrets page in the Console Sandbox best practices Full reference: https://docs.blaxel.ai/Sandboxes/best practices Bulk file upload: zip + writeBinary + unzip Never write many files with one fs.write per file — each call is a network round trip (~100ms), so a few hundred files takes minutes. Bundle them into a zip, upload it with one writeBinary call, and unzip inside the sandbox: 2 calls instead of N. For a handful of files, fs.writeTree (one batched call) is enough. If unzip is missing from your sandbox image, extract with python3 m zipfile e /tmp/project.zip /app/project instead, or install unzip in your template image. Persist project state across sandbox recreations Do not re clone a repo and re run npm install on every cold boot. The sandbox filesystem is erased on deletion (TTL expiry or explicit delete), but you have durable options: Volumes: durable block storage attached at sandbox creation ( volumes: [{ name, mountPath }] ). Put the project workspace and dependency cache on a volume; recreation re attaches it and skips the re pull. See ./references for full examples. Agent Drive: shared filesystem mountable into running sandboxes (private preview). Good for state shared across several sandboxes. Template images: bake heavy dependencies into a custom sandbox image so cold boots start pre installed. Also remember: idle sandboxes go to standby (free, resumes in <25ms) — prefer letting a sandbox idle with a TTL over deleting and rebuilding it on every session. Disable process log export By default every stdout/stderr line from sandbox processes is exported as structured telemetry. A chatty process (verbose dev server, trace level poller) can emit thousands of lines per minute, and that export load is a known cause of CPU contention inside the sandbox. Two ways to turn it off: Per sandbox: set the env var SANDBOX DISABLE PROCESS LOGGING=true on the sandbox (e.g. ENV SANDBOX DISABLE PROCESS LOGGING=true in your template Dockerfile, or in the sandbox env at creation). Workspace wide: an admin can disable process logging for all sandboxes in Console Workspace settings. You lose the process logs in the Blaxel Console; reading logs through the SDK/API ( process.get , log streaming) still works. Common antipatterns to flag when reviewing integrations Antipattern Symptom Fix get then create instead of createIfNotExists workload not found on gateway/preview URL after a delete + quick recreate (sandbox returned in TERMINATED state) createIfNotExists , or check sandbox.status after get Re pulling repo + reinstalling deps on every cold boot minutes of startup on every session volume or Agent Drive for the workspace; template image for deps One fs.write per file for many files restore takes minutes (N network round trips) zip + writeBinary + unzip (2 calls); writeTree for small sets Verbose stdout with log export left on CPU spikes during compiles/heavy output SANDBOX DISABLE PROCESS LOGGING=true or workspace toggle; also lower app verbosity Deleting sandboxes on idle cold rebuild on every return visit let standby handle idleness; use ttl for cleanup Agent Drive (shared filesystem) Agent Drive is a distributed filesystem backed by SeaweedFS that can be mounted to multiple sandboxes or agents at any time, including while they are already running. Unlike volumes (block storage attached only at sandbox creation), drives support concurrent read write access from multiple sandboxes and can be attached/detached dynamically. This feature is currently in private preview. During the preview, Agent Drive is only available in the us was 1 region. Both drive and sandbox must be in this region. Use cases: Passing data between sandboxes without intermediary services Storing tool outputs and context histories for other agents Sharing datasets across multiple agents Creating a shared filesystem cache of package dependencies Create a drive Mount a drive to a sandbox Once mounted, any file written to the mount path inside the sandbox is stored on the drive and persists even after the sandbox is deleted. Mount a subdirectory List, unmount, and delete drives CLI: bl get drives Full Agent Drive example Docs: https://docs.blaxel.ai/Agent drive/Overview Other Blaxel resources Agents Hosting Deploy AI agents as serverless auto scaling HTTP endpoints. Framework agnostic (LangChain, CrewAI, Claude SDK, etc.). Sync endpoint handles requests up to 100s, async endpoint up to 10 minutes. Docs: https://docs.blaxel.ai/Agents/Overview MCP Servers Hosting Deploy custom tool servers following the MCP protocol. Agents connect to deployed MCP servers via SDK: Every sandbox also exposes its own built in MCP server at https://<SANDBOX URL /mcp with tools for process management, filesystem, and code generation. Docs: https://docs.blaxel.ai/Functions/Overview Batch Jobs Scalable compute for parallel background tasks (minutes to hours). Max 24h per task. Set maxConcurrentTasks in blaxel.toml. Docs: https://docs.blaxel.ai/Jobs/Overview Resources Deployment configuration reference: https://docs.blaxel.ai/deployment reference CLI command reference: https://docs.blaxel.ai/cli reference/introduction Read individual SDK files for detailed explanations and code examples: ./references/sdk python.md ./references/sdk typescript.md Each SDK README contains: An overview of the SDK Requirements Code examples for working with sandboxes, volumes, agents, batch job

blaxel-sdk