Getting Started

Getting Started with Termi

This guide gets a self-hosted Termi instance running with Docker Compose in a few minutes. For the native desktop app instead, see Desktop App.

Prerequisites

• Docker and Docker Compose
• A Linux, macOS, or Windows machine to host it on (a home server, NAS, VPS, or your own laptop all work)

1. Clone the repository

git clone https://github.com/shuvoooo/termi.git
cd termi

2. Configure environment variables

cp .env.example .env

Open .env and set the required secrets. Generate each one with:

openssl rand -base64 32

DB_HOST=postgres          # Docker service name, or an external DB host
DB_USER=termi
DB_PASSWORD=<strong-password>
DB_NAME=termi

SESSION_SECRET=<generated-secret>
ENCRYPTION_KEY=<generated-secret>
GATEWAY_JWT_SECRET=<generated-secret>

NEXT_PUBLIC_GATEWAY_URL=ws://localhost:22080/gateway
NEXT_PUBLIC_APP_URL=http://localhost:22080

3. Start the stack

docker compose up -d

4. Run database migrations

docker compose exec web npx prisma migrate deploy

5. Open Termi

Visit http://localhost:22080 and create your first account.

Optional: RDP / VNC support

RDP and VNC connections are proxied through Apache Guacamole's guacd daemon, which needs to run alongside the stack:

docker run -d -p 4822:4822 --name termi-guacd guacamole/guacd:1.6.0

On Apple Silicon (ARM64 hosts), add --platform linux/arm64 to avoid FreeRDP alignment issues.

Reverse proxy / TLS

Termi includes ready-to-use Traefik configuration for exposing your instance over HTTPS with a real domain — see the docker-compose.yml and .env.example in the repository for the GATEWAY_DOMAIN / GATEWAY_PREFIX options.

Next steps

• Features — see everything Termi can do
• Security — understand the encryption and authentication model before you add production credentials
• Desktop App — install a native client that connects to your new instance
• Troubleshooting — fixes for common setup errors (guacd, RDP, SSRF, secrets)
• FAQ — common setup questions

Need help? Open a GitHub Discussion or check SUPPORT.md in the repository.