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_KEY

The script writes a .env template into the current directory and exits. Open it with your editor of choice:

nano .env

The .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_NAME for the application (e.g. tofupilot.yourcompany.com).
  • STORAGE_DOMAIN_NAME for file storage (e.g. storage.tofupilot.yourcompany.com).
  • CENTRIFUGO_DOMAIN_NAME for realtime updates over WebSocket (e.g. realtime.tofupilot.yourcompany.com). Defaults to realtime.<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.com

If 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.pem

Authentication

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.

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.com

Google

Create an OAuth app in the Google Cloud Console and set the redirect URI to:

https://tofupilot.yourcompany.com/api/auth/callback/google

Copy the Client ID and Client Secret into .env:

AUTH_GOOGLE_ID=your-client-idAUTH_GOOGLE_SECRET=your-client-secret

Microsoft 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/microsoft

Copy 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.0

Replace 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/github

Copy the Client ID and Client Secret into .env:

AUTH_GITHUB_ID=your-client-idAUTH_GITHUB_SECRET=your-client-secret

GitLab

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/gitlab

Copy the Application ID and Secret into .env:

AUTH_GITLAB_ID=your-application-idAUTH_GITLAB_SECRET=your-application-secretAUTH_GITLAB_ISSUER=https://gitlab.com

For 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/atlassian

Copy the Client ID and Secret into .env:

AUTH_ATLASSIAN_ID=your-client-idAUTH_ATLASSIAN_SECRET=your-client-secret

Identity 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.com

A 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:

FieldValue
App nametofupilot-yourcompany (must be globally unique on GitHub)
Homepage URLhttps://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 32 in 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.pem
base64 -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-secret
  • GITHUB_APP_ID comes from Step 4 (App's General page).
  • GITHUB_APP_PRIVATE_KEY comes from Step 5 (base64-encoded output).
  • GITHUB_APP_WEBHOOK_SECRET comes from Step 3 (webhook secret).
  • GITHUB_APP_SLUG is the last segment of your App URL: https://github.com/apps/{slug}.
  • GITHUB_APP_CLIENT_ID and GITHUB_APP_CLIENT_SECRET come from Step 4. Without them, Connect in Settings > GitHub stops with not_configured before 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-deployer container 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_TOKEN and the ARTIFACT_* 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 tofupilot and the generated S3_SECRET_ACCESS_KEY from .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 the download_url of 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?

On this page