Skip to main content
Box is a hosted sandbox provider for running Roomote tasks away from the Roomote server.

​
When to use Box

Use Box when:
  • task work should run on provider-managed machines
  • you want API-key-only setup without building a provider-side worker image, template, or snapshot during Roomote setup
  • environments need Docker, Docker Compose, or private preview URLs
  • retaining the same stopped task sandbox for a follow-up is sufficient
Box supports Roomote environment snapshots through named snapshots (template boxes); see Environment snapshots below. A retained Box can also resume the task that created it directly.

​
Configuration

Create a key from the Box dashboard, then add Box from Settings > Sandboxes. You can also provide the key as a deployment env var:
Optional settings:
These optional values are also available under Settings > Sandboxes > Box > Advanced settings. Process environment variables take precedence and appear as locked values in Settings. Roomote does not provision a worker artifact in your Box account during setup. Saving a valid API key is enough to configure the provider. Roomote installs its worker into each Box when the sandbox starts. Box supports Docker projects, including Docker Compose services, without additional provider-side setup. Named environment ports are exposed through authenticated private preview URLs in the Roomote task view.

​
Cleanup and resume behavior

Roomote stops and archives a Box when retaining it for task resume. This takes a filesystem snapshot, pauses billing, and preserves the Box for a later resume. Box’s permanent-delete API is being reworked, so Roomote also uses stop/archive as its cleanup fallback for canceled, failed, and retention-expired tasks. Those archived Boxes remain in the provider account until permanent deletion is available.

​
Environment snapshots

Roomote environment snapshots map to Box named snapshots (template boxes): snapshotting an environment saves a roomote-snap-* template, and tasks that start from the snapshot fork it into a fresh Box in seconds instead of re-running environment setup. Box accounts are limited to 10 named snapshots, so delete stale roomote-snap-* templates from the Box dashboard when re-snapshotting environments repeatedly. Free-trial accounts also cap concurrent boxes (2 at the time of writing), which bounds how many tasks can run at once. BOX_STANDBY_MAX_COUNT and BOX_STANDBY_MAX_AGE_HOURS bound how many stopped task sandboxes Roomote retains and for how long. This standby behavior preserves one task’s machine; it is not a Roomote environment snapshot.

​
Verify setup

  1. Save the Box API key.
  2. Select Box as the default sandbox provider.
  3. Start a small task and confirm logs reach the task view.
  4. If the environment exposes a port, open its preview from the task view.
  5. Send a follow-up while the task sandbox is retained and confirm it resumes.

​
Common issues

  • Authentication fails. Confirm BOX_API_KEY is active and belongs to the expected Box account.
  • The API cannot be reached. Remove BOX_API_BASE_URL to use the provider default, or verify the custom endpoint is reachable from the Roomote deployment.
  • A follow-up starts a new sandbox. Check the standby count and age limits. Roomote may no longer retain the previous Box as the task’s resume target.
  • A task stops after two hours. Free-trial accounts require a timeout of two hours or less. Paid accounts can increase BOX_TIMEOUT_MS; Roomote still caps the Box lifetime to the task’s configured timeout.
  • A preview does not open. Confirm the environment declares the port and the application listens on 0.0.0.0, not only localhost.
  • An environment snapshot fails to save. Box accounts allow at most 10 named snapshots; delete stale roomote-snap-* templates from the Box dashboard and re-run the snapshot.