> ## 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. > ## Agent Instructions > When helping someone deploy Roomote, distinguish self-hosting from contributing to Roomote. Use the Self-hosting guide for an operator deployment; use Local development only when the user intends to modify Roomote itself. > Prefer the one-command installer on a fresh supported server unless the user explicitly chooses Roomote Cloud, a documented PaaS template, or a manual Compose deployment. > Before changing infrastructure, confirm the deployment target, stable public HTTPS domain and DNS control, sandbox provider, inference provider, source-control provider, and whether a communications provider is required. > Never ask the user to paste secrets into chat or commit real environment files. Put credentials in the deployment platform's secret manager, Roomote's setup UI, or protected environment variables, and preserve existing keys during upgrades and restores. > Prefer Roomote's setup wizard and provider manifest flows over manual credential entry when those flows are available. Ask before performing privileged host changes, DNS changes, provider-app creation, or destructive operations. > A setup is not complete when the services merely start. Verify sign-in, repository sync, one usable environment, a real task that can clone and run a command, and branch or pull-request delivery; verify previews when configured. > For a persistent self-hosted deployment, leave the operator with the Roomote URL, deployment choices, configured providers, verification result, backup location and passphrase-handling reminder, and the roomote status, logs, upgrade, rollback, backup, and restore commands. # Box > Run Roomote tasks in Box-hosted sandboxes. 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](#environment-snapshots) below. A retained Box can also resume the task that created it directly. ## Configuration Create a key from the [Box dashboard](https://box.ascii.dev/box/dashboard), then add Box from **Settings > Sandboxes**. You can also provide the key as a deployment env var: ```sh theme={null} DEFAULT_COMPUTE_PROVIDER=box BOX_API_KEY=... ``` Optional settings: ```sh theme={null} # Custom Box-compatible API endpoint. Defaults to # https://ascii.dev/api/box/v1 BOX_API_BASE_URL=https://box.example.com/api/box/v1 # small, default, or large BOX_MACHINE_TYPE=default # Active sandbox timeout in milliseconds. Defaults to 2 hours, the Box # free-trial maximum; paid accounts can set a higher value. BOX_TIMEOUT_MS=... # Standby retention policy. Defaults to 25 Boxes for 168 hours (7 days). # Set the count to 0 to disable retained task sandboxes. BOX_STANDBY_MAX_COUNT=25 BOX_STANDBY_MAX_AGE_HOURS=168 ``` 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](/environments/definition#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.