Configure
Last updated on November 20, 2026
Configuration lives in a single .env file that is generated on first run. To create it, SSH into your server and run the deploy command with the license key TofuPilot issued for your instance (copy it from Self-Hosting in Orbit):
curl -fsSL https://www.tofupilot.com/deploy | bash -s -- --license YOUR_LICENSE_KEYThe script writes a .env template into the current directory and exits. Open it with your editor of choice:
nano .envThe .env file also holds auto-generated secrets (AUTH_SECRET, DB_PASSWORD, S3_SECRET_ACCESS_KEY, STORAGE_FILER_JWT_KEY, the CENTRIFUGO_* keys, DEPLOYER_TOKEN, and SECRETS_MASTER_KEY). Do not delete or modify them. They are created on first deploy and reused on every re-run. SECRETS_MASTER_KEY encrypts every stored config value and secret: back it up with the database, since losing it makes them unreadable.
Wrap a value in single quotes when it contains spaces or special characters, for example EMAIL_SMTP_PASSWORD='p@ss w0rd`$'. Inside single quotes, write a single quote as \'. Values are literal, so a ${VAR} reference is not expanded. The deploy script rewrites every value in quotes on each run, which is expected.
Domains
TofuPilot needs three subdomains. Create a DNS A record for each pointing to your server, then set them in .env:
DOMAIN_NAMEfor the application (e.g.tofupilot.yourcompany.com).STORAGE_DOMAIN_NAMEfor file storage (e.g.storage.tofupilot.yourcompany.com).CENTRIFUGO_DOMAIN_NAMEfor realtime updates over WebSocket (e.g.realtime.tofupilot.yourcompany.com). Defaults torealtime.<DOMAIN_NAME>if unset.
Realtime features (live station status and telemetry, dashboard updates, and streaming build logs) need the CENTRIFUGO_DOMAIN_NAME record and its TLS certificate. Without it the app still works, but those views fall back to manual refresh.
SSL certificates
HTTPS is handled by Let's Encrypt by default. To enable it, set your email:
SSL_MODE=letsencryptSSL_LETSENCRYPT_EMAIL=admin@yourcompany.comIf you use your own certificate authority, switch to custom mode and provide absolute paths on the host:
SSL_MODE=customSSL_CERT_PATH=/etc/ssl/tofupilot/fullchain.pemSSL_KEY_PATH=/etc/ssl/tofupilot/privkey.pemAuthentication
You need at least one sign-in method. TofuPilot supports email magic links and several OAuth providers, and you can enable as many as you want.
When you skip email, users sign in only through OAuth, which means no invitations or notifications.
Email (magic link)
The email method sends a one-time code by email and drives invitations and notifications.
EMAIL_SMTP_HOST=smtp.yourcompany.comEMAIL_SMTP_PORT=587EMAIL_SMTP_USER=noreply@yourcompany.comEMAIL_SMTP_PASSWORD=your-smtp-passwordEMAIL_FROM_AUTH=noreply@yourcompany.comCreate an OAuth app in the Google Cloud Console and set the redirect URI to:
https://tofupilot.yourcompany.com/api/auth/callback/googleCopy the Client ID and Client Secret into .env:
AUTH_GOOGLE_ID=your-client-idAUTH_GOOGLE_SECRET=your-client-secretMicrosoft Entra ID
Register an app in the Azure Portal under App registrations and set the redirect URI to:
https://tofupilot.yourcompany.com/api/auth/callback/microsoftCopy the Application (client) ID and Secret into .env:
AUTH_MICROSOFT_ENTRA_ID_ID=your-client-idAUTH_MICROSOFT_ENTRA_ID_SECRET=your-client-secretAUTH_MICROSOFT_ENTRA_ID_ISSUER=https://login.microsoftonline.com/your-tenant-id/v2.0Replace your-tenant-id with your Azure AD tenant ID. For Azure Government, use login.microsoftonline.us.
GitHub
Create an OAuth app in GitHub Developer Settings and set the callback URL to:
https://tofupilot.yourcompany.com/api/auth/callback/githubCopy the Client ID and Client Secret into .env:
AUTH_GITHUB_ID=your-client-idAUTH_GITHUB_SECRET=your-client-secretGitLab
Create an application in GitLab (or your self-hosted GitLab instance) with the read_user and openid scopes, and set the redirect URI to:
https://tofupilot.yourcompany.com/api/auth/callback/gitlabCopy the Application ID and Secret into .env:
AUTH_GITLAB_ID=your-application-idAUTH_GITLAB_SECRET=your-application-secretAUTH_GITLAB_ISSUER=https://gitlab.comFor self-hosted GitLab, replace https://gitlab.com with your instance URL.
Atlassian
Create an OAuth 2.0 (3LO) app in the Atlassian developer console, enable the User identity API with the read:me scope, and set the callback URL to:
https://tofupilot.yourcompany.com/api/auth/callback/atlassianCopy the Client ID and Secret into .env:
AUTH_ATLASSIAN_ID=your-client-idAUTH_ATLASSIAN_SECRET=your-client-secretIdentity provider on a private network
SSO refuses an identity provider that resolves to a private address (RFC 1918, loopback, link-local), so a registration cannot be used to reach internal services. When your IdP runs on your own network, list its origin in .env, comma-separated for several:
BETTER_AUTH_TRUSTED_ORIGINS=https://idp.internal.yourcompany.comA trusted origin is also a valid sign-in redirect target and may send signed-in requests, so list only hosts you control. An IdP registered before version 2.44.10 needs the same entry: until it is listed, its sign-ins fail.
The same setting covers any other address users open TofuPilot at. Sign-in and every signed-in change are accepted only from https://DOMAIN_NAME and the origins listed here, so add an internal hostname or IP address users browse to.
Git provider
TofuPilot can connect to GitHub, GitLab, or Bitbucket Data Center so you can drive automatic Deployments from your CI/CD pipelines.
GitHub
Self-hosted instances need their own GitHub App.
Step 1. Go to your GitHub organization Settings > Developer Settings > GitHub Apps > New GitHub App and fill in:
| Field | Value |
|---|---|
| App name | tofupilot-yourcompany (must be globally unique on GitHub) |
| Homepage URL | https://DOMAIN_NAME |
Step 2. In Identifying and authorizing users:
- Callback URL:
https://DOMAIN_NAME/api/github/setup - Request user authorization (OAuth) during installation: checked. TofuPilot uses it to confirm that the person connecting an installation can access it on GitHub.
- Expire user authorization tokens: checked. TofuPilot uses the authorization once and revokes it, so GitHub asks the user to authorize again on every connect; expiry covers a failed revocation.
Step 3. Fill in the remaining sections:
- Post installation: nothing to set. GitHub disables the Setup URL once OAuth during installation is checked, and redirects to the Callback URL instead.
- Webhook
- Active: checked
- Webhook URL:
https://DOMAIN_NAME/api/webhooks/github - Secret: a random string (e.g. run
openssl rand -hex 32in your terminal)
- Repository permissions
- Contents: Read-only (clone repositories and read commits)
- Administration: Read and write (required to create a repository from a template)
- Metadata: Read-only (automatically selected)
- Pull requests: Read-only
- Organization permissions
- Members: Read-only (confirms that the person connecting an organization's installation is an owner of that organization)
- Account permissions: none
- Subscribe to events
- Delete, Pull request, Push, Repository
- Install target
- Only on this account
Administration: Read and write is required for cloning starter templates. Without it, creating a procedure from a template fails with a 403.
Step 4. Click Create GitHub App. GitHub may redirect you to your instance's sign-in page afterward. That is expected: the App is already created. On the App's General page, note the App ID and the Client ID, then click Generate a new client secret and copy it.
Make sure Push is checked under Subscribe to events (Step 3). Without it GitHub won't notify your instance of new commits and auto-deploy won't trigger.
Step 5. Scroll to Private keys, click Generate a private key, and base64-encode the downloaded file:
base64 -w 0 < downloaded_file.pembase64 -i downloaded_file.pem[Convert]::ToBase64String([IO.File]::ReadAllBytes("downloaded_file.pem"))Step 6. Add these variables to .env:
GITHUB_APP_ID=your-app-idGITHUB_APP_PRIVATE_KEY=your-base64-encoded-private-keyGITHUB_APP_WEBHOOK_SECRET=your-webhook-secretGITHUB_APP_SLUG=tofupilot-yourcompanyGITHUB_APP_CLIENT_ID=your-client-idGITHUB_APP_CLIENT_SECRET=your-client-secretGITHUB_APP_IDcomes from Step 4 (App's General page).GITHUB_APP_PRIVATE_KEYcomes from Step 5 (base64-encoded output).GITHUB_APP_WEBHOOK_SECRETcomes from Step 3 (webhook secret).GITHUB_APP_SLUGis the last segment of your App URL:https://github.com/apps/{slug}.GITHUB_APP_CLIENT_IDandGITHUB_APP_CLIENT_SECRETcome from Step 4. Without them, Connect in Settings > GitHub stops withnot_configuredbefore GitHub opens.
Step 7. After deploying, go to Settings > GitHub in your dashboard to install the App and select repositories.
GitLab
GitLab needs no extra environment variables. Go to Settings > GitLab in your dashboard and click Connect to add your GitLab access token, instance URL, and select a group.
Bitbucket
Bitbucket Data Center needs no extra environment variables. Go to Settings > Bitbucket in your dashboard and click Connect to add your instance URL and a project-scoped HTTP access token with Project admin permission, then select a project. Bitbucket Cloud (bitbucket.org) is not supported yet.
Deployments
The deployments pipeline builds procedure bundles from your Git repository and serves them to stations. It runs automatically on self-hosted installs, no extra .env configuration is required:
- The
tofupilot-deployercontainer builds bundles in an isolated Docker-in-Docker sandbox. - Artifacts are stored in a dedicated bucket on the bundled object storage; the dashboard mints short-lived presigned links for stations to download them.
DEPLOYER_TOKENand theARTIFACT_*settings are generated and wired automatically.
The deployer needs a privileged container to run its build sandbox (its own Docker-in-Docker daemon — it does not mount the host Docker socket). It will not start under rootless Docker; the rest of the stack is unaffected. Use a standard (root) Docker installation if you need the build pipeline. Because builds execute your procedure code inside this privileged worker, run self-hosted on a host you control and treat the build worker as part of your trust boundary.
To deploy automatically when you push to a branch, configure the GitHub App above. The push webhook triggers a build for procedures with auto-deploy enabled. Manual deploys from the dashboard work without it.
File storage
The bundled object storage (SeaweedFS) holds attachments, uploaded files, images and deployment bundles, in two buckets: tofupilot and tofupilot-artifacts. It is reachable on STORAGE_DOMAIN_NAME, and it accepts signed requests only:
- The dashboard and the deployer sign with the access key
tofupilotand the generatedS3_SECRET_ACCESS_KEYfrom.env. - Browsers, the CLI, stations and the SDKs receive presigned links from the API. A presigned link expires: after 1 hour for attachments, files and bundles, and after 7 days for avatars and images. To download a file later, ask the API for a fresh link (for example
POST /v2/attachments/{id}/finalize, or thedownload_urlof a run's attachments) instead of storing the link. - A request without a valid signature is refused with
403.
Storage authentication turns on by itself at the first deploy of a dashboard release that supports it. On that deploy, the script moves the storage from SeaweedFS 3.80 to SeaweedFS 4.54 on the same data volume: existing files stay where they are and remain readable. Storage is unavailable for a few seconds while SeaweedFS 4 starts. From then on, the install stays on SeaweedFS 4 (.env records it in TOFUPILOT_STORAGE_VERSION); it does not go back to 3.80. Until a supporting dashboard release is deployed, the script prints a warning and storage accepts unsigned requests, as before.
Once on, storage authentication cannot be turned off.
SeaweedFS 4 runs with its usage statistics turned off (-master.telemetry=false): the storage sends nothing outside your server.
Access the storage yourself
To back up, inspect or copy files with your own tools, sign with the same key. For example, with the AWS CLI on the server. The last variable stops recent versions of the AWS CLI from adding checksums to uploads, which the bundled storage does not accept:
export AWS_ACCESS_KEY_ID=tofupilotexport AWS_SECRET_ACCESS_KEY="$(docker exec tofupilot-dashboard printenv S3_SECRET_ACCESS_KEY)"export AWS_REQUEST_CHECKSUM_CALCULATION=when_requiredaws --endpoint-url "https://storage.tofupilot.yourcompany.com" s3 ls s3://tofupilot/Tools that read the storage without credentials (aws s3 --no-sign-request, anonymous rclone remotes, plain curl on object URLs) stop working when authentication turns on.
To add a separate key, for example a read-only key for a backup job, use SeaweedFS's s3.configure command; it adds the key next to the install's own. Do not change or remove the tofupilot key: the dashboard and the deployer use it.
docker exec tofupilot-seaweed sh -c "echo \"s3.configure -user=backup -access_key=BACKUP_KEY -secret_key=BACKUP_SECRET -actions=Read,List -apply\" | weed shell"If you put your own reverse proxy in front of the storage host, it must forward the Host header unchanged: the signature of every request covers it.
Inside the install, SeaweedFS 4 binds its administrative listeners (filer, master, volume server) to the storage container's loopback interface, so they are not reachable from the other containers on the install's Docker network: only the S3 gateway on port 8333 is, and it always requires signed requests. None of these ports is published on the host or routed by the reverse proxy. The S3 gateway's own gRPC port stays on the Docker network; SeaweedFS refuses its administrative calls unless they carry a token signed with the generated STORAGE_FILER_JWT_KEY, so a container sharing the network cannot use it to bypass signing. That key is what guards this port: keep it as private as S3_SECRET_ACCESS_KEY. Unlike the other secrets, it can be lost or replaced without harm: nothing stored depends on it, and the next deploy generates a new one if it is missing. Adding gRPC mutual TLS as a second layer is planned.
An install still on SeaweedFS 3.80 (no dashboard release with storage authentication deployed yet) keeps the previous layout: its internal ports are reachable by the other containers on the install's Docker network and accept requests without credentials.
How is this guide?