Skip to main content
Blaxel is a hosted sandbox provider. Roomote creates a sandbox from the worker image, installs the current worker release, exposes task ports through Blaxel preview URLs, and starts the task worker as a keep-alive process.

​
When to use Blaxel

Use Blaxel when task work should run outside the Roomote host and you want provider-managed microVMs with automatic standby and fast wake-up. Blaxel does not currently support Roomote environment snapshots, but resumable tasks retain their existing Blaxel sandbox on standby. Reusable snapshot-based environment workflows remain available with Modal, E2B, and Daytona.

​
Configuration

Create a key from the Blaxel API keys page, then add Blaxel from Settings > Sandboxes or provide: 
BL_API_KEY=...
BL_WORKSPACE=my-workspace
When you save the credentials, Roomote automatically imports the configured Roomote worker image and builds a Blaxel sandbox image. The build injects Blaxel’s sandbox API and saves the resulting immutable sandbox/name:version reference as BLAXEL_IMAGE. You may still provide BLAXEL_IMAGE through the process environment to use a prebuilt image. You can optionally select a region: 
BLAXEL_REGION=us-pdx-1
Standby retention can be bounded separately from active task timeouts: 
BLAXEL_STANDBY_MAX_COUNT=25
BLAXEL_STANDBY_MAX_AGE_HOURS=168
Region and standby retention are also editable under Settings > Sandboxes > Blaxel > Advanced settings. Process environment variables take precedence and appear as locked values in Settings.

​
Runtime behavior

  • Roomote requests a Blaxel TTL matching the task timeout.
  • Fresh sandbox provisioning uses a stable task identity and Blaxel’s idempotent create API so controller retries reconnect instead of creating duplicate sandboxes.
  • Each exposed port receives a public Blaxel preview URL. Roomote’s preview proxy remains the user-facing authentication layer. Existing preview resources are reused across standby resumes.
  • The detached worker process uses Blaxel keep-alive while the task is active.
  • When Blaxel reports WORKLOAD_UNAVAILABLE, Roomote retries workload access with bounded exponential backoff. Missing workloads, invalid routes, and application-origin errors are handled separately rather than retried as transient platform failures.
  • When a resumable task goes to sleep, Roomote stops its worker, extends the sandbox lifetime to the configured standby age (seven days by default), and lets Blaxel move the sandbox to standby. A follow-up reconnects to the same sandbox and launches a new worker without reinstalling the workspace.
  • Non-resumable workflows are still destroyed when their sleep deadline is reached. A five-minute retention sweep deletes standby sandboxes that exceed the configured count or age. A count of 0 disables Blaxel standby retention.
Blaxel standby is intentionally separate from Roomote environment snapshots. A standby handle reconnects to one mutable sandbox; it cannot be cloned or reused as a clean environment template.

​
Verify setup

  1. Save the API key and workspace name, then wait for image provisioning to finish.
  2. Select Blaxel as the default sandbox provider.
  3. Start a small task and confirm logs reach the task view.
  4. Start a web app and verify its preview link.

​
Common issues

  • Authentication fails. Confirm the API key belongs to BL_WORKSPACE.
  • The sandbox remains unavailable. Confirm BLAXEL_IMAGE is a Blaxel-built sandbox/name:version image, not a raw Docker registry reference.
  • A preview has no URL. Confirm the configured workspace can create public sandbox previews and that the requested ports are valid.