Hyphen
Log In

Hyphen Deploy Quickstart

Learn how to configure cloud providers and deploy containerized apps or static sites from your local machine using the Hyphen CLI.

Deploy a container app or static site from your local app folder. This guide requires a Hyphen account and organization.

You will need:

  • Your app's source files on your computer
  • Docker for a container build, or finished website files for a static build
  • Access to connect a cloud provider and configure a project in Hyphen

GitHub integration and a Git commit are not required for a local CLI build. You can add GitHub Actions later to deploy committed code automatically.

Hyphen Deploy supports container apps on Amazon ECS, Azure Container Apps, and Google Cloud Run. It supports static sites on Cloudflare Workers Static Assets.

Table of Contents

App types

Set the App Type for each app in the deployment:

  • Static: finished website files. Select Cloudflare Workers under Deploy to. The provider assigns a URL automatically.
  • Container: server-side code. Select a cloud under Deploy to and set the container deployment settings.

A deployment can include static apps, container apps, or both. The Object storage option applies to container apps only. Include a container app and select a cloud to enable it.

Use Copy CLI command to copy the hx deploy or hx build command for the deployment. If the deployment has missing requirements, the dialog shows build instructions for static and mixed deployments.

Setup

1. Connect your cloud provider

In the Hyphen app, open Integrations and connect your cloud provider:

A Cloudflare site requires the Cloudflare account setup described in its guide.

Follow the provider's setup instructions to grant Hyphen access. For AWS, also complete the distribution-list setup needed to create a cloud workspace.

2. Set up your project's cloud connections

Choose the project that will contain your app, or create one using + → Project. Use this same project throughout the guide.

For static sites, the project needs a ready Site Registry for each selected provider. Open the project's Settings → Integrations to check its connections. For Cloudflare, add a Site Registry there. Hyphen creates the private R2 bucket automatically. Static sites do not require a Container Registry or Cloud Workspace.

For container deployments, the project needs a ready Container Registry and Cloud Workspace on each target cloud:

  • Container Registry: stores the container images built from your code. A build uploads an image to every ready container registry on the project (one artifact per registry).
  • Cloud Workspace: provides the cloud workspace used for deployment.

For containers, you can select more than one cloud, such as AWS, Azure, and Google Cloud. When you select Deploy to targets, Hyphen can create the project's registry and workspace or use existing connections. The organization integration alone does not complete this project setup.

During a run, each cloud instance pulls only the image artifact whose target matches that cloud.

You can also review and manage these connections directly under the project's Settings → Integrations, or complete missing connections by selecting Deploy after saving your deployment configuration below.

3. Use the CLI to initialize your app

Install or update the Hyphen CLI (hx):

sh -c "$(curl -fsSL https://cdn.hyphen.ai/install/install.sh)"

powershell -c "irm https://cdn.hyphen.ai/install/install.ps1 | iex"

Use the current CLI release for the commands in this guide. Check your version with hx version and update an existing installation with hx update.

Open a terminal in your app's root folder—the folder containing its source files and, for a Next.js app, package.json. Sign in:

hx auth

Select the same organization and project you are configuring in the dashboard. If you need to change an existing selection, use hx set-org and hx set-project.

Link the current folder to an app in Hyphen:

hx init

Follow the prompts to select or create the app. The .hx file records the app, project, and organization for this folder. Initialization links the app; it does not build or deploy it.

For containers, Hyphen uses an existing Dockerfile or generates one during the build. For static sites, run your frontend build command to produce the website files before you use hx. See Builds for both build types, and Using ENV with Docker for container secrets.

4. (Optional) Connect DNS Zone

For a container app's custom hostname, connect your DNS zone in Settings → DNS → Add Zone. Static providers assign site URLs automatically. Cloudflare uses a workers.dev URL for each environment or preview.

Configure Your Project Environment Deployment Settings

Each deployment belongs to one project environment. Configuring development does not configure production.

  1. Open your project and select the environment you want to deploy.
  2. Select Create Deployment.
  3. Include your app under Apps in this deployment. For a first deployment, use the local app you initialized.
  4. Select Static or Container as its App Type.
  5. For a static app, select its providers under Deploy to. For a container app, set the cloud targets, scale, availability, and traffic regions.
  6. For each container target, select new project connections or Use existing. Optionally set a container hostname and path.
  7. Select Save. Hyphen stores the configuration and creates any new connections you selected. This step does not upload code or start a run.
  8. Select Deploy to check for missing requirements. Complete the project connections before you run the CLI command.

If you include multiple apps, each needs an uploaded build. A CLI run builds the app in the current folder and uses uploaded builds for the other included apps.

Deploy your app

  1. In the project overview, confirm the selected environment.
  2. Open the menu beside Deploy and select Copy CLI command. This action is also available on the deployment details page, before your first build exists.
  3. Run the copied command in the app folder initialized above.

For a container app, deploy the production environment in the project linked in .hx with:

hx deploy --env production

Use the command copied from your selected environment. It includes --env only when the environment's type isn't development; the organization and project come from your app folder's .hx file. Before running it, check that .hx links to the app and project you selected in the dashboard. --env accepts an environment ID or alternate ID; this example uses the alternate ID production.

For a container app, the CLI builds local code, uploads the image, and starts a deployment run. For a static site, supply the finished website directory:

hx deploy --env production --type static ./dist

Replace ./dist with your frontend output directory. The CLI uploads the files and starts the deployment. It does not run your frontend build command. Follow the dashboard link to view the run, then open the app URL from its deployed resources.

A normal environment deployment does not automatically create a preview. See Deployment Previews for the preview commands.

The dashboard's Deploy button uses builds that have already been uploaded. It cannot upload code from a folder on your computer.

Selecting an environment in the CLI

From an initialized app folder, deploy the current project's environment of type development with:

hx deploy

To select a specific environment in that project, use its alternate ID:

hx deploy --env production

Both commands use the project linked in .hx. To deploy an app in another project, run from that app's initialized folder. Without --env, hx selects the environment whose type is development; its name or alternate ID may be different. The browser selection does not change what a bare hx deploy selects. Use the copied command when you want the environment selected in the dashboard.

The CLI can create missing deployment configuration, but the project still needs the connections for its app types. For static sites, keep --type static and the output directory in the command.

Deploy Static and Container Apps Together

A deployment can include both app types. Each app needs a build with artifacts for its selected providers. Run the appropriate build command from each app's initialized folder:

# From the container app folder
hx build --env production

# From the static app folder, after the frontend build
hx build --env production --type static ./dist

# From an initialized folder in the same project
hx deploy --env production --no-build

To select specific apps or builds, use --apps for containers and --sites for static sites. See the CLI reference for examples.

Next Steps