Skip to main content
Modal is the default sandbox provider for self‑hosted Proliferate. You’ll deploy a small Modal app and add your credentials to .env.
Modal setup is required when DEFAULT_SANDBOX_PROVIDER=modal (the default).

​
What This Enables

  • Sandbox execution for coding agents
  • Filesystem snapshots and previews via Modal sandboxes

​
What You’ll Need

  • A Modal account
  • Modal API token (MODAL_TOKEN_ID, MODAL_TOKEN_SECRET)
  • An app name (MODAL_APP_NAME)

​
1) Deploy the Modal App

The codebase includes a minimal deploy script at packages/modal-sandbox/deploy.py.
1

Install the Modal CLI

Install the Modal CLI using the official Modal docs.
2

Deploy the app

From the repo root:
modal deploy packages/modal-sandbox/deploy.py
The provider expects a get_image_id endpoint exposed by this deploy script. If it’s missing, you’ll see an error telling you to redeploy that file.

​
2) Set Environment Variables

Add these to your .env file: 
MODAL_APP_NAME=proliferate-sandbox
MODAL_TOKEN_ID=...
MODAL_TOKEN_SECRET=...
Optional: 
# Add a suffix for per‑developer deployments
MODAL_APP_SUFFIX=pablo

# Only used in tests (not required in production)
MODAL_ENDPOINT_URL=...
If you set MODAL_APP_SUFFIX, the deployed app name becomes MODAL_APP_NAME-MODAL_APP_SUFFIX.

​
3) Restart Services

docker compose down
docker compose up -d

​
Troubleshooting

  • Ensure modal deploy packages/modal-sandbox/deploy.py completed successfully
  • Verify MODAL_APP_NAME matches the deployed app name
  • Confirm MODAL_TOKEN_ID and MODAL_TOKEN_SECRET are correct
  • Regenerate tokens in Modal if needed