Host a project as a web service

Turn a Helix project into a live website or API with automatic deployment, custom domains, and session preview sharing.

Host a project as a web service

Helix can run a persistent web process from your project's source repository and make it available at a public URL. Enable the web service, add a .helix/startup.sh script, and Helix handles provisioning, deployment, and routing.

Separately, any active agent session can expose a port as a shareable preview URL — useful for checking or embedding what an agent is building before it is merged.

Enable the web service

Open your project's settings and select Web Service from the sidebar (the globe icon, or append ?tab=web-service to the URL).

Toggle Enable to turn on hosting. Set the Container port to the port your application will listen on, then save.

Once enabled, a default subdomain is created automatically. This subdomain is always listed as Live and cannot be deleted.

Write a startup script

Helix launches your application by executing .helix/startup.sh in the root of your repository. This script must start a long-running process that listens on the configured port.

The port is passed to the script as the HELIX_WEB_SERVICE_PORT environment variable:

#!/usr/bin/env bash
set -e
python3 -m http.server "$HELIX_WEB_SERVICE_PORT"

The script becomes the web server process — keep it running rather than exiting after startup.

Deploy your application

Automatic deployment on push

Every push to the default branch of the project's primary repository triggers a redeploy. No webhook configuration is needed — Helix's hosted git server fires the hook automatically after a successful push:

git push helix-origin main

The deployment sequence is:

1. Provision a fresh persistent sandbox.
2. Clone the repository and check out the pushed commit.
3. Execute .helix/startup.sh with HELIX_WEB_SERVICE_PORT set.
4. Poll the configured port until the application responds (up to 90 seconds).
5. Atomically switch traffic to the new sandbox and stop the previous one.

If the readiness check times out, the previous sandbox continues serving traffic and the failed sandbox stays running so you can inspect it.

Manual deployment

Use Deploy Now in the Web Service tab to redeploy from the current default branch without pushing new code.

For external CI pipelines or GitHub webhooks, trigger a deploy via the API:

POST /api/v1/projects/{project_id}/web-service/deploy

Add a custom domain

In the Web Service tab, enter a domain in the Add domain field and submit the form. Helix displays a CNAME record to add at your DNS provider:

Add the CNAME record at your DNS provider. Helix checks the domain automatically every minute. Once the DNS record resolves and the verification token matches, the domain status changes from Waiting for DNS to Live.

The verification check is passive — no action is needed after adding the DNS record.

Share a preview URL from an active session

When a spec task has an active session, a Share preview URLs section appears on the task detail page. Use it to expose a port inside the agent's container as a public URL.

Click Mint preview URL, enter the port number the agent is serving on, and Helix generates a share-<adjective>-<noun>-<token> URL.

Each preview URL has individual controls:

Preview URLs are scoped to the session. They are cleaned up automatically when the session ends.

Operator configuration

By default, Helix expects a reverse proxy (such as Caddy) to handle TLS for custom domains. To enable embedded TLS termination with automatic Let's Encrypt certificates, set:

HELIX_VHOST_TLS_MODE=auto
HELIX_VHOST_LETSENCRYPT_EMAIL=admin@example.com

When auto mode is active, Helix binds :443 for HTTPS and :80 for the ACME HTTP-01 challenge and plain-HTTP redirects. Certificates are issued on demand for the Helix canonical hostname and for any verified domain in the routing table. Certificates are stored in /data/certmagic.

HELIX_VHOST_TLS_MODE=off (the default) leaves TLS to the operator's reverse proxy and is unaffected by this setting.