> ## Documentation Index
> Fetch the complete documentation index at: https://hyperspeed.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Note>
  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.
</Note>

## 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`. |

<Warning>
  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.
</Warning>

## 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. |

<Tip>
  DNS for `CADDY_PUBLIC_HOST` must resolve to your server's public IP before Caddy can obtain a certificate. See [TLS & HTTPS](/configuration/tls) for the full setup flow.
</Tip>

## 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. |

<Note>
  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.
</Note>

## 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. |

<Note>
  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.
</Note>

## 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`. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.