Deployment

helix deploy builds your project and ships it to the Helix platform in one command. Functions run on a managed runtime per project that routes each request to the correct handler, SPA assets are served from the CDN, and the app is live at https://{project-id}.helix-app.ai. The first deploy provisions the project and records its ID; later deploys update it in place.

The build pipeline

Deploy builds and bundles your functions, then packages anything needed to run them:

1. Reads helix.config.ts. Validates the project ID, workspace ID, and auth aliases.
2. Scans functions/. Builds the route map from the file system and identifies scheduled functions.
3. Builds and bundles functions. Compiles handlers into a deployable bundle that routes each request to the correct handler.
4. Extracts configs. Reads the defineFunction and defineSchedule configs from each file to build the deployment manifest (schemas, trigger configs, routes).
5. Builds the SPA. Runs vite build if app/ exists.
6. Generates the manifest. A JSON file describing all functions, routes, triggers, schemas, and assets.

.output/
├── manifest.json          # Deployment descriptor
├── functions/
│   └── handler.js         # Bundled entry point that routes to each handler
└── public/                # Vite build output (if a SPA exists)
    ├── index.html
    └── assets/

What helix deploy does

1. Builds the project if it isn’t already built.
2. Uploads the function bundle, creating or updating the project’s runtime.
3. Uploads SPA assets for CDN delivery.
4. Registers triggers. Cron schedules are reconciled and staged disabled, then activated once the new code is live, so a failed deploy can’t leave a schedule firing against unpublished code (see scheduled functions).
5. Updates routing so function requests reach the new runtime.
6. Activates the deployment. Traffic switches to the new version.

On the first deploy, the CLI provisions the project, records its ID, and prints the project ID and live URL. It asks for a workspace if you haven’t set one.

Deploy options

# Deploy the project in the current directory
helix deploy

# Name the project on its first deploy, when it gets provisioned
helix deploy --name "Deal desk"

# Deploy a different target by naming its config file
helix deploy --config helix.production.config.ts

--name applies to the first deploy only, when the project is provisioned. Later deploys upload a new artifact to the project already named in the config file.

--config <path> selects the config file, and with it the deploy target, instead of the default ./helix.config.ts. Each target lives in its own config file pointing at its own workspace and project, so a deploy always lands where the file says. The HELIX_CONFIG environment variable has the same effect, which is handy in CI; the flag wins when both are set. See the configuration model and the deploy command reference.

Production URL and routing

Projects are served on their Helix app URL. All traffic arrives at the CDN on the project’s subdomain and routes by content type:

https://{project-id}.helix-app.ai/
├── /                      → SPA (index.html)
├── /about                 → SPA (client-side route)
├── /api/v1/users          → Function
└── /assets/main-abc123.js → Static asset (CDN)

Route priority matches the dev server:

1. Function routes. Exact match against the manifest’s route table, forwarded to the project’s runtime.
2. Static files. SPA assets served from the CDN cache.
3. SPA fallback. index.html for all unmatched paths.

The project ID URL is the address every project has, and it never changes. Once your organization has set a namespace, a project can also answer at a readable address such as https://invoices-acme.helix-app.ai, with the same routing and the same login. See project URLs.

Roll back

To restore a previous version, deploy again from an earlier commit of your project: a deploy always ships the complete bundle, so redeploying an older state fully replaces the current one.

How long previous deployments are kept

If your app is switched back to an older deployment, the newer deployments it replaced are also kept, so you can move forward again.

When a deployment expires, its bundle, the source it was built from, and its record are deleted. It disappears from the dashboard’s deployment history and from helix deployment get, and it cannot be recovered.