> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roomote.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Blaxel

> Run Roomote tasks in Blaxel perpetual sandboxes.

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](https://app.blaxel.ai/profile/security),
then add Blaxel from **Settings > Sandboxes** or provide:

```sh theme={null}
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](https://docs.blaxel.ai/Sandboxes/Templates).
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:

```sh theme={null}
BLAXEL_REGION=us-pdx-1
```

Standby retention can be bounded separately from active task timeouts:

```sh theme={null}
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.