Environment Variables

Complete reference for all environment variables used when self-hosting Hyperspeed via Docker Compose.

Copy .env.example to .env in the repository root and fill in the values below. Docker Compose reads .env automatically.

Variables marked Required must be set before starting the stack in production. The API will refuse to start (or log a fatal error) if JWT_SECRET is shorter than 32 characters or HS_SSH_ENCRYPTION_KEY is missing when DEBUG is not set.

Required

Variable	Default	Description
JWT_SECRET	(none)	HMAC key for signing access tokens. Use a strong random string of at least 32 characters. Generate one with openssl rand -hex 32.
HS_SSH_ENCRYPTION_KEY	(none)	AES-256 key for encrypting stored SSH credentials. Must be base64-encoded and decode to exactly 32 bytes. Generate with openssl rand -base64 32.

Never ship the placeholder values from .env.example to production. The API rejects JWT_SECRET shorter than 32 characters and any known default value when DEBUG is unset.

Network and CORS

Variable	Default	Description
CORS_ORIGIN	http://localhost:5173	The exact browser origin the API permits for cross-origin requests — scheme, host, and port if non-default (e.g. https://app.example.com). With Docker Compose + Caddy, set this to http://localhost locally or https://<your-hostname> in production.
PUBLIC_APP_URL	(empty)	Optional. Public HTTPS URL shown during onboarding (e.g. https://hyperspeed.example.com). Does not affect routing.
PUBLIC_API_BASE_URL	(empty)	Absolute origin the API uses when constructing absolute URLs (e.g. IDE preview iframe URLs). Set to the same value users type in the browser, without a trailing path: https://app.example.com.
HTTP_ADDR	:8080	Bind address for the API HTTP server inside the container.

Caddy and TLS

Variable	Default	Description
CADDY_PUBLIC_HOST	localhost	Hostname for Caddy’s site block. Set to localhost for HTTP-only local development. Set to a real FQDN (e.g. app.example.com) to enable automatic HTTPS via Let’s Encrypt. Do not include https://.
CADDY_EMAIL	(empty)	Email address for Let’s Encrypt account registration. Required when CADDY_PUBLIC_HOST is a real hostname.

DNS for CADDY_PUBLIC_HOST must resolve to your server’s public IP before Caddy can obtain a certificate. See TLS & HTTPS for the full setup flow.

Database and storage

Variable	Default	Description
DATABASE_URL	postgres://hyperspeed:hyperspeed@localhost:5432/hyperspeed?sslmode=disable	PostgreSQL connection string.
REDIS_URL	redis://localhost:6379/0	Redis connection string. Used for pub/sub and the collaborative editing WebSocket.
FILES_S3_ENDPOINT	(MinIO default from Compose)	Custom S3-compatible endpoint URL (e.g. for an external MinIO or AWS S3).
FILES_S3_REGION	(MinIO default from Compose)	S3 region.
FILES_S3_BUCKET	(MinIO default from Compose)	S3 bucket name.
FILES_S3_ACCESS_KEY	(MinIO default from Compose)	S3 access key ID.
FILES_S3_SECRET_KEY	(MinIO default from Compose)	S3 secret access key.
FILES_S3_FORCE_PATH_STYLE	true	Set to true for MinIO and other non-AWS S3-compatible stores. Set to false for AWS S3.

Provisioning (gifted subdomain)

These variables enable the optional Hyperspeed-operated provisioning gateway that creates *.hyperspeedapp.com DNS records for your install. Leave them unset if you are using a BYO domain.

Variable	Default	Description
PROVISIONING_BASE_URL	(empty)	HTTPS origin of the Hyperspeed provisioning gateway, no trailing path (e.g. https://provision.hyperspeedapp.com).
PROVISIONING_INSTALL_ID	(empty)	Install identifier issued by Hyperspeed. The gateway stores the matching secret on its side.
PROVISIONING_INSTALL_SECRET	(empty)	HMAC key used to sign requests to the provisioning gateway. This is scoped to your install — not the Hyperspeed control-plane bearer or any Cloudflare token.

When all three provisioning variables are set, GET /api/v1/public/instance returns provisioning_enabled: true and provisioning_base_domain: "hyperspeedapp.com". Authenticated users can then call POST /api/v1/provisioning/claim from the setup wizard or workspace settings.

Build metadata

These are typically passed as Docker build arguments rather than set in .env directly. See the repository docker-compose.yml for how they forward to the API image build.

Variable	Default	Description
HYPERSPEED_VERSION	dev	Semantic version string reported by GET /health and GET /api/v1/public/instance.
HYPERSPEED_GIT_SHA	(empty)	Git commit SHA reported by the same health endpoints.

Update notices

Variable	Default	Description
UPSTREAM_GITHUB_REPO	(empty)	GitHub repository in owner/name format (e.g. owner/hyperspeed). When set, the Dashboard can show in-app update notices. Users must opt in before the browser contacts GitHub.
UPDATE_MANIFEST_URL	(empty)	HTTPS URL to a static JSON release manifest, as an alternative to UPSTREAM_GITHUB_REPO. Set one or the other, not both.

Neither UPSTREAM_GITHUB_REPO nor UPDATE_MANIFEST_URL causes any outbound requests from the server. The browser contacts the source directly, and only after the user opts in on the Dashboard.

OpenRouter tuning

These variables tune server-side tool calling for OpenRouter AI integrations. Organization API keys are managed in the app itself; these variables configure how the server invokes tools on behalf of users.

Variable	Default	Description
OPENROUTER_CHAT_TOOLS_ENABLED	true	Enable function and server-side tools for OpenRouter staff mentions.
OPENROUTER_CHAT_SKIP_PREREAD	true	Skip the pre-read step before tool calls.
OPENROUTER_WEB_SEARCH_TOOL	true	Add the openrouter:web_search server tool. Extra billing from OpenRouter may apply.
OPENROUTER_DATETIME_TOOL	true	Add the openrouter:datetime server tool.
OPENROUTER_WEB_SEARCH_ENGINE	(empty, OpenRouter default)	Web search engine hint: auto, exa, or native. Leave empty to use the OpenRouter default.
OPENROUTER_WEB_SEARCH_MAX_RESULTS	5	Maximum results per individual web search call.
OPENROUTER_WEB_SEARCH_MAX_TOTAL_RESULTS	15	Maximum total results across all search calls in one completion.
OPENROUTER_CHAT_MAX_TOOL_ITERATIONS	0 (unlimited)	Maximum number of tool-call iterations per completion. 0 means no limit.
OPENROUTER_CHAT_TOOL_STEP_TIMEOUT_SEC	90	Timeout in seconds for each individual tool step.
OPENROUTER_CHAT_REASONING_JSON	(empty)	Optional JSON object passed as the top-level reasoning field on completions. Use with reasoning-capable models. Examples: {"effort":"high"}, {"max_tokens":4096}, {"effort":"medium","exclude":true}.
OPENROUTER_CHAT_MAX_TOKENS	0 (model default)	Override max_tokens on completions. Recommended when using OPENROUTER_CHAT_REASONING_JSON — set high enough to cover both the thinking budget and the answer (e.g. 16000 for Anthropic reasoning models).
OPENROUTER_PLUGINS_JSON	(empty)	Optional JSON array of OpenRouter request plugins, e.g. [{"id":"response-healing"}].

Cursor

These variables configure the Cursor-compatible API integration used for org-backed chat completions and Cloud Agents.

Variable	Default	Description
CURSOR_API_BASE_URL	https://api.cursor.com	Origin for Cursor-compatible chat completions (OpenAI-compatible endpoint).
CURSOR_CHAT_COMPLETIONS_PATH	/v1/chat/completions	Path appended to CURSOR_API_BASE_URL for chat completion requests.
CURSOR_COMPLETION_MODEL	auto	Model identifier sent to the Cursor API.
CURSOR_HTTP_AUTH	bearer	Authentication scheme: bearer (default) or basic (API key as Basic username, empty password).
CURSOR_AGENTS_BASE_URL	(same as CURSOR_API_BASE_URL)	Origin for Cloud Agents v0 requests. Defaults to the same host as CURSOR_API_BASE_URL when left empty.

Debug and development

Variable	Default	Description
DEBUG	false	Enable verbose text logs and relaxed validation (skips required-secret checks). Use only for local development — never in production.
HS_GIT_WORKDIR_BASE	(empty)	Directory for per-space Git working trees (IDE Git integration). When unset, the Git panel shows as unavailable. Example: /var/lib/hyperspeed/git.