Quick Start

Deploy Hyperspeed locally with Docker Compose and complete first-time setup in minutes.

This guide walks you through running Hyperspeed on your local machine using Docker Compose. You will have a working workspace by the end.

Prerequisites

• Docker and Docker Compose v2 — Compose v2 is required because docker-compose.yml uses depends_on health conditions. Verify your versions:

docker --version
docker compose version

Docker Compose v2 ships with Docker Desktop and as a plugin (docker compose). If your system only has the legacy docker-compose binary (v1), upgrade before continuing.

Deploy locally

1. Clone the repository

   Clone the full repository. The build contexts for the API and web images are inside apps/, so the entire repo is required — not just docker-compose.yml.

   git clone https://github.com/jasfromsolaris/Hyperspeed.git
   cd Hyperspeed
   
2. Copy the environment file

   Copy the example environment file to .env. Docker Compose reads this file automatically.

   cp .env.example .env
   
3. Set your secrets

   Open .env and set the two required secrets before starting the stack.

   JWT_SECRET — HMAC key used to sign access tokens. Use a random string of at least 32 characters:

   openssl rand -base64 32
   

   HS_SSH_ENCRYPTION_KEY — Encrypts stored SSH credentials for the terminal. Must be base64-encoded 32 bytes:

   openssl rand -base64 32
   

   Paste both values into .env:

   JWT_SECRET=<your-generated-value>
   HS_SSH_ENCRYPTION_KEY=<your-generated-value>
   

   For a local setup, leave CORS_ORIGIN=http://localhost as-is — this matches the address Caddy serves the app on.

   The default JWT_SECRET in .env.example (dev-change-me-in-production-min-32-chars-long) is a placeholder. Never use it in a real deployment.

4. Build and start the stack

   From the repository root (the directory containing docker-compose.yml), run:

   docker compose up --build
   

   This builds the API (Go) and web (Vite) images, then starts Caddy, Postgres, Redis, MinIO, the API, and the web container. The first build takes a few minutes.

   Run with -d to start in detached mode: docker compose up --build -d

5. Open Hyperspeed

   Once all containers are healthy, open http://localhost in your browser. Caddy serves the app on port 80; the API is also available at http://localhost:8080 for debugging.

6. Complete the setup wizard

   The first time you open the app, clicking Register launches the setup wizard. No organization exists yet, so the wizard walks you through creating the singleton workspace:

   1. Enter your name, email, and password to create the admin account.
   2. Enter a workspace name for your organization.
   3. Review the hostname and go-live notes, then finish setup.

   After the wizard completes, you are logged in as the workspace admin.

   Hyperspeed supports exactly one organization per database. Once the wizard runs, the Register page switches to an access-request flow for subsequent users. Add teammates via invites or enable open registration under workspace settings.

7. Create your first space

   A space is a project container — it holds a kanban board, chat rooms, a file tree, terminal connections, and automations.

   1. Click New space in the sidebar.
   2. Give the space a name and confirm.
   3. Open the Board tab to create your first tasks.

Stack services

The Compose stack runs the following services:

Service	Image	Purpose
caddy	caddy:2-alpine	Reverse proxy; serves the app on ports 80 and 443
postgres	postgres:16-alpine	Primary database
redis	redis:7-alpine	Pub/sub, presence, and file collab relay
minio	minio/minio:latest	Object storage for uploaded files
api	Built from source	Go REST API server
web	Built from source	Static web UI

Next steps

• Deploy to a server — See Deployment to run Hyperspeed on a VPS or cloud host with HTTPS.
• Configure environment variables — See Environment Variables for the full reference.
• Invite your team — Open workspace settings and generate invite links or enable open registration.