Repository navigation
Releases
v1.0.1: Dependencies Upgrade Only
Tabby Sync 1.0.1 — Stable
This release updates dependencies to their stable versions. No functional changes are introduced.
Changes
- Upgraded dependencies to stable releases
v1.0.0: first stable release
Tabby Sync Version 1.0.0 - Stable
First stable release of tabby-sync. A minimal self-hostable backend for the Tabby terminal's config sync feature, forked from tabby-web and stripped down to the three endpoints the desktop client actually calls.
Highlights
Minimal by design
About 360 lines of application Python around Bearer-token sync, plus 130 lines of Django settings. No web terminal, no OAuth providers, no WebSocket gateway, no app distribution, no analytics. Eight production dependencies total.
HTTPS by default
A plain docker compose up -d boots Django, Postgres and Caddy together. Caddy is the only published entry point on ports 80/443/443-udp with automatic Let's Encrypt certificates. The backend container has no exposed port and is not reachable from outside the Docker network. A separate overlay is available for local development without TLS.
Sync tokens hashed at rest
Tokens are stored as SHA-256 hashes. The cleartext is displayed exactly once at creation or on explicit rotation through a dedicated admin page or the CLI. A database dump does not expose usable tokens.
Admin and CLI provisioning
Sync users are created through the Django admin with a dedicated token display page and a Regenerate button, or through two management commands designed to be piped directly in scripts:
TOKEN=$(docker compose exec -T tabby /app/manage.sh create_sync_user alice)
TOKEN=$(docker compose exec -T tabby /app/manage.sh refresh_token alice)Tested and covered
170 unit and integration tests with 100% line coverage on the application code, gated by the CI pipeline. Every tag push builds and publishes a multi-tagged Docker image to GHCR.
Install
cp .env.example .env
# Fill in DB_PASSWORD, DJANGO_SECRET_KEY, DOMAIN and ACME_EMAIL
docker compose up -d
docker compose exec tabby /app/manage.sh createsuperuserOpen https:///admin/, create a sync user, copy the token from the display page, paste it into Tabby desktop under Settings > Config sync.
Image
docker pull ghcr.io/mathys-lopinto/tabby-sync:1.0.0
docker pull ghcr.io/mathys-lopinto/tabby-sync:1.0
docker pull ghcr.io/mathys-lopinto/tabby-sync:latest
Upgrade from beta
No migration added since 1.0.0b3. Existing users, tokens and configs are untouched. The :latest tag now points at a stable release.
Known limitations
- No app-level rate limiting or brute-force protection on the admin login. Run behind a VPN, an IP allowlist or a WAF when exposing the admin publicly.
- Django admin is the only browser-accessible UI. Sync-only users should never be granted is_staff or is_superuser.
Thanks
This project is a fork of https://github.com/Eugeny/tabby-web by https://github.com/Eugeny. The upstream MIT license and copyright notice are preserved.
v1.0.0b3: force HTTPS by default
Tabby Sync Version 1.0.0 - Beta 3
HTTPS is now the default. A plain docker compose up -d runs the full stack (Django, Postgres, Caddy) with Caddy as the only published entry point. The backend container has no exposed port and is not reachable from outside the Docker network.
What changed since b2
docker-compose.ymlnow includes the Caddy service, volumes and healthcheck. The backend has noports:mapping. Default image source isghcr.io/mathys-lopinto/tabby-sync:latest.docker-compose.https.ymldeleted. No longer needed.docker-compose.dev.ymladded as an overlay for local development (re-exposes port 9090, disables Caddy).- Gunicorn timeout lowered from 30s to 10s after observing internet scanner noise tying up sync workers on a real deployment.
- README rewritten with a quick start section, updated architecture diagram showing Caddy in the default path, and instructions for importing self-signed certificates into the host trust store.
Deployment
cp .env.example .env
# Fill in DB_PASSWORD, DJANGO_SECRET_KEY, DOMAIN and ACME_EMAIL
docker compose up -d
docker compose exec tabby /app/manage.sh createsuperuserFor LAN/VPN without a public domain, uncomment the tls line in caddy/Caddyfile and run ./scripts/generate-cert.sh before starting.
Image
docker pull ghcr.io/mathys-lopinto/tabby-sync:1.0.0b3
v1.0.0b2: fix PEP 440 release pipeline and bump deps
Tabby Sync Version 1.0.0 - Beta 2
Re-issue of v1.0.0b1 with a working release pipeline, plus a first Dependabot round.
Why this release
v1.0.0b1 merged and tagged, but docker/metadata-action's type=semver silently rejected the PEP 440 version, so only :latest was published and no versioned tag made it to GHCR. Worse, that :latest actually pointed at the beta image because the pre-release gate looked for the literal word beta, not the PEP 440 b.
This release exercises the fixed workflow and publishes the image correctly.
What changed since b1
Release workflow
release.ymlnow usestype=matchto extract the version from the tag name, handling both PEP 440 (1.0.0b2) and semver (1.0.0-beta1) forms.major.minoris only applied to stable tags.latestis gated on the absence ofa,bandrcsubstrings, so pre-releases never touch it.
Dependencies
First Dependabot run, grouped under the python-minor update:
- psycopg 3.2.10 → 3.3.3
- ruff 0.11.13 → 0.15.10
No breaking changes touch this project; the pin-in-version strategy caught by poetry.lock keeps the install reproducible.
Application code
No changes. The Django app, CLI commands and admin flows are identical to b1.
Image
docker pull ghcr.io/mathys-lopinto/tabby-sync:1.0.0b2No :latest or :1.0 tag for this pre-release.
Housekeeping
The stale :latest image left over from the b1 run has been manually deleted from the GHCR package UI — the workflow does not rewrite it.
v1.0.0b1: CI/CD pipeline
Tabby Sync Version 1.0.0 - Beta 1
First beta. Leaving alpha now that a real CI/CD pipeline protects the code and the published image is built on every tag.
Highlights
Continuous integration
A GitHub Actions workflow runs on every push and every pull request targeting master. Ruff lint, Ruff format check, and the full pytest suite with branch coverage all have to pass before anything merges. Coverage is uploaded to Codecov and surfaced through the badge in the README.
Published Docker image
Every v*.*.* git tag now triggers a second workflow that builds the Dockerfile and publishes ghcr.io/mathys-lopinto/tabby-sync with semver tags. Pre-release tags (alpha, beta, rc) get their own versioned tag but leave :latest alone, so pulling :latest always lands on a stable release.
The base docker-compose.yml now ships with a commented image: line next to build: ., so operators can swap one for the other to pull the published image instead of building locally.
Dependabot
Weekly pull requests for dependency bumps across Poetry, the Docker base image and the GitHub Actions used in the workflows. Patch and minor updates are grouped to reduce PR noise.
Ruff hygiene
A first pass of ruff check and ruff format on the existing code added a __str__ to Config, cleaned up a duplicate import and an unused variable in the test suite, and kept null=True on two Tabby-client-populated CharFields (User.active_version, Config.last_used_with_version) as a documented ignore since the stored representation is part of the client contract.
Image
docker pull ghcr.io/mathys-lopinto/tabby-sync:1.0.0b1Or open docker-compose.yml and uncomment the image: line to pull instead of building.
Upgrade notes
- No migration added since alpha3. Existing users, tokens and configs are untouched.
- Enable branch protection on
masterso the newCI / lint-and-teststatus check gates merges. Recommended rules: require a PR, require the CI status check to pass, require linear history, require conversation resolution.
v1.0.0-alpha3: CLI provisioning and ops polish
Tabby Sync Version 1.0.0 - Alpha 3
Scripted user provisioning from the command line, a real health endpoint, Docker healthchecks wired up end-to-end, and the last of the upstream dead code gone. No breaking changes.
Highlights
Scripted provisioning
Two new management commands make the user lifecycle fully scriptable:
TOKEN=$(docker compose exec -T tabby /app/manage.sh create_sync_user alice)
TOKEN=$(docker compose exec -T tabby /app/manage.sh refresh_token alice)create_sync_user creates a sync-only user with an unusable password and prints the cleartext token on stdout. refresh_token rotates an existing user's token and prints the new value. Both fail with a non-zero exit code on invalid usernames so shell scripts stop early.
Health and readiness
- New GET /api/health returns plain ok with no authentication, suitable for uptime probes and reverse-proxy checks.
- The tabby service got a Docker healthcheck that pings this endpoint.
- The HTTPS overlay now gates Caddy on service_healthy, so the reverse proxy does not serve traffic until migrations have run and gunicorn is actually answering. No more 502s during boot.
Operational hardening
- JSON-file log rotation on both tabby and db (10 MB per file, 3 files). Long-running deployments no longer fill the disk with container logs.
- Upstream CORS block removed. Tabby desktop is an Electron client, so CORS headers never applied in the first place. django-cors-headers is dropped from the dependency tree.
- Secure cookies are now controlled by an explicit SECURE_COOKIES=True env var, replacing the earlier "inferred from FRONTEND_URL" logic.
Meta
- SECURITY.md documents the private reporting channel.
- README covers /api/health and the new CLI commands.
Upgrade notes
- No migrations added. Existing users, tokens and configs are unchanged.
- .env cleanup: FRONTEND_URL, CORS_EXTRA_URL and BACKEND_URL are no longer read. Set SECURE_COOKIES=True in production deployments behind HTTPS.
- django-cors-headers is no longer installed; if you had a fork that depended on it, reinstall it locally.
Verified
- pytest: 169 tests, 100% line coverage on tabby/.
- End-to-end tests cover the CLI commands against the real API.
- docker compose up -d goes healthy within the start grace period.
Known limitations
- Still alpha. No real deployment exercised beyond the author's machine.
v1.0.0-alpha2: HTTPS overlay, hashed sync tokens and admin token UX
Tabby Sync Version 1.0.0 - Alpha 2
Second alpha. The backend now ships with an HTTPS overlay, hashed-at-rest sync tokens and a real admin UI for token management.
Highlights
HTTPS via Caddy. An optional docker-compose.https.yml overlay puts Caddy 2.11.2 in front of the app. By default it obtains a Let's Encrypt certificate over ACME (requires a public domain and port 80 reachable). For LAN, VPN or homelab setups, a single line in caddy/Caddyfile switches Caddy to a self-signed ECDSA P-256 certificate generated by scripts/generate-cert.sh. Only /api/*, /admin/* and /static/* are proxied to the backend; the rest is 404 at the proxy level. HTTP/3 is enabled.
Sync tokens hashed at rest. The config_sync_token cleartext column is gone. Users now hold a SHA-256 hash (config_sync_token_hash, indexed), and authentication is a hashed lookup that is effectively constant-time at the application layer. Tokens already in use are hashed in place by migration 0002, so connected Tabby desktops keep working without re-provisioning.
Admin UX for token management. Because the cleartext can no longer be read back from the database, the admin UI now owns the token lifecycle:
- A Regenerate sync token button on the user edit page.
- A dedicated display page at
/admin/app/user/<pk>/sync-token-shown/that shows the cleartext in a read-only field with a Copy button. The token is passed through the session and popped on render, so a reload falls back to a "no longer available" panel. - User creation also lands on that page, so staff cannot miss the token.
Tightened API surface.
ConfigSerializer.nameregained the missingmax_length=255validator.UserSerializer.active_configis scoped to the requesting user, closing a cross-user assignment hole.active_versionis now exposed through the API instead of being silently dropped.PATCHis wired on/api/1/user, so clients no longer have to echo the whole object on a partial update.- DRF's
SimpleRouterreplacesDefaultRouter, dropping the discovery index that was rendered at/.
Middleware cleanup. TokenMiddleware no longer opens a Django session and monkey-patches it shut. It sets request.user directly, filters is_active explicitly for defense in depth and tolerates any whitespace between Bearer and the value.
Postgres volume fix. postgres:18-alpine hard-codes PGDATA=/var/lib/postgresql/18/docker. The compose mount was pointed at the old path, so the named volume was never actually written to and each restart looked like a fresh initdb. The mount now matches, data persists across restarts.
Test suite. 157 tests, 100% line coverage on tabby/. Coverage gated at 85% via pytest-cov in pyproject.toml.
Install
cp .env.example .env
# fill in DB_PASSWORD, DJANGO_SECRET_KEY, DOMAIN
docker compose up -d
docker compose exec tabby /app/manage.sh createsuperuserThen http://localhost:9090/admin/, Users → Add user → Save. The admin redirects to the token display page; copy the token and paste it in Tabby desktop under Settings → Config sync.
For HTTPS with a self-signed certificate:
./scripts/generate-cert.sh
docker compose -f docker-compose.yml -f docker-compose.https.yml up -dUpgrade notes
- Run migrations (0002_hash_sync_token and 0003_alter_user_active_config_alter_user_active_version). Existing tokens are hashed in place; no client reconfiguration required.
- The admin used to display the token as a plaintext field. It now shows nothing about the token; use the Regenerate sync token button to issue a new one if you need access to it.
- GET /api/1/user still includes config_sync_token for backwards compatibility, but always returns null.
Caveats
- Still alpha. The full stack (Postgres + Caddy HTTPS) has only been exercised on the author's machine.
- No app-level rate limiting; put a real gateway in front for public deployments. The shipped Caddy overlay is meant for private / LAN / VPN contexts.
- No tests (yet) for brute force / timing / concurrency; those remain theoretical concerns for a self-hosted backend behind auth.
v1.0.0-alpha1: first runnable cut
Tabby Sync Version 1.0.0 - Alpha 1
First alpha of tabby-sync, a self-hostable backend for Tabby desktop's config sync. Forked from [tabby-web] and cut down to that single feature.
What's in
CRUD on /api/1/configs and GET/PUT on /api/1/user, both behind a per-user Bearer token (config_sync_token, 64 bytes hex, auto-generated). Token exposed through the Django admin. A multi-stage Dockerfile on python:3.14-slim + a Compose stack with Postgres 18.3-alpine, secrets from .env, named volume, pg_isready healthcheck.
What's out
Angular web terminal, WebSocket SSH/Telnet gateway, seven OAuth providers (GitHub/GitLab/Google/Microsoft/Azure AD/Auth0/OIDC), Tabby version distribution, GitHub sponsors check, Google Analytics, upstream CI.
Dep bumps vs upstream
- Django 3.2 → 6.0.4
- DRF 3.12 → 3.17.1
- gunicorn 20 → 25.3.0
- whitenoise 5.3 → 6.12.0
- django-cors-headers 3.7 → 4.9.0
- dj-database-url 0.5 → 3.1.2
- python-dotenv 0.17 → 1.2.2
- DB driver: mysqlclient → psycopg[binary] 3.2.10 (mysqlclient kept as
-E mysqlextra) - Python 3.7 → 3.14
- Lint: flake8 → ruff 0.11 (with formatter)
poetry.lockcommitted for reproducible builds
Install
cp .env.example .env
# fill in DB_PASSWORD and DJANGO_SECRET_KEY
docker compose up -d
docker compose exec tabby /app/manage.sh createsuperuserThen http://localhost:9090/admin/, add a user, copy their config_sync_token, paste it in Tabby desktop under Settings → Config sync.
Caveats
- Alpha. Boots end-to-end on my box, no real deployment yet.
- No tests.
- No app-level TLS, put a reverse proxy in front (an nginx + self-signed cert stack is drafted locally, coming in a follow-up).
- Users are provisioned through the admin; no CLI command yet.
- pip-audit clean at release time.