Skip to main content
Modal is a hosted compute 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 > Compute, 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 configured in Settings > Compute or DOCKER_WORKER_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=...
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.

​
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 compute 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.