Self-Hosting Quickstart

Overview

OpenSail is Apache 2.0 and self-hosts cleanly. There are four supported install paths. This page is a router. Pick the path that fits your goal, then follow the dedicated guide.

Prefer a managed experience? tesslate.com runs OpenSail as a hosted service with zero setup.

Pick your path

Docker Compose

One command brings up the full stack on your laptop or a single VM. The fastest way to kick the tires. Best for local development and small teams.

Desktop App

Native Tauri v2 app with a built-in FastAPI sidecar and SQLite. No Docker, no cluster. Runs fully offline against local models.

Kubernetes (Minikube)

Full K8s pipeline on your machine: per-project namespaces, btrfs CSI volumes, Volume Hub, snapshots. Test the production path end to end.

AWS EKS

Production deployment via Terraform. EKS, ECR, managed Postgres, S3-backed CAS, wildcard TLS via cert-manager.

Decision matrix

By use case
By capability
By operator effort

You want to…	Pick
Kick the tires in 10 minutes	Docker Compose
Build on a single machine with no containers	Desktop
Air-gapped install with Ollama	Desktop or Docker
Serve a small team on one VM	Docker Compose
Multi-tenant production with isolation and snapshots	AWS EKS
Validate the K8s pipeline before prod	Minikube
Pair a local app to your own self-hosted cloud	Desktop + AWS EKS

Capability	Docker	Desktop	Minikube	AWS EKS
AI agent runs (`tesslate-agent`)	Yes	Yes	Yes	Yes
Live preview and Monaco editor	Yes	Yes	Yes	Yes
Multi-container projects	Yes	docker runtime	Yes	Yes
Per-project namespace isolation	No	No	Yes	Yes
btrfs CSI and Volume Hub	No	No	Yes	Yes
Snapshot timeline (up to 5 per project)	No	No	Yes	Yes
Hibernation with CAS restore	No	No	Yes	Yes
Three-tier compute (0 / 1 / 2)	Partial	Partial	Yes	Yes
Wildcard TLS via cert-manager	No	No	No	Yes
SQLite (no Postgres)	No	Yes	No	No
No Redis required	No	Yes	No	No
Horizontal scaling	No	No	No	Yes

Path	Setup	Moving parts	Ongoing ops
Docker Compose	10 min	Postgres, Redis, Traefik, orchestrator, app, devserver image	Restart, rotate backups
Desktop	2 min	Tauri binary, sidecar, SQLite	Installer auto-updates
Minikube	30 min	Cluster, kustomize, local images, btrfs CSI, Volume Hub	Rebuilds, manifest rollouts
AWS EKS	2 to 4 hr	Terraform, EKS, ECR, RDS, S3, Cloudflare, wildcard TLS	Cluster upgrades, cost monitoring

Prerequisites by path

Docker
Desktop
Minikube
AWS EKS

Requirement	Notes
Docker Engine + Compose v2	Docker Desktop on macOS and Windows
8 GB RAM minimum	16 GB recommended
10 GB free disk	For images and volumes
A model key or LiteLLM endpoint	BYOK OpenAI, Anthropic, OpenRouter, or point at local Ollama
Git	For cloning the repo

Requirement	Notes
macOS 12+, Windows 10+, or Linux	Tauri v2 builds for all three
4 GB RAM minimum	SQLite and sidecar are lightweight
2 GB free disk	Grows with projects
A model key	BYOK or Ollama for fully offline use
Optional: Docker	Enables the `docker` per-project runtime
Optional: `tsk_` API key	Unlocks marketplace, sync, remote K8s runtime

Requirement	Notes
Minikube	With the Docker or KVM driver
kubectl + kustomize	Kustomize ships with kubectl 1.14+
btrfs-capable node	Required for the btrfs CSI driver
Local Docker registry	Minikube loads images by name
A model key or LiteLLM endpoint	BYOK or proxy

Requirement	Notes
AWS account with admin	EKS, ECR, RDS, S3, IAM
Terraform	`k8s/terraform/aws/`
Cloudflare DNS	For apex and wildcard certs
Managed Postgres	RDS recommended
ElastiCache Redis	For ARQ and pub/sub
btrfs-capable nodegroup	Required for CSI driver and Volume Hub
LiteLLM deployment	Or direct provider keys on the proxy

Core environment variables

Every path reads the same core variables. The full reference lives in Configuration.

Variable	Why it matters
`SECRET_KEY`	JWT signing and Fernet encryption for stored credentials
`DEPLOYMENT_MODE`	`docker`, `kubernetes`, or `desktop`. Selects orchestrator, DB driver, queue, pub/sub
`DATABASE_URL`	Postgres (cloud) or resolved SQLite (desktop)
`LITELLM_API_BASE` + `LITELLM_MASTER_KEY`	AI gateway that fans out to providers
`APP_DOMAIN`	Apex domain for routing, cookies, and OAuth redirects
`OPENSAIL_HOME`	Desktop only. Data directory for `opensail.db`, projects, and cache

Generate a secure SECRET_KEY:

python3 -c "import secrets; print(secrets.token_urlsafe(32))"

What you get after install

Component	Source path	Purpose
Orchestrator	`orchestrator/app/main.py`	FastAPI backend, router registration, middleware
Agent runner	`packages/tesslate-agent/`	Agent loop, tool registry, context compaction, approval gates
Task queue	`orchestrator/app/services/task_queue/`	ARQ on Redis (cloud) or asyncio + apscheduler (desktop)
Pub/sub	`orchestrator/app/services/pubsub/`	Redis Streams (cloud) or in-process (desktop)
Orchestration	`orchestrator/app/services/orchestration/`	Per-project `factory.py` resolves Docker, Kubernetes, or local backends
Volume Hub client	`orchestrator/app/services/volume_manager.py`	gRPC client to the Hub (K8s only)
Frontend	`app/src/App.tsx`	React 19, Vite, Monaco

Next steps

Docker setup

Full Docker Compose install with seeds and clean-slate reset.

Desktop install

Installers, cloud pairing, permission system, runtime selection.

Kubernetes on Minikube

End-to-end K8s locally including btrfs CSI and Volume Hub.

AWS production

Terraform, EKS, ECR, wildcard TLS, S3 CAS, managed Postgres.

Configuration reference

Every environment variable, grouped by subsystem.

Architecture

Orchestrator, agent runner, storage, queue, compute tiers.

Getting help

GitHub

Source, releases, and issue tracker.

Discord

Ask questions, share what you are building.

Agent runner

Deep dive on the tesslate-agent package.

Email

Direct support.

Get Started

Install and Run

Core Concepts

Working with Projects

Agents and Skills

Ship and Share

Self-Hosting

Developer Guide

Self-Hosting Quickstart

Overview

Pick your path

Docker Compose

Desktop App

Kubernetes (Minikube)

AWS EKS

Decision matrix

Prerequisites by path

Core environment variables

What you get after install

Next steps

Docker setup

Desktop install

Kubernetes on Minikube

AWS production

Configuration reference

Architecture

Getting help

GitHub

Discord

Agent runner

Email

​Overview

​Pick your path

Docker Compose

Desktop App

Kubernetes (Minikube)

AWS EKS

​Decision matrix

​Prerequisites by path

​Core environment variables

​What you get after install

​Next steps

Docker setup

Desktop install

Kubernetes on Minikube

AWS production

Configuration reference

Architecture

​Getting help

GitHub

Discord

Agent runner

Email

Overview

Pick your path

Decision matrix

Prerequisites by path

Core environment variables

What you get after install

Next steps

Getting help