Cloud sandboxes

The base install works without this add-on. From day one, users can run workspaces on Linux machines you already own. Add cloud sandboxes when you want managed cloud workspaces that the Proliferate server creates and tears down for your organization.

Requirements

Everything on this list must be in place before the add-on works:

• A publicly reachable HTTPS URL. Sandboxes and GitHub call back into your server, so localhost installs can't use this add-on. If you followed the Docker guide, the SITE_ADDRESS you configured is already this URL.
• A GitHub App you create under your GitHub organization. It is what lets a sandbox clone your code and lets the server act on repositories on your team's behalf. Creation is manual today; a one-click flow is planned.
• An E2B account and API key. E2B is the cloud sandbox provider. Every sandbox runs inside your own E2B team and is billed to your account; nothing runs in a shared tenant.
• A sandbox template built in your own E2B team. E2B has no public templates, so every self-hosted install builds its own. The build takes a few minutes, and it must be repeated after each server update.

Work through the two setup pages in order. Each ends with the exact environment variables the server needs.

Enable and verify

When both pages are done, your env file (.env.static in the deploy bundle) has three new groups of values: the GITHUB_APP_* variables, E2B_API_KEY, and E2B_TEMPLATE_NAME. Apply them by running the update script from the deploy directory:

./update.sh

(./update.sh regenerates the runtime env from .env.static, pulls the pinned image, runs migrations, and restarts the stack. Rerunning ./bootstrap.sh applies env changes the same way.)

Then verify the whole path end to end:

1. In the desktop app, create a cloud workspace on a repository the GitHub App is installed on.
2. Confirm a sandbox appears in your E2B dashboard running your template.
3. Confirm the workspace clones the repository and starts an agent session.

If the workspace fails to start, check docker compose logs api for github_app_not_configured or E2B errors, and check the webhook delivery log on your GitHub App settings page for non-2xx responses.

Swappable by design