tabby-web/README.md

Tabby Web

Note on project status

Important

At this time I don't have the time to work on tabby-web and won't be able to provide help or support for it. I'm still happy to merge any fixes/improvement PRs. ✌️

This is the Tabby terminal, served as a web app. It also provides the config sync service for the Tabby app.

How it works

Tabby Web serves the Tabby Terminal as a web application while managing multiple config files, authentication, and providing TCP connections via a separate gateway service.

Requirements

Runtime Requirements

• Python 3.7+
• A database server supported by Django (MariaDB, Postgres, SQLite, etc.)
• Storage for distribution files - local, S3, GCS or others supported by fsspec

Docker Build Requirements

Building the Docker image requires significant resources due to the frontend compilation:

Resource	Minimum	Recommended
RAM	2 GB	4 GB
CPU	2 cores	4 cores
Disk	5 GB	10 GB

Note: The frontend build (webpack/Angular) is memory-intensive. If building on constrained systems (like Oracle Cloud Always Free tier with 1GB RAM), consider:

• Using pre-built images from a CI/CD pipeline
• Building on a larger machine and pushing to a registry
• Adding swap space (not recommended for production)

Quickstart (using docker-compose)

You'll need:

• OAuth credentials from GitHub, GitLab, Google or Microsoft for authentication.
• For SSH and Telnet: a tabby-connection-gateway to forward traffic.
• Docker BuildKit: export DOCKER_BUILDKIT=1

    docker-compose up -e SOCIAL_AUTH_GITHUB_KEY=xxx -e SOCIAL_AUTH_GITHUB_SECRET=yyy

will start Tabby Web on port 9090 with MariaDB as a storage backend.

For SSH and Telnet, once logged in, enter your connection gateway address and auth token in the settings.

Environment variables

• DATABASE_URL (required).
• APP_DIST_STORAGE: a file://, s3://, or gcs:// URL to store app distros in.

Authentication Providers

Only providers with credentials configured will appear as login options. Set the following environment variables for each provider you want to enable:

Provider	Environment Variables
GitHub	SOCIAL_AUTH_GITHUB_KEY, SOCIAL_AUTH_GITHUB_SECRET
GitLab	SOCIAL_AUTH_GITLAB_KEY, SOCIAL_AUTH_GITLAB_SECRET
Google	SOCIAL_AUTH_GOOGLE_OAUTH2_KEY, SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET
Microsoft (multi-tenant)	SOCIAL_AUTH_MICROSOFT_GRAPH_KEY, SOCIAL_AUTH_MICROSOFT_GRAPH_SECRET
Azure AD (single-tenant)	SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_KEY, SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_SECRET, SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_TENANT_ID
Auth0	SOCIAL_AUTH_AUTH0_DOMAIN, SOCIAL_AUTH_AUTH0_KEY, SOCIAL_AUTH_AUTH0_SECRET
Generic OIDC	SOCIAL_AUTH_OIDC_OIDC_ENDPOINT, SOCIAL_AUTH_OIDC_KEY, SOCIAL_AUTH_OIDC_SECRET

For Auth0, set the callback URL to: https://your-domain/api/1/auth/social/complete/auth0/

Generic OIDC Provider

The generic OIDC provider works with any OpenID Connect compliant identity provider, including:

• Authentik - Self-hosted identity provider
• Authelia - Self-hosted authentication server
• Keycloak - Open source identity management
• Okta - Enterprise identity platform
• And any other OIDC-compliant provider

Configuration:

• SOCIAL_AUTH_OIDC_OIDC_ENDPOINT: The OIDC discovery endpoint (e.g., https://authentik.example.com/application/o/<app-slug>/)
• SOCIAL_AUTH_OIDC_KEY: Client ID from your identity provider
• SOCIAL_AUTH_OIDC_SECRET: Client secret from your identity provider
• SOCIAL_AUTH_OIDC_NAME (optional): Custom button text (default: "SSO")

Set the callback URL to: https://your-domain/api/1/auth/social/complete/oidc/

Note on MFA: Multi-factor authentication is handled by your identity provider. Enable MFA in Authentik, Authelia, or your chosen provider to require 2FA for Tabby Web logins.

Azure AD Single-Tenant

For organizations that want to restrict login to a specific Azure AD/Entra ID tenant (instead of allowing any Microsoft account), use the Azure AD single-tenant provider:

• SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_KEY: Application (client) ID from Azure portal
• SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_SECRET: Client secret
• SOCIAL_AUTH_AZUREAD_TENANT_OAUTH2_TENANT_ID: Directory (tenant) ID

Set the callback URL to: https://your-domain/api/1/auth/social/complete/azuread-tenant-oauth2/

When registering your app in Azure portal, select "Accounts in this organizational directory only" for supported account types.

Adding Tabby app versions

• docker-compose run tabby /manage.sh add_version 1.0.163

You can find the available version numbers here.

Development setup

Put your environment vars (DATABASE_URL, etc.) in the .env file in the root of the repo.

For the frontend:

cd frontend
yarn
yarn run build # or yarn run watch

For the backend:

cd backend
poetry install
./manage.py migrate # set up the database
./manage.py add_version 1.0.156-nightly.2 # install an app distribution
PORT=9000 poetry run gunicorn # optionally with --reload

Security

• When using Tabby Web for SSH/Telnet connectivity, your traffic will pass through a hosted gateway service. It's encrypted in transit (HTTPS) and the gateway servers authenticate themselves with a certificate before connections are made. However there's a non-zero risk of a MITM if a gateway service is compromised and the attacker gains access to the service's private key.
• You can alleviate this risk by hosting your own gateway service, or your own copy of Tabby Web altogether.