Hyphen
Log In

Hyphen Deploy Quickstart

Step-by-step guide to deploying local containerized and static applications to AWS, Azure, or Google Cloud using the Hyphen CLI and platform.

Deploy a local app folder, such as a Next.js app, to your own cloud. This guide starts after you have signed up and created your Hyphen organization.

You will need:

  • Your app's source files on your computer
  • Docker installed, available in your terminal, and running
  • 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 containerized apps on Amazon ECS, Azure Container Apps, and Google Cloud Run.

Table of Contents

App types

When you include an app in a deployment, choose its App Type. The deployment form does not choose one for you.

  • Static: files hosted by Hyphen. Hyphen assigns the URL automatically, so you do not select a cloud target.
  • 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:

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 deployment, the project needs a ready Container Registry and Cloud Workspace connection on every cloud your deployment targets:

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

You don't need to set these up ahead of time. You can select more than one cloud for the same deployment—for example AWS, Azure, and Google Cloud together. When you choose your Deploy to cloud targets while configuring your deployment below, Hyphen creates the project's registry and workspace for each targeted cloud automatically, or you can choose an existing connection instead. Connecting your cloud provider to the organization 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.

A Dockerfile is used if present. If one is missing, Hyphen Code can generate one during the build. See Builds for details, and Using ENV with Docker if your container needs Hyphen-managed secrets.

4. (Optional) Connect DNS Zone

For a custom hostname, connect your DNS zone in Settings → DNS → Add Zone. A configured hostname is required for deployment previews.

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 and choose the cloud targets, availability, and traffic regions. For each cloud target without a ready connection yet, Hyphen shows whether it will create a new container registry and cloud workspace for the project or you can switch to Use existing to select one already connected.
  3. Include your app under Apps in this deployment, then select its scale size. For a first deployment, start with the one local app you initialized.
  4. Optionally configure a hostname and path, or override the deployment defaults for that app.
  5. Select Save. Saving stores the configuration and starts creating any new connections you chose; it does not upload your local code or start a run.
  6. Select Deploy to review any missing requirements. Complete or retry the project connections and wait for them to be ready before running 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 example, to deploy the production environment in the project linked in .hx, use:

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.

The CLI builds your current local code, uploads the container image, and starts a deployment run. Follow the run using the dashboard link, then open the app URL from its deployed resources. A normal environment deployment does not automatically create a preview.

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 ready registry and workspace connections.

Next Steps