mirror of
https://github.com/harivansh-afk/sandbox-agent.git
synced 2026-04-15 11:02:20 +00:00
155 lines
4.7 KiB
Text
155 lines
4.7 KiB
Text
---
|
||
title: "Foundry Self-Hosting"
|
||
description: "Environment, credentials, and deployment setup for Sandbox Agent Foundry auth, GitHub, and billing."
|
||
---
|
||
|
||
This guide documents the deployment contract for the Foundry product surface: app auth, GitHub onboarding, repository import, and billing.
|
||
|
||
It also covers the local-development bootstrap that uses `.env.development` only when `NODE_ENV=development`.
|
||
|
||
## Local Development
|
||
|
||
For backend local development, the Foundry backend now supports a development-only dotenv bootstrap:
|
||
|
||
- It loads `.env.development.local` and `.env.development`
|
||
- It does this **only** when `NODE_ENV=development`
|
||
- It does **not** load dotenv files in production
|
||
|
||
The example file lives at [`/.env.development.example`](https://github.com/rivet-dev/sandbox-agent/blob/main/.env.development.example).
|
||
|
||
To use it locally:
|
||
|
||
```bash
|
||
cp .env.development.example .env.development
|
||
```
|
||
|
||
Run the backend with:
|
||
|
||
```bash
|
||
just foundry-backend-start
|
||
```
|
||
|
||
That recipe sets `NODE_ENV=development`, which enables the dotenv loader.
|
||
|
||
### Local Defaults
|
||
|
||
These values can be safely defaulted for local development:
|
||
|
||
- `APP_URL=http://localhost:4173`
|
||
- `BETTER_AUTH_URL=http://localhost:7741`
|
||
- `BETTER_AUTH_SECRET=sandbox-agent-foundry-development-only-change-me`
|
||
- `GITHUB_REDIRECT_URI=http://localhost:7741/v1/auth/callback/github`
|
||
|
||
These should be treated as development-only values.
|
||
|
||
## Production Environment
|
||
|
||
For production or self-hosting, set these as real environment variables in your deployment platform. Do not rely on dotenv file loading.
|
||
|
||
### App/Auth
|
||
|
||
| Variable | Required | Notes |
|
||
|---|---:|---|
|
||
| `APP_URL` | Yes | Public frontend origin |
|
||
| `BETTER_AUTH_URL` | Yes | Public auth base URL |
|
||
| `BETTER_AUTH_SECRET` | Yes | Strong random secret for auth/session signing |
|
||
|
||
### GitHub OAuth
|
||
|
||
| Variable | Required | Notes |
|
||
|---|---:|---|
|
||
| `GITHUB_CLIENT_ID` | Yes | GitHub OAuth app client id |
|
||
| `GITHUB_CLIENT_SECRET` | Yes | GitHub OAuth app client secret |
|
||
| `GITHUB_REDIRECT_URI` | Yes | GitHub OAuth callback URL |
|
||
|
||
Use GitHub OAuth for:
|
||
|
||
- user sign-in
|
||
- user identity
|
||
- org selection
|
||
- access to the signed-in user’s GitHub context
|
||
|
||
## GitHub App
|
||
|
||
If your Foundry deployment uses GitHub App-backed organization install and repo import, also configure:
|
||
|
||
| Variable | Required | Notes |
|
||
|---|---:|---|
|
||
| `GITHUB_APP_ID` | Yes | GitHub App id |
|
||
| `GITHUB_APP_CLIENT_ID` | Yes | GitHub App client id |
|
||
| `GITHUB_APP_CLIENT_SECRET` | Yes | GitHub App client secret |
|
||
| `GITHUB_APP_PRIVATE_KEY` | Yes | PEM private key for installation auth |
|
||
|
||
For `.env.development` and `.env.development.local`, store `GITHUB_APP_PRIVATE_KEY` as a quoted single-line value with `\n` escapes instead of raw multi-line PEM text.
|
||
|
||
Recommended GitHub App permissions:
|
||
|
||
- Repository `Metadata: Read`
|
||
- Repository `Contents: Read & Write`
|
||
- Repository `Pull requests: Read & Write`
|
||
- Repository `Checks: Read`
|
||
- Repository `Commit statuses: Read`
|
||
|
||
Set the webhook URL to `https://<your-backend-host>/v1/webhooks/github` and generate a webhook secret. Store the secret as `GITHUB_WEBHOOK_SECRET`.
|
||
|
||
This is required, not optional. Foundry depends on GitHub App webhook delivery for installation lifecycle changes, repo access changes, and ongoing repo / pull request sync. If the GitHub App is not installed for the workspace, or webhook delivery is misconfigured, Foundry will remain in an install / reconnect state and core GitHub-backed functionality will not work correctly.
|
||
|
||
Recommended webhook subscriptions:
|
||
|
||
- `installation`
|
||
- `installation_repositories`
|
||
- `pull_request`
|
||
- `pull_request_review`
|
||
- `pull_request_review_comment`
|
||
- `push`
|
||
- `create`
|
||
- `delete`
|
||
- `check_suite`
|
||
- `check_run`
|
||
- `status`
|
||
|
||
Use the GitHub App for:
|
||
|
||
- installation/reconnect state
|
||
- org repo import
|
||
- repository sync
|
||
- PR creation and updates
|
||
|
||
Use GitHub OAuth for:
|
||
|
||
- who the user is
|
||
- which orgs they can choose
|
||
|
||
## Stripe
|
||
|
||
For live billing, configure:
|
||
|
||
| Variable | Required | Notes |
|
||
|---|---:|---|
|
||
| `STRIPE_SECRET_KEY` | Yes | Server-side Stripe secret key |
|
||
| `STRIPE_PUBLISHABLE_KEY` | Yes | Client-side Stripe publishable key |
|
||
| `STRIPE_WEBHOOK_SECRET` | Yes | Signing secret for billing webhooks |
|
||
| `STRIPE_PRICE_TEAM` | Yes | Stripe price id for the Team plan checkout session |
|
||
|
||
Stripe should own:
|
||
|
||
- hosted checkout
|
||
- billing portal
|
||
- subscription status
|
||
- invoice history
|
||
- webhook-driven state sync
|
||
|
||
## Mock Invariant
|
||
|
||
Foundry’s mock client path should continue to work end to end even when the real auth/GitHub/Stripe path exists.
|
||
|
||
That includes:
|
||
|
||
- sign-in
|
||
- org selection/import
|
||
- settings
|
||
- billing UI
|
||
- workspace/task/session flow
|
||
- seat accrual
|
||
|
||
Use mock mode for deterministic UI review and local product development. Use the real env-backed path for integration and self-hosting.
|