API

The BLAST API is a small set of operations over VMs: fork one, run commands inside it, sync files in and out, and manage sessions. It's a plain REST API served directly by the blast binary, with no separate CLI, web console, or client SDK.

Get started

Call the API against the port BLAST is listening on (7240 by default):

bash

curl -X POST localhost:7240/v1/fork \
  -H "Content-Type: application/json" \
  -d '{"image":"ubuntu:24.04"}'

Operations

POST/v1/forkfork a VM

GET/v1/vmslist VMs

GET/v1/vms/{id}get a VM

DELETE/v1/vms/{id}delete a VM

POST/v1/vms/{id}/runsrun a command

GET/v1/vms/{id}/runs/{run_id}poll a run

GET/v1/vms/{id}/sessionslist sessions

POST/v1/vms/{id}/sessionscreate a session

DELETE/v1/vms/{id}/sessions/{sid}delete a session

POST/v1/vms/{id}/syncread or write files

Authentication

BLAST's HTTP API has no built-in authentication. Run it behind your own network boundary (localhost, a private network, or a reverse proxy) if you need to restrict who can call it. The api_key under [worker] in blast.toml is used outbound only, to authenticate BLAST to a control plane it registers with; it is not checked on inbound requests to BLAST's own API.

Errors

An error response carries the HTTP status and a JSON body:

json

{
  "code": 404,
  "message": "VM not found: vm_abc123"
}

code mirrors the HTTP status; message is human-readable.