Deploying Your Own Web App

First, a routing note. If you just want to put an HQ-generated artifact (a report, a mockup, a small page) on a link, you do not need this article: ask HQ to /deploy it and you are done. This article is for the next level up: deploying an app you built yourself, with its own build step and possibly its own server, using the hq-deploy command line tool directly.

The hq-deploy CLI#

hq-deploy is its own small tool, separate from the hq CLI and from slash commands (see Every HQ Command at a Glance for that distinction). Run it with npx or install it globally.

The four subcommands you will actually use:

That last one answers the most common question builders have: "my deployed app is erroring, where are its logs?" They are captured for every app, and hq-deploy logs is how you read them.

No configuration needed. The CLI detects your framework by scanning the project's config files, in this order: Next.js (server-rendered), Remix (server-rendered), Astro (server-rendered if configured with output: server, otherwise static), then Vite (static). Anything else deploys as a static site. The detection result is cached in .hq-deploy/detected.json so later deploys skip the scan.

A static site gets built, uploaded, and served from a CDN. A server-rendered app gets built into a container and run for you. Either way, the flow is the same from your side:

hq-deploy deploy

and your app comes up at {app}.indigo-hq.com.

The two rules for server-rendered apps#

Static sites have no special requirements. Server-rendered (SSR) apps have exactly two, and missing either one will fail the deploy:

1. Answer health checks. Your app must respond with a 200 status to GET /health. The platform uses this endpoint to decide whether a new version is alive. No /health route, no successful deploy.
2. Listen on the platform's port. Your server must listen on the port given by the PORT environment variable, which is set to 3000. Hard-coding a different port means the platform can never reach your app.

Each running app gets a quarter of a CPU and half a gigabyte of memory, which is plenty for a typical server-rendered site.

Bad deploys never take your site down. Deploys are rolling: the previous version keeps serving traffic the entire time the new one is starting. If the new version does not become healthy within 5 minutes, the deploy is marked failed, and the old version simply continues serving as if nothing happened. When the new version does come up healthy, traffic moves over with zero downtime. So the worst case for a broken deploy is a "failed" status and a log to read with hq-deploy logs, never an outage.

Building a full-stack app? HQ Deploy supports Next.js 15 and Hono 4. See Deploying Full-Stack Apps: Next.js and Hono.

API keys#

hq-deploy login asks for a platform API key. Facts worth knowing about these keys:

• Keys start with the hqd_ prefix, so you can recognize one on sight.
• The full key is shown exactly once, at creation. The server keeps only a one-way hash, so nobody (including support) can recover a lost key. If you lose it, revoke it and create a new one.
• After login, the key is stored on your machine in ~/.hq-deploy/config.json, readable only by your user account.
• You can list your active keys and revoke any of them at any time; listing never reveals the secret part.

Treat a deploy key like any credential: it belongs in the login prompt and nowhere else. Never paste it into a chat session or a document; the reasons are in the Secrets Guide.

One line for completeness: enterprises can run the entire deploy stack inside their own AWS account, authenticating with their existing AWS credentials instead of platform keys. If that is you, the reference lives at docs.hq.computer.

Common questions#

If you get stuck#

A failed SSR deploy is almost always one of the two rules: no 200 from GET /health, or not listening on PORT (3000). Check those first, then read hq-deploy logs. For everything else, see The "I'm Stuck" Guide or file /hq-bug.