Skip to main content
Modal is a hosted sandbox provider for running task sandboxes away from the Roomote server. It is a good fit when you want provider-managed sandbox infrastructure, better isolation from the app host, and snapshot-capable resume flows.

​
When to use Modal

Use Modal when:
  • several people may run tasks at the same time
  • task work should not consume CPU or memory on the Roomote host
  • you want hosted sandboxes with snapshot support
  • you can provide Modal credentials and a worker image Modal can pull

​
Configuration

Add Modal from Settings > Sandboxes, or provide the values as deployment env vars: 
MODAL_TOKEN_ID=...
MODAL_TOKEN_SECRET=...
Modal also needs a base image. Roomote usually derives MODAL_BASE_IMAGE_REF from the shared worker image (DOCKER_WORKER_IMAGE or the derived release image): 
DOCKER_WORKER_IMAGE=ghcr.io/roocodeinc/roomote-worker:<version>
Set MODAL_BASE_IMAGE_REF only when you need to pin a custom Modal base image: 
MODAL_BASE_IMAGE_REF=ghcr.io/roocodeinc/roomote-worker:<version>
Optional values: 
MODAL_ENDPOINT=...
MODAL_ENVIRONMENT=...
MODAL_APP_NAME=...
MODAL_REGISTRY_USERNAME=...
MODAL_REGISTRY_PASSWORD=...
MODAL_ECR_OIDC_ROLE_ARN=...
MODAL_ECR_REGION=...
# Optional sandbox placement; also available as Advanced infrastructure in
# Settings > Sandboxes. Comma-separated Modal regions, for example us or us-west.
MODAL_REGIONS=us
Use the registry variables when Modal must pull from a private registry. For production, prefer immutable image tags such as a release or commit tag. MODAL_REGIONS is an optional comma-separated list of Modal container placement regions (for example us, us-west, or us,eu). When unset, Modal chooses placement. Prefer broader tokens such as us for capacity and cold-start behavior. Pinning a region can add a Modal pricing multiplier and only applies to newly created or resumed sandboxes, not sandboxes that are already running. Do not confuse MODAL_REGIONS with MODAL_ECR_REGION, which only controls AWS ECR image pulls.

​
Worker image expectations

Hosted providers cannot use a local-only image tag such as roomote-worker:local. The worker image must be registry-qualified and reachable by Modal. If Modal cannot pull the image, tasks will fail before the worker runtime starts.

​
Verify setup

  1. save Modal credentials and a registry-qualified worker image
  2. select Modal as the default sandbox provider
  3. start a small task from an environment
  4. confirm the task starts, streams logs, and can run project commands
  5. try resuming or following up on a task that can use a saved snapshot

​
Common issues

  • Modal cannot pull the worker image. Use a registry-qualified image and configure registry credentials or ECR OIDC settings when needed.
  • Tasks fail immediately after launch. Check MODAL_TOKEN_ID, MODAL_TOKEN_SECRET, and any Modal environment or endpoint overrides.
  • The wrong worker runtime starts. Pin DOCKER_WORKER_IMAGE or MODAL_BASE_IMAGE_REF to an immutable tag.