# Hyphen AI > Hyphen is a developer infrastructure platform that generates cloud infrastructure with AI and continuously optimizes it. It includes deployment, environment and secrets management, feature flags, link shortening, and team access control. Source Index: https://hyphen.ai/llms.txt ## Products ### [Hyphen Agent | Infrastructure that improves itself](https://hyphen.ai/agent) Hyphen Agent continuously observes traffic, usage, and configuration patterns and safely acts in real time to operate and optimize your infrastructure while reducing operational overhead and cloud costs. ### [Hyphen CLI (hx) | Bring Hyphen to your terminal](https://hyphen.ai/cli) With the Hyphen CLI, spin up an app in seconds, configure your environments, manage secrets, and create short URLs — all from your command line. ### [Hyphen Deploy | Say Goodbye to Deployment Hell](https://hyphen.ai/deploy) Forget YAML files, Docker configs, Terraform, and Helm charts. With Hyphen Deploy, you define your target SLA, scale, and performance, and Deploy AI generates your cloud infrastructure automatically. ### [Hyphen ENV | Secrets Management Service](https://hyphen.ai/env) Manage secrets across your team and infrastructure with a fully auditable end-to-end encrypted secrets management service. ### [Horizon | Feature flag evaluation and env config on the edge](https://hyphen.ai/horizon) Horizon is a built-in ultra-low latency feature flag evaluation and environment config on the edge, or hosted on your own infrastructure. ### [Hyphen Link | Custom Short URL and QR Code Service](https://hyphen.ai/link) Create custom short URLs and QR codes using your own domain, and track performance with included analytics. ### [Hyphen net.info | City-level IP Geolocation API](https://hyphen.ai/net-info) Enable location-specific experiences, security, and analytics with city-level IP geolocation information, including latitude, longitude, time zone, postal code, and more. ### [Hyphen Team Smart Access | Automate access to your services and resources](https://hyphen.ai/smart-access) Automate team management and streamline access control across your services with integrations for cloud resources, code repos and team channels. ### [Hyphen Toggle | Feature Flags, Simplified](https://hyphen.ai/toggle) Ship smarter and faster. Toggle lets you roll out, test, and personalize features instantly. Open Feature Compatible and Enterprise-ready with a 99.95% SLA and ability to run locally with Horizon. ## Resources - [Hyphen AI vs Low-Code Platforms | Built for Developers](https://hyphen.ai/hyphen-vs-low-code): Discover why developers choose Hyphen AI over traditional low-code platforms. AI-powered infrastructure, code-first workflows, and multi-cloud deployment without the limitations of visual builders. - [Pricing | Hyphen AI](https://hyphen.ai/pricing): Explore Hyphen AI pricing. Pay only for what you use with transparent, usage-based pricing for deployments, feature flags, secrets management, and more. - [Changelog](https://hyphen.ai/docs/changelog): Latest updates and releases - [Help Center](https://help.hyphen.ai): Support and FAQs ## Documentation ### Welcome to Hyphen AI 👋 URL: https://hyphen.ai/docs/ Description: A step-by-step guide to getting started with Hyphen AI, from creating an account and organization to installing the Slack bot and setting up essential integrations. Create an account, setup your organization, install our bot, and setup your integrations! ## Create an Account and Organization 😄 If your company already is signed up then ask one of the administrators to send you an invite or they can invite you via the `@hyphen` bot on slack by typing "@hyphen can you please invite @YOUR\_SLACK\_ACCOUNT" and 💥 you will be invited! If this is the first time for your organization then go to [https://app.hyphen.ai](https://app.hyphen.ai) and go to the link to `register`. Simply fill out your user information such as email, first name, last name. After you do that you will be asked to fill out your organization information: ![](https://files.readme.io/fd99906059be37beef681dce28400994cc3fcb85ab7951e3c921bbed9ccf5108-Screenshot_2024-09-25_at_17.28.17.png) After entering this information you will need to put your companies credit card information in. Not to worry as we will not be charging your card right away. If you have questions on how we charge you can go to our [pricing page](https://hyphen.ai/pricing). > 📘 You will be sent an email to confirm your account so please remember to do that! ## Install our Bot into Slack 🤖 Now that you have an account and setup go to [https://app.hyphen.ai](https://app.hyphen.ai) and logon. From here you will see the dashboard page and the first task is to install our slack bot. 🎉 ![](https://files.readme.io/8dd0a5e99a96dd81c428100c4dae1ed24ad5a82a2505fdd5bc555c26ff5c130a-Screenshot_2024-09-25_at_17.34.08.png) Simply click on `Add To Your Slack` button and follow the integration steps to get it installed. We will talk more about how to use it below after you connect some of your services to us and watch the magic happen. ## Setup Your Integrations After you have setup the Hyphen bot you will now want to setup some integrations. This will enable Hyphen to setup access, create distribution lists, and slack channels for your teams. > 📘 It is recommended to connect your workspace such as `Google Workspace` or `Office 365`, `Github` organization, and at least one cloud provider such as `AWS`, `Google Cloud`, or `Azure`. For help with any of these integrations please go to the `Integrations` section on the left hand navigation. ## Watch the Magic Happen! 🪄 ### Organizations URL: https://hyphen.ai/docs/introduction/organizations/ Description: Understand how Hyphen Organizations serve as collaborative workspaces for managing projects, billing, and user access. In Hyphen, an Organization is a collaborative workspace where your team can manage multiple projects under a shared billing account. Organizations provide a central place to control project permissions, manage billing, and invite users to collaborate on one or more projects. Each project in Hyphen belongs to an organization, and users within an organization can collaborate across projects based on their assigned roles. ## Membership Each user in Hyphen has a personal account. Multiple personal accounts can collaborate within the same organization. Organization membership allows users to contribute to projects, access resources, and, depending on their role, manage the organization itself. ### Organization Owners Members can be assigned the Organization Owner role, which grants them control over the organization’s settings, billing, and user access. A member who creates a Hyphen organization is automatically assigned the org owner role. Owners can manage permissions for both the organization and individual projects, allowing them to tailor access for team members as needed. ### Roles and Access You can invite people to join your organization and assign them a role that grants different levels of access to the organization’s resources. Role assignments can be organization-wide or specific to individual projects: * **Organization-Level Roles**: These roles govern access to the organization’s settings, including billing and overall membership. * **Project-Level Roles**: These roles define what users can do within specific projects, such as managing secrets, configurations, or code repositories. ### Project-Based Access While organization-level roles define broad access, project-specific roles allow you to fine-tune access controls within individual projects. For example, you may want someone to contribute to a project without giving them full administrative access to the organization. For more information, see "[Projects](/docs/introduction/project)" In summary, organizations in Hyphen provide a structured, scalable way for teams to collaborate on projects with clear access control and billing management. You can invite team members, assign them the appropriate roles, and manage who has access to what across both the organization and individual projects. ### Projects URL: https://hyphen.ai/docs/introduction/project/ Description: Learn how to manage applications, environments, and secrets within Hyphen Projects, including understanding environment types and role-based access control. A Project in Hyphen is a container that groups related apps, environments, and secrets, allowing teams to manage them together under a unified workflow. Projects provide a way to organize and control access to multiple apps and their environments, ensuring that secrets and configurations are securely stored and accessible to the appropriate team members. Each project is linked to an [Organization](/docs/introduction/organizations-1) and can be accessed by users who have the appropriate permissions within that organization. ## Environments Within each project, you can define multiple Environments to segregate configurations and secrets specific to different stages of the app lifecycle. Each environment has a **type** that determines its role in the project: - **Development**: Used during the active development of an app. Secrets and configurations in this environment might include development-specific databases, API keys, and testing services. Each project can have at most one development environment. - **Production**: The live environment where the app runs in real-world use, with production-specific secrets and configurations. Each project can have at most one production environment. - **Custom**: For any specialized workflow that doesn't fit the development or production lifecycle stage. Projects can have multiple custom environments. Environments allow for flexibility and separation of concerns. Secrets and settings can be isolated per environment to ensure that, for example, development credentials do not affect the production system. Each environment maps to exactly **one deployment setting**. This one-to-one relationship means deployment behavior is fully predictable per environment — to deploy to multiple environments, create a separate deployment for each. ## Access Projects are managed using role-based access control (RBAC), which allows you to define what each team member can do within a specific project. This ensures that sensitive operations (like modifying production secrets) can only be performed by users with the appropriate permissions. ### Project Roles Project roles allow you to fine-tune access to different parts of a project, including the ability to view, modify, or manage secrets, apps, and environments. These roles may differ from organization-level roles, allowing flexibility in team collaboration. - **Project Owner**: Has full control over the project, including managing users, apps, environments, and secrets. The Project Owner can invite or remove members, modify project settings, and manage access to secrets and resources across all environments. - **Project Collaborator**: Can actively contribute to the project and manage apps, integration connections, project environments and work with secrets. However, a collaborator may not manage project access by adding or removing members. - **Project Viewer**: Can view the resources within a project, including apps, environments, but cannot view secrets or make any changes. This role is useful for team members who need to monitor the project without directly contributing. ### Custom Domain URL: https://hyphen.ai/docs/introduction/custom-domain/ Description: Learn how to add a custom domain to your Hyphen organization to create branded short links, enhancing brand recognition and trust. Includes setup instructions for DNS records and optional configurations for link not found redirects and auto-migration. Add a custom domain to your [Organization](organizations) so that you can create short links with a domain that reflects your brand. This boosts brand recognition and enhances public trust in your links. ## Prerequisites - You own or manage a custom domain and have access to its DNS settings. - Your Hyphen organization member account allows you to create a custom domain in your organization. - Your short link domain is different from your website, however you can use a subdomain. For example: | type | website | short link | | :-------- | :------- | :---------- | | subdomain | acme.com | go.acme.com |
## 1. Sign in to your DNS Sign in to your DNS provider's dashboard and access the DNS entries for the domain you plan to use with Hyphen's link URL shortening service. ## 2. Add DNS record ### For a subdomain Add a CNAME record with the following details. If you’re using a top-level domain and your provider doesn’t support CNAME records at the top level, follow the instructions for domains below. | Record Type | Hostname | Points | | :---------- | :---------------------------- | :---------------- | | CNAME | _\[replace with your domain]_ | link.hyphen.cloud |
## 3. Add your custom domain to Hyphen 1. [Sign in to your Hyphen account](https://app.hyphen.ai). 2. In the main navigation, select **Settings**. then choose **Domains**. ![Screenshot of Hyphen app showing where the Domains link is in the main navigation](https://files.readme.io/3bd58937bbce0cba39ffe15c1c901e6b7850c3d5f9d2ba7316fa2f24950dd17c-Screenshot_2025-08-15_at_8.41.16_AM.png)
1. Click the **Add Domain** button. 2. Enter your custom domain and select **Next**. 3. If you haven't already add the DNS records to point to Hyphen in your domain's DNS settings, sign in to your domain registrar and follow the [steps above](#2-add-dns-records). 4. Once you sure the DNS record(s) have been added, click the **Verify Domain** button. Your domain should be ready to use for branded short links within 5 minutes, as domain verification usually completes quickly. ## **4. Configure Link Not Found Redirect (Optional)** Hyphen will return a generic 404 Not Found page when a link code is not found for your domain. The “Link Not Found Redirect” setting allows you to set a custom redirect URL for your domain. Instead of serving the 404 page, Hyphen will redirect to this URL when the link code is not found. The behavior is as follows: - If a short link does not exist for your domain, users will be redirected to the “Link Not Found Redirect URL”, with the path sent as a query string property called “code” ``` https://notfoundurl.com/path/?code={code} ``` - If a Link Not Found Redirect URL is not set for your domain, users will see a generic 404 Not Found page. ### **Setting the Link Not Found Redirect** The custom redirect URL can be set when you add your domain and/or edited after the domain’s DNS has been verified. ### While adding a new domain 1. Navigate to **Settings > Domains > Add Domain** in your Hyphen account. 2. Enter a valid URL (must include `http` or `https`) in the Link Not Found Redirect field. 3. Save your changes. ![](https://files.readme.io/48a051689c7bcb690b4d93ac022f3d5a3ed59020d1e172426cafbf98e42adfc1-add-not-found.png) ### While editing an existing domain 1. Navigate to **Settings > Domains** in your Hyphen account. 2. Select the custom domain you want to configure. 3. Click on Edit ![](https://files.readme.io/d86850d4ee39fd00dfabf90de385081c9fb6f13627f600a17a5c4c4829b67228-Screenshot_2025-04-25_at_10.21.13_PM.png) ![](https://files.readme.io/eaea7b0b92925a7feb49566f056befcc7cceb15d637cf0991f7bd0bfa8afac91-edit-not-found.png) 4. Enter a valid URL (must include `http` or `https`) in the textbox. Delete the URL if you want to remove the redirect URL and use the generic 404 Not Found page. 5. Save your changes. ## **5. Configure Auto-Migration Template URL (Optional)** The Auto-Migration Template URL provides a seamless migration path from another URL shortening service to Hyphen. If the auto-migration URL returns a redirect, Hyphen will automatically create a new short link with the destination from the previous service. When a user requests a short link that isn’t found in Hyphen: - Hyphen will make a request to the Auto-Migration Template URL, replacing `{code}` in your template with the requested short link code. - If the fallback URL returns a redirect, Hyphen will automatically create a new short link using the destination from the fallback service, then redirect the user to that destination. - If no redirect is found, Hyphen will follow your configured Link Not Found Redirect behavior. > 🚧 A link will be created for any redirect response from the fallback URL. If you are using a service that has a custom 404, this should be turned off to prevent links being created for invalid codes. ### **Setting the Auto-Migration Template URL** You can configure the Auto-Migration Template URL when adding or editing a domain. ### While adding a new domain 1. Navigate to **Settings > Domains > Add Domain** in your Hyphen account. 2. Enter a valid URL template with the `{code}` tag (must include http or https) in the Auto-Migration Template URL field. 3. Save your changes. Example template: `https://legacy-shortener.com/{code}` ![](https://files.readme.io/d86850d4ee39fd00dfabf90de385081c9fb6f13627f600a17a5c4c4829b67228-Screenshot_2025-04-25_at_10.21.13_PM.png) ![](https://files.readme.io/00b9a1227cf58f9ca3ef32493847ffd48f3d9989f678d6cbb412f50b9b2aaac5-add-fallback.png) ### While editing an existing domain 1. Navigate to **Settings > Domains** in your Hyphen account. 2. Select the custom domain you want to update. 3. Click on **Edit** ![](https://files.readme.io/c3eba3a584475436f51cdef78834d2abc2f13a48e7ef69f25b42dca9adf98f9b-edit-fallback.png)
1. Enter a valid URL template with the `{code}` tag. 2. Save your changes.
> 📘 If `{code}` isn't included in the template, Hyphen will automatically append it to the end of the URL. ### Hyphen CLI URL: https://hyphen.ai/docs/introduction/cli/ Description: A comprehensive guide to installing, configuring, and using the Hyphen Command Line Interface (CLI) for managing applications, deployments, and environment variables. Hyphen CLI can be installed in macOS, Windows and Linux environments. In this guide, you will learn how to install and update command-line interface (CLI). ## Installation ```Text linux/macos sh -c "$(curl -fsSL https://cdn.hyphen.ai/install/install.sh)" ``` ```Text windows powershell -c "irm https://cdn.hyphen.ai/install/install.ps1 | iex" ``` ## Commands `hyphen` The root command for the Hyphen CLI. For convenience, the alias `hx` can be used in place of `hyphen` for all commands. > 📘 For convenience, the alias `hx` can be used in place of `hyphen` for all commands. Usage: ``` hyphen [command] hx [command] ``` ### Core Commands - `app`: Manage applications - `auth`: Authenticate with Hyphen - `build`: Build and upload a Docker image without deploying - `deploy`: Run a deployment - `entrypoint`: Generate or update the hyphen-entrypoint.sh script - `env`: Manage environments - `help`: List available commands, flags, and their descriptions - `init`: Initialize an app - `link`: Shorten a URL and optionally generate a QR code - `project`: Manage projects - `pull`: Retrieve and decrypt environment variables for a specific environment - `push`: Upload and encrypt environment variables for a specific environment - `set-org`: Set the organization ID - `set-project`: Set the project ID - `update`: Update the Hyphen CLI - `version`: Display the version of the Hyphen CLI ### Global Flags - `--org`: Organization ID (e.g., org_123) - `--proj`: Project ID (e.g., proj_123) - `--env`: Environment ID (e.g., env_12345) - `--yes`, -y: Automatically answer yes for prompts - `--no`: Automatically answer no for prompts ## Authentication Authenticate with Hyphen by entering the `hyphen auth` command. This will start the OAuth flow (opens a browser window and ask you to sign in with username and password) and save the credentials to your session. ``` hyphen auth ``` ### API Key Authentication If you are authenticating in a CI/CD environment and need to authenticate using an API key, you can do so in 2 ways: 1. Use API Key `--use-api-key` will look for the HYPHEN_API_KEY environment variable first and if not found it will prompt for the key. ``` hyphen auth -- use-api-key ``` 2. Set API Key `--set-api-key VALUE` will expect an inline value. The risk in using this method is just in exposing the secret in your terminal output, but it's provided for convenience. ``` hyphen auth --set-api-key VALUE ``` ## Commands ### `app` Manage applications. #### Subcommands - `create`: Create a new application in Hyphen - `get`: Get an app - `list`: List applications in your organization and project
### `app create` This command allows you to: - Create a new application with a specified name - Optionally provide a custom app ID or use an automatically generated one - Associate the new app with your current organization and project ``` hyphen app create [flags] ``` #### Flags - `-h, --help` Help for `app create` command - `--id, i`: App ID (optional)
### `app get` This command allows you to: - Fetch detailed information about a specific application - Use either the application name or ID as the identifier The command will display various details about the application, including: - Project information (ID and name) - Application details (name, alternate ID, and ID) - Organization information (ID and name) ``` hyphen app get [flags] ``` #### Flags - `-h, --help` Help for `app create` command
### `app list` List applications in your organization and project ``` hyphen app list [flags] ``` #### Flags - `-h, --help` Help for `app list` - `--page`: Page number (default 1) - `--page-size`: Number of results per page (default 10) - `--table`: Display results in a table format
### `auth` Starts the OAuth flow, opens a browser window for you to sign in with a username and password and saves the credentials to your session. ``` hyphen auth ```
### `build` Build and upload a Docker image to your project's container registry without deploying it. This command is useful for: - Testing your build process without triggering a deployment - Pre-building artifacts that can be deployed later - Verifying your Dockerfile and container registry configuration The build command performs the same build process as `hx deploy`, but stops after uploading the image to your container registry. ``` hyphen build [flags] ``` #### Flags - `--help, -h`: Help for `build` command #### Examples ``` hyphen build hx build ``` For more details about the build process, see [Builds](../deploy/builds).
### `deploy` Run a deployment by executing a project environment deployment. By default, the environment of type `development` will be deployed. This command builds your Docker image (unless `--no-build` is specified), pushes it to your container registry, and deploys your application according to the deployment configuration. ``` hyphen deploy [flags] ``` #### Flags - `--no-build`: Skip the build step and use the most recent build - `--help, -h`: Help for `deploy` command #### Examples ``` hyphen deploy my-deployment-policy hyphen deploy dpol_123456789 hx deploy --env production --no-build ``` For more information about deployments, see [Deployment Run Methods](../deploy/deployment-run-methods).
### `entrypoint` Generate or update the `hyphen-entrypoint.sh` script for Docker deployments. This script is normally created automatically when you run `hx init`, but this command allows you to: - Create the entrypoint script if it's missing (e.g., from having used an older version of `hx init`) - Update the script to the latest version - Regenerate the script if it was accidentally deleted or modified ``` hyphen entrypoint [flags] ``` #### Flags - `--force`: Overwrite existing entrypoint file - `--help, -h`: Help for `entrypoint` command
### `env` Manage environment .env secrets. #### Subcommands - `list`: List environment variables in Hyphen - `list-versions`: List versions of an environment in Hyphen - `pull`: Pull and decrypt environment variables from Hyphen - `push`: Push local environment variables to Hyphen - `rotate-key`: Rotate the encryption key and update all environments - `run`: Run your app with the specified environment #### Flags - `--enivoronment, -e`: Project Environment ID (e.g., pevr_12345) - `-h, --help` Help for `project list`
### `env list` The `env list` command displays environment variables stored in Hyphen for your current project. This command allows you to: - View all environments associated with your project - See key details about each environment, including ID, version, secret count, size, and publish date - Display results in either a detailed list format or a concise table format The information displayed for each environment includes: - ID: The unique identifier for the environment (default for the main environment) - Version: The current version number of the environment - Secrets Count: The number of secret variables stored in the environment - Size: The total size of the environment data - Published: The date and time when the environment was last published ``` hyphen env list [flags] ``` #### Flags - `-h, --help`: help for `env list` - `--page`: Page number (default 1) - `--page-size`: Number of results per page (default 10) - `--table`: Display results in a table format
### `env list-versions` The `env list-versions` command displays different versions of a specific environment stored in Hyphen for your current project. This command allows you to: - View all versions of a specific environment - See key details about each version, including ID, version number, secret count, size, and publish date - Display results in either a detailed list format or a concise table format The information displayed for each version includes: - ID: The unique identifier for the environment - Version: The version number of the environment - Secrets Count: The number of secret variables stored in this version - Size: The total size of the environment data for this version - Published: The date and time when this version was published ``` hyphen env list-versions [flags] ``` #### Flags - `-h, --help`: help for `env list` - `--page`: Page number (default 1) - `--page-size`: Number of results per page (default 10) - `--table`: Display results in a table format
### `env push` Encrypt and uploads local environment variables to Hyphen. This command allows you to: - Push all environments found in local .env files when no environment is specified - Push a specific environment by name - Encrypt and securely store your environment variables in Hyphen The command looks for .env files in the current directory with the naming convention `.env.[environment_name]`. ``` hyphen env push [flags] ``` #### Flags - `--environment, -e`: Specific environment(s) to push to (e.g. development, production, default) - `--help, -h`: Help for `push` command ### `env pull` Retrieves environment variables from Hyphen and decrypts them into local .env files. This command allows you to: - Pull a specific environment by name - Pull all environments for the application The pulled environments will be decrypted and saved as `.env.[environment_name]` files in your current directory. ``` hyphen env pull [flags] ``` #### Flags - `--environment, -e`: Specific environment(s) to pull from (e.g. development, production, default) - `--force`: Force overwrite of locally modified environment files - `--version`: Specify a version to pull - `--help, -h`: Help for `pull` command
### `env rotate-key` Rotates the encryption key and updates all environments with the new key. ``` hyphen env rotate-key [flags] ``` #### Flags - `--force`: Force overwrite of locally modified environment files - `-h, --help`: help for `env list`
### `env run` Executes your application with the specified environment variables. ``` hyphen env run [environment] -- [command] ``` #### Flags - `-h, --help`: help for `env list
### `help` List available commands, flags, and their descriptions ``` hyphen help ```
### `init` Initialize an app, which creates the `.hx`, `.hxkey`, and `hyphen-entrypoint.sh` files The `hyphen-entrypoint.sh` script is designed for use in Docker containers and automates the process of downloading the Hyphen CLI, authenticating with an API key, pulling environment variables, and running your application with those variables loaded. > **Note:** If the `hyphen-entrypoint.sh` is missing (e.g. because you ran `init` with an older version of hx) or needs to be updated, you can re-create it with `hx entrypoint` (and use `--force` if needed to overwrite it). ``` hyphen init [flags] ``` #### Flags - `--id, i`: APP ID (optional) - `--help, -h`: Help for `init` command #### Examples ``` hyphen init hyphen init "My New App" hyphen init "My New App" --id my-custom-app-id ```
### `link` Shorten a URL and optionally generate a QR code. ``` hyphen link [flags] ``` #### Flags - `--code`: Custom short code - `--domain`: The domain to use when shortening - `--qr`: Generate a QR code - `--tag`: Tag the shortened URL. - `--title`: The title for the shortened URL - `--help, -h`: Help for `link` command
### `project` Manage projects within your organization. #### Subcommands - `create`: Create a new project - `get`: Get a project - `list`: List projects in your organization
### `project create` This command allows you to: - Create a new project with a specified name - Automatically generate an alternate ID based on the project name The project name: - Can include spaces and special characters - Will be trimmed of leading/trailing spaces and quotes The alternate ID: - Is automatically generated from the project name - Contains only alphanumeric characters and hyphens - Replaces spaces with hyphens and removes other special characters After creation, you'll receive a summary of the new project, including its: - Name - ID (assigned by Hyphen) - Alternate ID (generated from the name) ``` hyphen project create [flags] ``` #### Flags - `-h, --help` Help for `project create` command
### `project get` This command allows you to: - Fetch detailed information about a specific project - Use either the project name or ID as the identifier The command will display the following details about the project: - Name: The project's full name - ID: The unique identifier assigned by Hyphen - AlternateID: The human-readable identifier generated from the project name ``` hyphen project get [flags] ``` #### Flags - `-h, --help` Help for `project get` command
### `project list` This command allows you to: - View all projects in your current organization - See key details of each project at a glance For each project, the command will display: - Name: The project's full name - ID: The unique identifier assigned by Hyphen - AlternateID: The human-readable identifier generated from the project name If no projects are found in your organization, you'll be informed accordingly. The projects are displayed in a list format, with each project's details separated by an empty line for better readability. **Note**: The list is fetched based on your current organization context. Ensure you're in the correct organization before running this command. ``` hyphen project list [flags] ``` #### Flags - `-h, --help` Help for `project list`
### `pull` Retrieves environment variables from Hyphen and decrypts them into local .env files. This command allows you to: - Pull a specific environment by name - Pull all environments for the application The pulled environments will be decrypted and saved as `.env.[environment_name]` files in your current directory. ``` hyphen pull [flags] ``` #### Flags - `--environment, -e`: Specific environment(s) to pull from (e.g. development, production, default) - `--force`: Force overwrite of locally modified environment files - `--version`: Specify a version to pull - `--help, -h`: Help for `pull` command
### `push` Encrypt and uploads local environment variables to Hyphen. This command allows you to: - Push all environments found in local .env files when no environment is specified - Push a specific environment by name - Encrypt and securely store your environment variables in Hyphen The command looks for .env files in the current directory with the naming convention `.env.[environment_name]`. ``` hyphen push [flags] ``` #### Flags - `--environment, -e`: Specific environment(s) to push to (e.g. development, production, default) - `--help, -h`: Help for `push` command
### `set-org` Set the organization ID in `.hx`. ``` hyphen set-org ``` #### Flags - `--global`: Set the org ID globally - `--help, -h`: Help for `set-org` command
### `set-project` Set the project ID in `.hx`. ``` hyphen set-project ``` #### Flags - `--global`: Set the project ID globally - `--help, -h`: Help for `set-project` command
### `update` Use `update` to get the latest version of the Hyphen CLI ``` hyphen update ```
### `version` Display the current version of the Hyphen CLI ``` hyphen version ```
### Horizon URL: https://hyphen.ai/docs/introduction/horizon/ Description: A comprehensive guide on how to self-host Horizon for fast, secure access to feature flags and secrets, including deployment on Google Cloud and Azure. Run Horizon in your environment and at the edge for fast, secure access to your feature flags and secrets. ## Self Hosting You can self-host instances of Horizon on your own infrastructure to add redundancy and reduce latency. When you self-host Horizon, start by creating an API key and grant it access to the projects you’ll run. Horizon uses this key to make calls to Hyphen, so it must have access for every project you require.
### Create an API Key Open the Hyphen Dashboard app and navigate to settings > API Keys ![](https://files.readme.io/991821c335692aefedf501dcc04e47035b052e325e9fd6a5570b6626c113fc05-Screenshot_2025-06-25_at_19.29.43.png) Create a new API Key, giving it `project collaborator` access to the projects that will be accessed through yourself hosted instance. Don't forget to save the secret some place safe as it will not be shown to you again. ![](https://files.readme.io/ff2b82a6654b03ba9e04944f026ed21210e399977f20f254124b80338805f9e0-Screenshot_2025-06-25_at_19.30.37.png) ### Environment Variables Horizon uses environment variables, some required and show not, that you may want to customize | Name | Description | Required | | :---------------- | :------------------------------------------------------------------------------------------------------------ | :------- | | API\_KEY | Used to authenticate with Hyphen services | Yes | | HYPHEN\_BASE\_URL | Hyphen may provide you with your own URL, if that is the case use this variable to adjust Horizon's behavior. | No | ### Local Docker This is useful for testing locally and making sure everything is working. You may use whatever port mapping you like. ```powershell docker run ` -e API_KEY={you_key} ` -p {pick_a_port}:3333 us-docker.pkg.dev/hyphenai/public/horizon:latest ` -t horizon ``` ```shell docker run \ -e API_KEY={you_key} \ -p {pick_a_port}:3333 us-docker.pkg.dev/hyphenai/public/horizon:latest \ -t horizon ``` ### Deploying to the cloud #### Google Cloud Open the cloud console and navigate to Cloud Run and then Create ![](https://files.readme.io/45fc61bddd0d0670d89e7cd70ff8d6363bf9edd67a853ee4688b03fb7d424331-Screenshot_2025-06-25_at_19.59.33.png) Make the Following Selections * Deploy using Artifact Registry / Docker Hub * use the container Image url of `us-docker.pkg.dev/hyphenai/public/horizon:latest` * Give the service a meaning, to you, name * Uncheck `Use IAM to authenticate incoming requests` ![](https://files.readme.io/c341a5c1893ed903d409e2aba7b2f15d8f1c91e7ef65f53dbdcfb4056dd25fc9-Screenshot_2025-06-25_at_19.54.22.png) Make the Following Selections * If you'd like to use a different port do so, but this is optional as Horizon respects the `$PORT` variable * Add the API key secret are an Environment Variable called `API_KEY` * Click Create #### Azure Container Apps Open the Azure portal and navigate to Container App and create a new one ![](https://files.readme.io/8e1b09246250803fde94ee1d087da91d14da994112cf2cadc79c529bdc1f9659-Screenshot_2025-06-25_at_20.07.10.png) Make the Following Selections * Choose the correct Subscription * Choose the correct Resource Group or create a new one * Choose the correct region * Choose an existing App Environment or create a new one * Click Next ![](https://files.readme.io/b106050b0b0e7043c839460697245d6f3c2b4f3af3d52d07daaf5755af26cb5d-Screenshot_2025-06-25_at_20.10.37.png) Make the Following Selections * Give The Container App a meaningful, to you, name * Select `Docker Hub or other registeries` * Image type is public * login server is `us-docker.pkg.dev` * Image and Tag is `hyphenai/public/horizon:latest` * Add an environment variable with the name `API_KEY` and the value of the API Key Secret you just created. * Click Next ![](https://files.readme.io/3cbf490ad201ad9b01059b83ae724a3563765754ae55506f82efe5a145e7f62a-Screenshot_2025-06-25_at_20.11.32.png) Make the Following Selections * Enable ingress * Accept traffic from anywhere * Target Port should be `3333` * Click Review + Create ### Hyphen Deploy Coming Soon, you'll be able to deploy Horizon directly with Hyphen Deploy! ### Configuring the SDK Configuring the SDKs is dependent on which SDK you are using. As such you should look at the documentation for the specific API. Bellow is an example of using the Hyphen Node SDK ```typescript const options = { publicApiKey: config.hyphenPublicKey, applicationId: '{YOUR_APP}', context: { targetingKey: 'anonymous', }, // this my also be the URL of a load balancer, balancing multiple instances uris: ['{URL_OF_YOUR_INSTANCE}'] }; const toggle = new Toggle(options); ``` ### Hyphen Deploy Quickstart URL: https://hyphen.ai/docs/deploy/deploy-quickstart/ Description: A quickstart guide to deploying containerized applications using Hyphen Deploy across AWS, Azure, and Google Cloud. > 🚧 At this time Hyphen Deploy supports containerized applications running on: > > - 🚧 Amazon Elastic Container Service (ECS) > - 🚧 Azure Container Apps > - 🚧 Google Cloudrun
Hyphen Deploy takes your source code and turns it into a running application in your own cloud with minimal setup. You define requirements such as SLA, traffic location, and response time, and Hyphen generates a deployment configuration that is secure, consistent, and aligned with best practices. The following cloud providers are currently supported: - [Amazon Web Services](../integrations/aws-integration) - [Google Cloud](../integrations/google-cloud-integration) - [Microsoft Azure](../integrations/azure-integration-setup-guide) ## Setup ### 1. Connect your cloud provider Sign into the Hyphen app with a member account that has the organization admin role. In the main navigation, select **Integrations**, then select your cloud provider of choice. Follow the instructions for connecting your cloud provider to your Hyphen org, which is typically just signing into the cloud provider with your user account, selecting an organization or tenant to connect to, and granting Hyphen the necessary permissions. Once connected, you can choose to connect to another cloud provider for multi-cloud load balanced deployments, or move on to the next step. ### 2. Create a container registry for your project A [Project](../introduction/project) in Hyphen is a container that groups related apps, environments, and secrets, allowing teams to manage them together under a unified workflow. Projects provide a way to organize and control access to multiple apps and their environments, ensuring that secrets and configurations are securely stored and accessible to the appropriate team members. Each project is linked to an Organization and can be accessed by users who have the appropriate permissions within that organization. #### For a new project In the Hyphen app, to create a new project: 1. Click the "+" button in the header of the UI, and select **Project**. 2. Enter a name (e.g. `my-first-project`) 3. Under **Project Integrations** , check the container registry box to create a container registry in your organization's cloud. This is where build artifacts (e.g., Docker images) will be stored after being generated by the Hyphen Deploy build step. 4. Your new project will be created with the default environments of `development` and `production`. #### For an existing project If you have an existing project without a container registry: 1. Navigate to the Project overview. 2. Under **Integration Connections**, click the **+** button next to **Container Registry**. 3. Check the **Container Registry** box to create one in the cloud of your choice. 4. Select **Connect Project Container Registry** to finalize. ### 3. Use the CLI to initialize your app The Hyphen CLI (`hx`) is a command-line tool for running Hyphen commands locally from your terminal. #### Install the CLI For linux/macos ```bash sh -c "$(curl -fsSL https://cdn.hyphen.ai/install/install.sh)" ``` For windows ```powershell powershell -c "irm https://cdn.hyphen.ai/install/install.ps1 | iex" ``` #### Authenticate with Hyphen Authenticate by running: ```bash hx auth ``` This starts the OAuth flow (opens a browser window, prompts you to sign in, and saves the credentials to your session). #### Set the project and initialize your app Set your project context: ```bash hx set-project ``` In the terminal, `cd` into the root directory of the app you want to deploy, then run ```bash hx init ``` This initializes your app with Hyphen and creates the `.hx` file and `.env` files for each environment. #### Docker Containerization If you're deploying a containerized application, `hx init` also creates a `hyphen-entrypoint.sh` script that automates environment variable management for your Docker containers. This script handles: - Downloading the Hyphen CLI if not already present - Authenticating with your Hyphen API key - Pulling environment variables for the specified environment - Running your application with those variables loaded To use it in your Dockerfile: ```dockerfile # Copy Hyphen configuration COPY hyphen-entrypoint.sh ./hyphen-entrypoint.sh RUN chmod +x ./hyphen-entrypoint.sh # Use as entrypoint ENTRYPOINT ["./hyphen-entrypoint.sh"] CMD ["npm", "run", "start"] ``` When running your container, provide these environment variables: - `HYPHEN_API_KEY`: Your Hyphen API key - `HYPHEN_APP_ENVIRONMENT`: The environment name (e.g., "production") - `HYPHEN_APP_ID`: Your application ID (from `.hx` file) - `HYPHEN_PROJECT_ID`: Your project ID (from `.hx` file) - `HYPHEN_ORGANIZATION_ID`: Your organization ID (from `.hx` file) ### 4. (Optional) Connect DNS Zone If you are deploying a service that will be accessible on the internet, add your DNS zone to manage the required DNS resource records automatically. 1. Navigate **DNS** under the **Settings** section in the left navigation. 2. Click **Add Zone** in the top left. 3. Select your DNS Provider from the list of connected Integrations. 4. Follow the next steps to select your zone from the provider. ## Configure Your Project Environment Deployment Settings Each deployment is scoped to a single project environment. So in order to deploy both development and production, each environment will need to be configured and deployed. Back in the Hyphen app: 1. Navigate to the project containing the app(s) you want to deploy. By default, the `development` environment is selected. Click the **Create Deployment** button to configure the environment's deployment settings. 2. In **Deployment Settings**, choose the default deployment target or targets (e.g. Microsoft Azxure), availability tier, and traffic region or regions for this environment. These settings apply to all apps in the deployment unless you override them for a specific app. 3. Under **Apps in this deployment**, turn on each app you want to include in the deployment. [Learn more about environment variables or secrets if your build requires them.](/docs/env-secrets-management/env-secrets-management) 4. For each included app, configure the app-specific settings: - Select the scale size. - Optionally configure a hostname by entering a subdomain, selecting a domain, and adding a path. A hostname is required if you will be using [deployment previews](/docs/deploy/deployment-previews). - If needed, enable **Customize cloud target, availability and traffic region for this app** to override the deployment defaults for that app. 5. Optionally add a description for the deployment. 6. Select **Save** to save your deployment. Repeat this process to create a separate deployment for each additional environment (e.g. `production`). ## Deploy your app Now that you've created a deployment, it's time to build and package your app for deployment. Back in the terminal run to build and deploy your app. ```bash hx deploy ``` The ID of the deployment is available in the url when looking at the deployment detail. While the run is in progress the CLI shows each build, release, and verification step in the order they are executed. When the deployment finishes you will receive a link to the generated preview environment as well as the run ID, which you can use to inspect logs in the Dashboard or reference the run from follow-up automation. When deployment finishes, you'll get a link to access your running app. ## Next Steps - [Learn about builds](builds) including Dockerfile auto-generation and build triggers - [Understand environment variables](environment-variables) available in your deployed application - [Set up GitHub Actions](github-action) to automate your deployments - [Explore deployment run methods](deployment-run-methods) for different ways to trigger deployments ### Builds URL: https://hyphen.ai/docs/deploy/builds/ Description: Learn how Hyphen automatically builds Docker images, pushes them to your container registry, and deploys your application, including details on the build process, triggers, and requirements. When you deploy your application with Hyphen, the platform automatically builds your Docker image, pushes it to your project's container registry, and deploys it to your cloud infrastructure. This streamlined process ensures that your latest code changes are packaged consistently and securely deployed. ## How Builds Work Builds in Hyphen Deploy are triggered when you run a deployment or manually with the `hx build` command. The build process happens locally on your machine or in your CI/CD environment, then the resulting Docker image is pushed to your project's container registry in your cloud provider. When you run `hx deploy`, Hyphen: 1. Locates your Dockerfile in the repository 2. If no Dockerfile exists, Hyphen Code generates one automatically based on your application's code 3. Builds a Docker image using your Dockerfile 4. Inspects the image to detect exposed ports 5. Authenticates with your project's container registry 6. Pushes the image to the registry with appropriate tags 7. Registers the build with Hyphen and proceeds with deployment The entire build process is tracked and logged, so you can monitor progress and troubleshoot any issues that arise. ## Build Process Details ### Finding Your Dockerfile Hyphen automatically searches your repository for a `Dockerfile`. If no Dockerfile is found, Hyphen Code will automatically generate one for you based on your application's code and dependencies. The generation process: - Analyzes your codebase and detects the programming language, framework, and build system - Creates an optimized Dockerfile tailored to your application - Saves the generated Dockerfile and .dockerignore locally (allowing you to review before committing) ### Building the Docker Image The Docker build process uses your Dockerfile to create a container image. Hyphen builds images targeting the `linux/amd64` platform by default, ensuring compatibility with the most common cloud container services including AWS ECS, Azure Container Apps, and Google Cloud Run. The image is tagged with your app name and the current Git commit SHA (shortened to 7 characters), making it easy to track which code version is deployed. ### Port Detection After building the image, Hyphen inspects it to automatically detect which ports your application exposes. This information is used to configure networking and load balancing when your application is deployed. Ports are detected from the `EXPOSE` directive in your Dockerfile. ### Pushing to Container Registry Once built, the image is pushed to your project's container registry. Hyphen handles authentication automatically, logging in with the credentials configured when you set up your container registry integration. The image is tagged appropriately for your registry type: - **AWS ECR**: Uses `:` as the separator with tag format `registry:image-tag` - **Azure ACR**: Uses `/` as the separator with tag format `registry/image:tag` - **Google Artifact Registry**: Uses `/` as the separator with tag format `registry/image:tag` After the push completes, Hyphen logs out of the registry to avoid leaving credentials in your local Docker configuration. ### Registering the Build Builds are associated with a specific environment (e.g., development, production) or available to all environments. When you run a deployment, Hyphen automatically uses the latest build for that environment. Additional metadata is recorded with each build: - The container image URI - Exposed ports - Git commit SHA - Build timestamp - Associated app and environment This build record can be viewed in the Hyphen Dashboard and is used to track your deployment history. ## Build Triggers Builds can be triggered in several ways: ### Via CLI When you run `hx deploy` from your terminal, Hyphen builds your Docker image locally before initiating the deployment. The CLI streams build progress to your terminal, making it easy to monitor and debug. ```bash hx deploy ``` For more details on using the CLI for deployments, see [Deployment Run Methods](deployment-run-methods#cli). ### Via GitHub Actions When you use GitHub Actions to automate your deployments, the build happens in the GitHub Actions runner environment. The `Hyphen/setup-hx-action` installs the Hyphen CLI, which then builds your Docker image as part of the workflow. For a detailed guide on setting up automated deployments with GitHub Actions, see [GitHub Actions Deployment](github-action). ## Container Registries Build artifacts (Docker images) are stored in your project's container registry. This registry is created in your connected cloud provider and is dedicated to your project. Each project needs a container registry configured before you can deploy. If you haven't set up a container registry yet, see the [Deploy Quickstart](deploy-quickstart#2-create-a-container-registry-for-your-project) guide. ## Requirements Before running a build, ensure you have: - Docker installed and available in your PATH - A container registry configured for your project - Successfully run `hx init` to initialize your app A Dockerfile is not required but will be used if present. If not, Hyphen Code will generate one automatically. ## Skipping Builds If you want to deploy a previously built image without rebuilding, you can use the `--no-build` flag: ```bash hx deploy --no-build ``` This is useful when you want to: - Redeploy the same build to a different environment - Retry a failed deployment without rebuilding - Test deployment configuration changes without code changes When using `--no-build`, Hyphen will use the most recent build for your app. ## Standalone Builds You can also build and upload a Docker image without immediately deploying it using the `hx build` command. This is useful for testing your build process or preparing artifacts ahead of deployment. For more information about the build command, see [CLI documentation](../introduction/cli#build). ## Next Steps - [Deploy an environment](deploy-quickstart#create-a-deployment-policy) to deploy your built images - [Set up GitHub Actions](github-action) to automate your build and deployment process - [Learn about deployment run methods](deployment-run-methods) to understand different ways to trigger deployments ### Deployment Run Methods URL: https://hyphen.ai/docs/deploy/deployment-run-methods/ Description: Learn the different methods for running deployments on Hyphen, including Git integration, CLI, REST API, and the Dashboard. A deployment run on Hyphen is the act of running a specific deployment configuration. Each time you run a deployment, Hyphen will return a unique URL so that you and your team can preview changes in a live [environment](../introduction/project/#environments). ## GitHub The most common way to run a deployment is by pushing code or opening a pull request to a Hyphen-connected Git repository. When you import a Git repository to Hyphen, you can setup an action so that each commit or pull request automatically triggers a deployment run. You can also create deployments from a Git reference using the Hyphen Dashboard if you need to deploy specific commits or branches manually. For a detailed guide on setting up GitHub Actions workflows to automate deployments, see [GitHub Actions Deployment](github-action). ## CLI Use the Hyphen CLI (`hx`) when you want to launch a deployment run directly from your terminal or a custom automation script. The CLI packages the code that is currently checked out locally, builds the artifacts that your deployment expects, and streams status updates until the run completes. For details on the build process, see [Builds](builds). ```bash hx deploy ``` Run the command from the repository root that was initialized with `hx init`. Replace `` with either the ID or the name of the deployment you want to execute. The CLI authenticates using the credentials saved during `hx auth`. If you are authenticating in a CI/CD environment and need to authenticate using an API key, you can do so in 2 ways: 1. **Use API Key** `--use-api-key` will look for the HYPHEN_API_KEY environment variable first and if not found it will prompt for the key. ``` hyphen auth -- use-api-key ``` 2. **Set API Key** `--set-api-key VALUE` will expect an inline value. The risk in using this method is just in exposing the secret in your terminal output, but it's provided for convenience. ``` hyphen auth --set-api-key VALUE ``` While the run is in progress the CLI shows each build, release, and verification step in the order they are executed. When the deployment finishes you will receive a link to the generated preview environment as well as the run ID, which you can use to inspect logs in the Dashboard or reference the run from follow-up automation. ## REST API Hyphen also exposes a REST API for triggering deployment runs programmatically. This is useful when you need to integrate deployments into an external build system, ticketing workflow, or release orchestration tool. Create a run by sending an authenticated `POST` request to `/api/organizations/{organizationId}/deployments/{deploymentId}/runs`, using the deployment ID shown on the Deployment Policy detail page. The request body is optional; include it when you want to pin the run to specific build artifacts. Each artifact entry must provide an `appId` and either a `buildId` (to reuse an existing Hyphen build) or a published container image reference: ```bash curl -X POST "https://api.hyphen.ai/api/organizations/$HYPHEN_ORG/deployments/$DEPLOYMENT_ID/runs" \ -H "Authorization: Bearer $HYPHEN_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "artifacts": [ { "appId": "app_123", "buildId": "ab_456" }, { "appId": "app_789", "artifact": { "type": "Docker", "image": { "uri": "gcr.io/my-project/custom-image:latest" } } } ] }' ``` The response contains the deployment run record, including its ID, current status, pipeline steps, and preview URL. Follow-up calls to `GET /api/organizations/{organizationId}/deployments/{deploymentId}/runs/{runId}` return the latest status, and `PUT /api/organizations/{organizationId}/deployments/{deploymentId}/runs/{runId}/status` (body `{ "status": "canceled" }`) lets you cancel a run that is still in progress. ## Dashboard For ad-hoc deployments you can start a run directly from the Hyphen Dashboard: 1. Navigate to **Deploy** → **Deployment Policies**, then choose the policy you want to execute. 2. Select **Run latest build** and the latest build be used in the deployment run. 1. To run a previous build, open the dropdown menu and select **Run previous build...** 2. Select the **Deploy** button to the corresponding with the commit SHA you want to deploy 3. Confirm the run to queue it. The status panel updates in real time and links to the preview environment once the deployment completes. Dashboard-triggered runs behave the same way as runs started from Git pushes, the CLI, or the API—they appear in the deployment history, emit events, and reuse the configuration defined by the project environment deployment settings. ![](https://files.readme.io/3a47b30178949c92fa0ebece784e8cea1b8e5ad0c7b3c12ac5cf47c664a70c19-deployment-run1.jpeg)
### GitHub Actions Deployment URL: https://hyphen.ai/docs/deploy/github-action/ Description: Automate your application deployments to development and production environments using GitHub Actions and the Hyphen CLI. This guide covers setting up secrets, workflow examples, and how deployments work. Automate your application deployments using GitHub Actions and the Hyphen CLI. This guide shows you how to set up CI/CD workflows that deploy to development when merging to main, and to production when creating releases. ## Prerequisites Before setting up GitHub Actions deployment, ensure you have: - Completed the initial Hyphen setup (see [Deploy Quickstart](deploy-quickstart)) - Connected your cloud provider to Hyphen - Created a container registry for your project - Initialized your app locally with `hx init` (the `.hx` file should be checked into your repository) - Configured deployment settings for the project environment you wish to deploy. - A Hyphen API key with appropriate permissions for deployment A Dockerfile will be used if present, and if not, Hyphen Code will generate one automatically. See [Builds](builds) for more details. ## Setting up GitHub Secrets Add your Hyphen API key to your repository's secrets: 1. In your GitHub repository, go to **Settings** > **Secrets and variables** > **Actions** 2. Click **New repository secret** 3. Name: `HYPHEN_API_KEY` 4. Value: Your Hyphen API key from the Hyphen App 5. Click **Add secret** ## Workflow Example This workflow deploys to development when a PR is merged to main, and to production when a release is created. ```yaml name: Deploy Application on: push: branches: - main release: types: [created] jobs: deploy-dev: name: Deploy to Development if: github.event_name == 'push' && github.ref == 'refs/heads/main' runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v4 - name: Setup Hyphen CLI uses: Hyphen/setup-hx-action@v1 with: apiKey: ${{ secrets.HYPHEN_API_KEY }} - name: Run tests run: | # Add your test commands here # npm test # pytest echo "Running tests..." - name: Deploy to Development run: hx deploy deploy-prod: name: Deploy to Production if: github.event_name == 'release' runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v4 - name: Setup Hyphen CLI uses: Hyphen/setup-hx-action@v1 with: apiKey: ${{ secrets.HYPHEN_API_KEY }} - name: Run tests run: | # Add your test commands here # npm test # pytest echo "Running tests..." - name: Deploy to Production run: hx deploy ``` ## Action Inputs The `Hyphen/setup-hx-action` supports the following inputs: | Input | Required | Description | Default | | ------------ | -------- | ------------------------------- | ------- | | `apiKey` | Yes | Your Hyphen API key | - | | `version` | No | Specific CLI version to install | Latest | | `hyphen-dev` | No | Use development environment | `false` | ### Example with Specific CLI Version ```yaml - name: Setup Hyphen CLI uses: Hyphen/setup-hx-action@v1 with: apiKey: ${{ secrets.HYPHEN_API_KEY }} version: 0.10.1 ``` ## How It Works When you run `hx deploy ` in your GitHub Actions workflow: 1. The Hyphen CLI builds your Docker image (Hyphen Code generates a Dockerfile automatically if none exists) 2. The image is pushed to your project's container registry (configured during setup) 3. The application is deployed to your cloud provider according to the project environment deployment settings 4. Build, release, and verification steps are executed For details on the build process, including Hyphen Code's Dockerfile auto-generation, see [Builds](builds). ## Next Steps - [Learn more about Deployment Policies](deploy-quickstart#create-a-deployment-policy) - [Understand the build process](builds) including Dockerfile auto-generation - [Manage environment variables](environment-variables) in your deployments - [Explore CLI commands](../introduction/cli) - [Set up environment variables and secrets](../env-secrets-management/using-env-with-docker) ### Environment Variables URL: https://hyphen.ai/docs/deploy/environment-variables/ Description: Understand how Hyphen Deploy manages environment variables, including system-injected HYPHEN_ variables and user-defined ENV Secrets for application configuration and sensitive data. Hyphen Deploy provides your application with environment variables at runtime. These include system-injected variables that provide deployment context and metadata, as well as user-defined secrets that you manage through Hyphen's ENV service. ## HYPHEN\_ System Variables Hyphen automatically injects environment variables prefixed with `HYPHEN_` into your application at runtime. These variables provide deployment metadata and context that your application can use for logging, monitoring, feature flagging, or environment-specific behavior. The following variables are automatically available to your application: | Variable | Description | Example Value | | --------------------------- | ------------------------------------------------------------------- | ----------------------------------------------------- | | `HYPHEN_API_KEY` | Hyphen API key for the deployment | `a2i...Q==` | | `HYPHEN_APP_CLOUD` | The cloud provider where your app is deployed | `googleCloud`, `aws`, `azure` | | `HYPHEN_APP_ENVIRONMENT` | The deployment environment name | `development`, `production` | | `HYPHEN_APP_ID` | Unique identifier for your application | `app_1a2b3c4d5e6f7g8h9i0j1k2l` | | `HYPHEN_APP_IMAGE` | Full container image reference used for this deployment | `us-docker.pkg.dev/my-project/my-repo/my-app:a1b2c3d` | | `HYPHEN_APP_IMAGE_LOCATION` | Cloud provider hosting the container registry | `googleCloud`, `aws`, `azure` | | `HYPHEN_APP_NAME` | Human-readable name of your application | `my-app` | | `HYPHEN_APP_REGION` | Geographic region where your app is deployed | `NorthAmerica-1`, `Europe-1` | | `HYPHEN_DEPLOYMENT_ID` | Unique identifier for the deployment policy | `dply_2b3c4d5e6f7g8h9i0j1k2l3m` | | `HYPHEN_DEV` | Flag indicating if running in development mode (only set when true) | `true` | | `HYPHEN_ORGANIZATION_ID` | Unique identifier for your organization | `org_3c4d5e6f7g8h9i0j1k2l3m4n` | | `HYPHEN_ORGANIZATION_NAME` | Name of your organization | `My Organization` | | `HYPHEN_PROJECT_ID` | Unique identifier for your project | `proj_4d5e6f7g8h9i0j1k2l3m4n5o` | | `HYPHEN_PROJECT_NAME` | Name of your project | `my-project` | | `HYPHEN_REVISION_DATE` | Timestamp when this revision was deployed (ISO 8601) | `2025-01-15T14:30:00.000Z` | | `HYPHEN_RUN_ID` | Unique identifier for this deployment run | `depr_5e6f7g8h9i0j1k2l3m4n5o6p` | These variables are managed by Hyphen. You cannot modify or override them. ## ENV Secrets In addition to the system-injected HYPHEN\_ variables, you can define your own environment variables and secrets using Hyphen's ENV service. These are the variables you manage with the `hx push` and `hx pull` commands. ENV Secrets are: - **User-defined**: You control which variables exist and their values - **Encrypted**: Stored securely with end-to-end encryption - **Environment-specific**: Different values for development, production, etc. - **Version-controlled**: Track changes and roll back if needed - **Automatically loaded**: Injected into your application at runtime alongside HYPHEN\_ variables Common use cases for ENV Secrets include: - API keys and tokens - Database connection strings - Third-party service credentials - Feature flags - Application configuration ### Managing ENV Secrets To work with ENV Secrets, use the Hyphen CLI: ```bash # Push local .env files to Hyphen hx push # Pull encrypted variables from Hyphen hx pull # Push a specific environment hx push --environment production ``` ENV Secrets are stored in `.env.[environment_name]` files locally (e.g., `.env.development`, `.env.production`) and synchronized with Hyphen's secure storage. For detailed information about managing ENV Secrets, see: - [ENV Secrets Management](../env-secrets-management/env-secrets-management) - [Using ENV with Docker](../env-secrets-management/using-env-with-docker) - [Rotating Encryption Keys](../env-secrets-management/rotating-an-encryption-key) ## Accessing Variables in Your Application All environment variables (both HYPHEN\_ system variables and your ENV Secrets) are available through your programming language's standard environment variable access mechanisms: **Node.js:** ```javascript const appId = process.env.HYPHEN_APP_ID; const apiKey = process.env.MY_API_KEY; ``` **Python:** ```python import os app_id = os.environ.get('HYPHEN_APP_ID') api_key = os.environ.get('MY_API_KEY') ``` **Go:** ```go import "os" appID := os.Getenv("HYPHEN_APP_ID") apiKey := os.Getenv("MY_API_KEY") ``` ## Variable Precedence > **Warning:** If you define an ENV Secret with the same name as a `HYPHEN_` system variable, your ENV Secret will override the system variable. This may cause unexpected issues with deployment metadata and application behavior. We recommend not creating ENV Secrets that start with `HYPHEN_`. ## Best Practices - **Use HYPHEN\_ system variables** for deployment context, logging, and monitoring - **Use ENV Secrets** for sensitive data like credentials and API keys - **Never commit secrets** to version control (add `.env.*` files to `.gitignore`) - **Use different values** for different environments (development, staging, production) - **Rotate credentials regularly** using Hyphen's key rotation features ## Next Steps - [Learn about ENV Secrets Management](../env-secrets-management/env-secrets-management) - [Understand the build process](builds) - [Set up GitHub Actions deployment](github-action) - [Explore deployment run methods](deployment-run-methods) ### Deployment Previews URL: https://hyphen.ai/docs/deploy/deployment-previews/ Description: Learn how to create and manage deployment previews with Hyphen, enabling isolated environments for testing and review with unique URLs and real cloud infrastructure. ## What you get - A unique preview URL that you can set that is ready to share with teammates and reviewers - Real infrastructure in your cloud, created from your project environment deployment settings - Runtime context variables injected into your app (app ID, environment, run ID, cloud, etc.) - When a preview is deleted, the Hyphen Agent handles cleanup of cloud resources based on applicable retention policy --- ## Core concepts ### Deployment run A deployment run is the execution of a project environment deployment for a specific revision. ### Project environments Projects group apps, environments, and secrets. Environments (like `development` and `production`) isolate config and secrets per lifecycle stage. ### Deployment policies Deployment policies define what gets deployed, where it runs, and how it scales. Each policy is scoped to a single project environment — there is a one-to-one relationship between environments and deployment policies. You configure policies in the Hyphen app as part of setup. --- ## Prerequisites 1. A cloud provider connected to your Hyphen organization 2. A project container registry configured 3. [Your app initialized](/docs/deploy/deploy-quickstart#3-use-the-cli-to-initialize-your-app) with the CLI (`hx init`) and the `.hx` file committed 4. [Project environment deployment settings](/docs/deploy/deploy-quickstart#create-a-deployment-policy) are configured All of the above can be achieved by following the [Hyphen Deploy Quickstart](deploy-quickstart) ---
## Creating a Deployment Preview Hyphen supports multiple ways to trigger deployment runs. ### Option 1: Use the CLI Hyphen Deployment Previews let you create isolated environments for branches, pull requests, or temporary testing. Using the CLI, you can: - Build an artifact associated with a preview - Deploy that build to a preview environment - Reuse an existing build for future deployments #### Step 1: Build with a Preview Label Use the `--preview` flag when building to associate the build with a preview name. ```bash hx build --preview ``` Example ``` hyphen build --preview "PR-200" ``` This command: - Builds your application - Uploads the artifact to your artifact registry - Tags the build with the preview name > 📘 **Important ** > > 📘 This step does not create the preview environment yet. > > 📘 The preview name is stored with the build so it can be used later during deployment. > > 📘 Builds tagged with a preview can be deployed to your production deployment. #### Step 2: Create a Deployment Preview To create a preview, you must give the preview a name and a **host prefix**. The prefix gets pre-pended to the deployments existing hostname. ``` hx deploy --preview --prefix ``` Example ``` hx deploy deploy-to-dev --preview "PR-200" --prefix pr200 ``` Example preview url would be: `https://pr200-my-app.demo.com` Hyphen will: - Create the preview - Look for builds associated with that preview - Start a deployment run #### Step 3: Reuse an Existing Build If a build already exists for the preview, you can skip building again using `--no-build`. ``` hx deploy deploy-to-dev --preview "PR-200" --no-build ``` ### Option 2: In the Hyphen App To create deployment previews in the Hyphen app: 1. Navigate to **Deploy** → then choose the policy you want to create a preview for. 2. Open the dropdown menu labeled **production**, then select **New Preview...** ![](https://files.readme.io/be3fc8b3cc55e70b3324893c29406140a499efe65a4dd0fe9c697a0819070f82-Screenshot_2026-03-05_at_2.06.12_PM.png) 3. Give your new preview a name and host prefix and select **Create** ![](https://files.readme.io/3dcdf1ef61995bcf7a2e73c4c2b6104953e386c1321d4a9b6a5fb078a3d2f503-Screenshot_2026-03-05_at_2.07.12_PM.png) 4. You're new deployment preview is now selected and ready to be deployed. Click the **Deploy Preview** button, which will take you to a list of app builds that are available to deployed. 5. Select the build to deploy and your deployment run will begin. ### ENV Quick Start URL: https://hyphen.ai/docs/env-secrets-management/env-secrets-management/ Description: A quick start guide to setting up and using Hyphen's ENV service for secure secrets management with end-to-end encryption. ENV is Hyphen’s built-in secrets management service, designed with end-to-end encryption to ensure the highest level of security for your sensitive data. Hyphen never has access to your secret values or your encryption key at any point, ensuring that only you and your team can view or manage your secrets. Your data is always stored fully encrypted, and Hyphen never sees or generates the encryption keys. These keys are created locally on your machine as 256-character long random strings. The encryption keys are used in conjunction with OpenSSL’s AES-256-CBC symmetric encryption cipher to keep your data fully encrypted at all times. ## Prerequisites Before getting started with ENV service, ensure you have: - Signed up for a Hyphen account and have access to an organization ## Install the CLI To get started, download and install the Hyphen CLI using the following command: macOS/Linux ```Text bash sh -c "$(curl -fsSL https://cdn.hyphen.ai/install/install.sh)" ``` Windows ```Text powershell powershell -c "irm https://cdn.hyphen.ai/install/install.ps1 | iex" ``` ## Sign in to your Hyphen Account After installation, sign in to your Hyphen account by running: ```Text bash hx auth ``` This will open a browser window to log in. If the window doesn’t open, copy and paste the URL from the terminal into your browser. ## Initialize your project To start using Hyphen ENV with your app, you need to initialize the app and set up encryption keys. This step creates a record of the app within your Hyphen organization and stores the secret encryption key on your machine in a `.hxkey` file. Navigate to your app’s directory and run: ```Text bash hx init ``` You will receive a confirmation message indicating that the app has been successfully initialized, similar to the following: ```Text bash App successfully initialized App Name: quick-start-app App AlternateId: quick-start-app App ID: app_6709694e54fc37367966d0ce Organization ID: org_66f30abb67ebc6bb0c5e0af7 ``` ## Manage Your .env Files Once initialized, Hyphen will create several .env files in your app’s directory. Use these files to store environment-specific secrets: ## Encrypt and Push Secrets to Hyphen Once you’ve added your secrets to the appropriate .env files, you need to encrypt them and push them to Hyphen. Run the following command: ```Text bash hx push ``` You will receive confirmation for each environment that’s been pushed. If you’ve updated the default, development, and production environments, the response will look like: ```Text bash Local environments: default, development, production Environments pushed: default, development, production ``` **Note**: .env.local is never pushed to Hyphen. ## Backup Your .hxkey file The `.hxkey` file is only stored locally and will be required for other team members or for other machines to pull the latest secrets. Make sure to save this in a secure place. ### Pulling Secrets URL: https://hyphen.ai/docs/env-secrets-management/pulling-secrets-for-an-existing-app/ Description: A guide on how to use the Hyphen CLI to securely pull application secrets into your local development environment. ## Prerequisites Before pulling down secrets, ensure you have: * You have installed the Hyphen CLI (see installation guide). * Signed in to your Hyphen account via the CLI with the `hx auth` command * You have access to an existing project that contains the app secrets in your Hyphen organization ## Navigate to your App's Directory First, navigate to the directory where your app’s source code is located: ```Text bash cd path/to/your/app ``` This is where the secrets will be synced and stored. ## Obtain the encryption key The encryption key is stored in a .hxkey file, but Hyphen never has access to this key, and is why we never see your secrets. Once you obtained the encryption key via a secure channel, place in the app's root directory. ## Fetch Secrets for the App ```Text bash hx pull ``` The pull command retrieves environment variables from Hyphen and decrypts them into local .env files. You can also pull a specific environment by name: ```Text bash hx pull production ``` ## Verify the Pulled Secrets Once the command has completed, the secrets will be available in the corresponding .env files in your app’s directory. The following files may be updated based on your environment. You can open and inspect these files to verify that the secrets have been pulled correctly. If you edit an of the `.env` files, the next time you push, a new version for that environment(s) will be added to the version history. ### Version Control URL: https://hyphen.ai/docs/env-secrets-management/version-control/ Description: Understand how Hyphen's version control system securely tracks and manages changes to your secrets, enabling traceability and restoration. ## How Version Control Works Every time you update and push your `.env` files using Hyphen, a new revision is created. These revisions are securely stored and can be reverted to at any time, allowing for full traceability of secret changes. **Note**: Due to Hyphen’s End-to-End Encryption (E2EE), we cannot display the exact differences between two revisions. However, we can show the number of secrets and file size of each version to help you gauge whether information was added or removed. ## Viewing revisions in the Hyphen app To view the history of your secrets and their respective revisions, navigate to the app and select the environment (i.e. default, development, production). This will open a view that lists the versions history. ![ENV version history example for the development environment for an app named "demo-app" ](https://files.readme.io/3a5bb704c21324eaf278b38b5c5c8966dee1dfeef38b942168a19fdcc81af620-Screenshot_2024-10-14_at_11.14.00_AM.png) The file size and secrets count give you an indication of whether secrets were added or removed in that revision, even though the contents are not displayed due to encryption. ## Viewing revisions in the Hyphen CLI To view the history of your secrets and their respective revisions using the cli, use the following command: ```shell bash hx env list-versions ``` Replace `` with the specific environment ID you wish to inspect. This command will return a list of past versions for that environment, displaying key details like version number, secret count, file size, and publish date. Example output: ```shell hx env list-versions development ID: development Version: 2 Secrets Count: 3 Size: 31 bytes Published: 08/15/2025 8:50:05 PM ID: development Version: 1 Secrets Count: 0 Size: 22 bytes Published: 08/11/2025 7:35:40 PM ... ``` ## Restore a previous version's secret data Hyphen uses immutable versioning, meaning you cannot directly roll back to a previous version. However, you can pull the encrypted data from a past version and push it as a new version. To do this: ### Retrieve the secret data from the desired version Use the following command to pull down the secrets from a specific version: ```shell hx pull ``` Replace `` with the environment you are working with and `` with the ID of the version you want to restore. ### Push the fetched data as a new version Once the previous version’s data is fetched, you can push it as a new version using the command: ```shell hx push ``` This will encrypt and push the retrieved secrets as the latest version in Hyphen. Example: ```shell # Fetch the secrets from version 12 for the development environment hx pull development 12 # Push it as a new version hx push ``` This process allows you to effectively revert without altering the integrity of your version history. ### Access Log URL: https://hyphen.ai/docs/env-secrets-management/access-log/ Description: Understand and utilize the ENV Access Log for auditing secret management actions, tracking changes, and ensuring transparency across different application environments. The ENV Access Log helps users trace and audit actions related to secret management within an application. It shows who performed the action with their IP address, the version of the secrets, and the app and environment affected. This provides transparency and traceability of secret changes across default, development, production, or other environments. ## View an Environment's ENV Access Log in Hyphen App 1. Select the ENV link in the main navigation. This brings you to the ENV dashboard, which lists all apps where secrets have been pushed to Hyphen. 2. Click on any of the environments within an app to open that environment's access log. example ENV access log example ENV access log ### Using ENV with Docker URL: https://hyphen.ai/docs/env-secrets-management/using-env-with-docker/ Description: Learn how to securely manage environment variables and secrets when deploying applications with Docker, covering three distinct methods: using hyphen-entrypoint.sh, including .env files, and exporting secrets. When building a docker image to run/deploy your application you have two options for loading secrets. ## Prerequisites Before getting started with ENV service, ensure you have: * Signed up for a Hyphen account and have access to an organization * Have the hx command line installed and authenticated ### Sample Docker configuration Here’s a basic configuration for your Docker environment. ```dockerfile FROM node:20-alpine3.16 as base ######################################### FROM base as builder WORKDIR /app COPY package.json package-lock.json ./ RUN npm ci COPY . ./ RUN npm run build ######################################### FROM base as server WORKDIR /app COPY --chown=node:node --from=builder /node_modules ./node_modules COPY --chown=node:node --from=builder /dist ./dist ENV PORT 3000 EXPOSE 3000 USER node CMD ["npm", "run", "start-prod"] ``` ```Text .dockerignore node_modules/ .hxkey ``` ## Option 1: Using hyphen-entrypoint.sh ### Pros * Secrets rotation only requires a container restart * Treats secrets like secrets and makes them available only at runtime. * One-time setup works consistently across environments and CI/CD and doesn't require changes when new secrets are added ### Cons * Differs from how the application is developed When you run `hx init`, a `hyphen-entrypoint.sh` script is automatically created in your project directory. This script is designed specifically for Docker deployments and handles: 1. Downloading the Hyphen CLI if not already present 2. Authenticating with your Hyphen API key 3. Pulling environment variables for the specified environment 4. Running your application with those variables loaded > **Note:** If the `hyphen-entrypoint.sh` is missing (e.g. because you ran `init` with an older version of hx) or needs to be updated, you can re-create it with `hx entrypoint` (and use `--force` if needed to overwrite it). ### Required Environment Variables The entrypoint script requires five environment variables to be set in your container: * `HYPHEN_API_KEY`: Your Hyphen API key for authentication * `HYPHEN_APP_ENVIRONMENT`: The environment to pull variables from (e.g., "development", "production", "default") * `HYPHEN_APP_ID`: Your application ID (e.g., "app_68f65adbb2aca958a8ff6ea9") * `HYPHEN_PROJECT_ID`: Your project ID (e.g., "proj_68ee9033968a1e3b98be5501") * `HYPHEN_ORGANIZATION_ID`: Your organization ID (e.g., "org_681bd71a0cd803794aebd33a") ### Sample Dockerfile with Entrypoint ```dockerfile FROM node:20-alpine3.16 AS base ######################################### FROM base AS builder WORKDIR /app COPY package.json package-lock.json ./ RUN npm ci COPY . ./ RUN npm run build ######################################### FROM base AS server WORKDIR /app COPY --chown=node:node --from=builder /app/package.json ./package.json COPY --chown=node:node --from=builder /app/dist ./dist COPY --chown=node:node --from=builder /app/hyphen-entrypoint.sh ./hyphen-entrypoint.sh RUN chown -R node:node /app RUN chmod +x ./hyphen-entrypoint.sh ENV PORT=3000 EXPOSE 3000 USER node ENTRYPOINT ["./hyphen-entrypoint.sh"] CMD ["npm", "run", "start-prod"] ``` ### Build and Run ```shell Build Command docker build . -t my-org/my-app ``` ```shell Run Command with Hyphen Environment Variables docker run -t my-org/my-app \ -e HYPHEN_API_KEY=$HYPHEN_API_KEY \ -e HYPHEN_APP_ENVIRONMENT=production \ -e HYPHEN_APP_ID=app_YOUR_APP_ID \ -e HYPHEN_PROJECT_ID=proj_YOUR_PROJECT_ID \ -e HYPHEN_ORGANIZATION_ID=org_YOUR_ORG_ID ``` You can find these IDs in your `.hx` file after running `hx init`, or in the Hyphen dashboard. The entrypoint script will automatically handle downloading the CLI, authenticating, pulling secrets, and starting your application with the correct environment variables loaded. ## Option 2: Including .env files ### Pros * Quickest way to get started * Mirrors how the application is developed ### Cons * Requires creating a new docker image to rotate secrets If you choose to include your .env files in the container, you will need to: 1. Pull the secrets 2. Copy them into your container 3. Use an open-source library to read them into your application. More information on .env files and the many open-source libraries can be found at [https://www.dotenv.org/](https://www.dotenv.org/)
```shell Pull Command > hx pull default && hx pull production ``` It's best practice to only pull secrets for the specific environment you're running in, which is why we didn't just run `hx pull`. ```shell Build Command docker build . -t my-org/my-app ``` Given that the `DOCKERFILE` copies the contents of the directory into the image, this will copy over the .env files, making them available to your application. ## Option 3: Exporting Secrets ### Pros * Secrets rotation only requires a container restart * Treats secrets like secrets and makes them available only at runtime. ### Cons * Differs from how the application is developed * Requires more setup Running the `hx env run` command will export all secrets as environment variables, which you can reference as needed. In this example, we pass them to the docker run command, though you could also mount them during the build. This is often how secrets are passed to cloud providers (e.g., Google Cloud Run). ```shell Build Command docker build . -t my-org/my-app ``` ```shell Run Command with Secrets # Single environment variable hx env run production -- sh -c 'docker run -t my-org/my-app -e MY_SECRET=$MY_SECRET' # Multiple environment variables hx env run production -- sh -c 'docker run -t my-org/my-app \ -e MY_SECRET=$MY_SECRET \ -e API_KEY=$API_KEY \ -e DB_PASSWORD=$DB_PASSWORD' ``` ### Deploying with ENV URL: https://hyphen.ai/docs/env-secrets-management/deploying-with-env/ Description: A comprehensive guide on how to integrate ENV secrets management into your deployment pipeline using GitHub Actions, with a specific example for deploying to Google Cloud Run. The following guide shows you how to use our [GitHub Actions](/docs/env-secrets-management/env-secrets) to deploy your application with secrets from ENV. ENV is designed to be incredible flexible and this is just one example of how to deploy with secrets from ENV to Google Cloud. ## Setting GitHub Secrets There are a few GitHub Secrets that you will need to set to be able to bootstrap and use env. The names of these secrets do not matter as you pass them to the various steps yourself. * `HYPHEN_API_KEY`: A Hyphen API key with access to the project, app, and environment you’re deploying. * `HYPHEN_KEY_FILE`: The contents of the `.hxkey` file. This file contains your encryption key and should **never** be checked into your repository, hence the need to include it as a secret. * `DEV_GCP_SA_KEY`: JSON credentials for deploying to GCP. Since your application won’t need this directly, we recommend not storing it in ENV. The same principle applies for other cloud providers. ## Writing the Workflow The following example workflow demonstrates a typical deployment process: 1. Clones your repository 2. Setups up Node v20 3. Installs and authenticates the hx CLI 4. Pulls the production ENV 5. Runs a build process 6. Set up and authenticate Google Cloud SDK 7. Authenticated docker with Google Cloud 8. Build a docker image using the build output 9. Push the Docker image to Google Artifact Registry 10. Deploys the image to Google Cloud Run using ENV Secrets ```yaml deploy.yml name: Deploy to Development on: workflow_dispatch: push: branches: [main] env: PROJECT_ID: my-development-environment SERVICE_NAME: my-app jobs: setup-build-deploy: name: Deploy to Dev runs-on: ubuntu-latest steps: - name: Checkout id: checkout uses: actions/checkout@v4 - name: Use Node.js 20 uses: actions/setup-node@v4 with: node-version: 20 - name: setup hx CLI id: setup uses: Hyphen/setup-hx-action@v1 with: apiKey: ${{ secrets.HYPHEN_API_KEY }} - name: Pull ENV id: pull-env uses: Hyphen/env-action@v1 with: hxKeyFile: ${{ secrets.HYPHEN_KEY_FILE }} environment: production outputs: variables - name: Run Build run: npm run build:ts - name: Authenticate with Google Cloud uses: google-github-actions/auth@v2 with: credentials_json: ${{ secrets.DEV_GCP_SA_KEY }} - name: Set up Cloud SDK uses: google-github-actions/setup-gcloud@v2 - name: Docker Auth run: gcloud auth configure-docker - name: Build Docker Image run: docker build -t gcr.io/$PROJECT_ID/$SERVICE_NAME:$GITHUB_SHA . - name: Docker Push to Google Cloud run: docker push gcr.io/$PROJECT_ID/$SERVICE_NAME:$GITHUB_SHA - name: Deploy to [us-central1] run: |- gcloud run deploy $SERVICE_NAME \ --image=gcr.io/$PROJECT_ID/$SERVICE_NAME:$GITHUB_SHA \ --cpu=1 \ --memory=2Gi \ --no-cpu-throttling \ --min-instances=1 \ --timeout=300 \ --platform=managed \ --region=us-central1 \ --allow-unauthenticated \ --set-env-vars=ONE_SECRET=$ONE_SECRET \ --set-env-vars=TWO_SECRET=$TWO_SECRET ``` ## Automatically add all secrets In the above example we are explicitly sending environment variables, exported by the env-action, to the google CLI. This is tedious and is prone to errors, forgetting to add it in the deploy script, misspelling, etc. This can easily be scripted through; We are going to add a script that iterates through all the environment variables and transforms them into the format the google CLI is looking for. If you are not using Google this script can easily be updated to transform them into the format AWS or Azure use. This script does the following 1. Looks for all environment variables with the `env` prefix. Don't forget to update the env-action step to add whatever prefix you want to use. 2. Removes the prefix from the variable name 3. Concatenates them into a `key=value, key=value` string. This is where you can change the format to match what Azure or AWS expects. 4. Echos out the result so we can use command substitution to send it to the CLI ```shell transformEnvs.sh # Initialize an empty string to store the concatenated result. result="" # Iterate over all environment variables. for var in $(env); do # Check if the variable starts with "env_" if [[ $var == env_* ]]; then # Extract the name and value by splitting at the first '='. name_with_prefix="${var%%=*}" value="${var#*=}" # Remove the "env_" prefix from the name. name="${name_with_prefix#env_}" # Concatenate the modified variable to the result string. # Append a space to separate each name=value pair. result+="${name}=${value}, " fi done # Trim any trailing spaces. result=$(echo "$result" | sed 's/, $//') # Output the concatenated result. echo "$result" ``` Next, we need to update the env-action to include our desired prefix. ```yaml deploy.yml ... - name: Pull ENV id: pull-env uses: Hyphen/env-action@v1 with: hxKeyFile: ${{ secrets.HYPHEN_KEY_FILE }} environment: production variablePrefix: env_ outputs: variables ... ``` The last thing we need to do is replace our `--set-env-vars` parameter in our deploy step ``` ... - name: Deploy to [us-central1] run: |- gcloud run deploy $SERVICE_NAME \ --image=gcr.io/$PROJECT_ID/$SERVICE_NAME:$GITHUB_SHA \ --cpu=1 \ --memory=2Gi \ --no-cpu-throttling \ --min-instances=1 \ --timeout=300 \ --platform=managed \ --region=us-central1 \ --allow-unauthenticated \ --set-env-vars="$(./.github/workflows/transformEnvs.sh)" ``` ### Rotating an Encryption Key URL: https://hyphen.ai/docs/env-secrets-management/rotating-an-encryption-key/ Description: Learn how to rotate encryption keys using the Hyphen CLI to enhance data security and meet compliance requirements. This guide covers the process, prerequisites, and available flags. > 🚀 Hyphen helps you prevent downtime > > When you rotate your encryption key, old versions of your secrets can still be fetched and decrypted! This allows you to change your keys and not have to rush to change every application at once. > > When you have given the new key to your applications, developers can delete the old version and you're good to go. Rotating encryption keys is a critical security practice that helps safeguard your sensitive data over time. Here are key reasons why you should rotate your encryption keys: 1. **Mitigate Potential Threats**: Over time, encryption keys can become more vulnerable, either through inadvertent exposure or prolonged use. Regular key rotation reduces the risk of keys being compromised. 2. **Compliance Requirements**: Many security standards, such as PCI-DSS and GDPR, require regular key rotation to maintain data protection and reduce vulnerabilities. 3. **Limit the Scope of Data Exposure**: In case an encryption key is ever compromised, rotating the key ensures that past data remains secure by limiting the time a single key is in use. 4. **Strengthen Security Hygiene**: Regularly rotating encryption keys is part of a healthy security practice that ensures your organization stays proactive in safeguarding its secrets. 5. **Respond to Security Events**: If there is ever a suspected breach or leak of an encryption key, rotating the key immediately helps neutralize the risk and prevent unauthorized access to your secrets. Hyphen allows you to rotate your encryption keys with minimal effort while ensuring your secrets remain secure. Here’s how to rotate an encryption key for your project. ## Prerequisites * You have installed the Hyphen CLI (see installation guide). * Signed in to your Hyphen account via the CLI with the `hx auth` command * You have access to an existing project that contains the app secrets in your Hyphen organization ## Rotate your encryption keys with the Hyphen CLI Navigate to the directory where your app’s source code is located. Run the this command: ```shell Command Line hx env rotate-key [flag] ``` This will rotate the encryption key and update all environments within your app. ## Flags and Options * `--force`: Use this flag to force overwrite locally modified environment files that haven’t been pushed yet. Without this, the CLI may warn you about unpushed changes before proceeding. * `-e`, `--environment`: Specify the environment ID (e.g., pevr\_12345) if you need to rotate keys for a specific environment. * \-p, --project: Provide the project ID (e.g., proj\_123) to rotate the key for a specific project. * \-v, --verbose: Enables verbose output to get more detailed information during the operation. * \-y, --yes: Automatically answer “yes” for prompts, allowing the key rotation process to proceed without manual confirmations. * \-n, --no: Automatically answer “no” for prompts if you want to cancel actions when asked. ### Example ```shell Command Line hyphen env rotate-key ``` This will do the following: 1. Pull the latest 2. Generate a new encryption key (always done client side) 3. Update your `.hxkey` files 4. Push new versions of your environments encrypted with the new key. ## What happens next? Share the new `.hxkey` with your team and update all your services / applications to use the new key. Once everyone has the new key simply delete the old versions of your secrets. ### End-to-End Encryption URL: https://hyphen.ai/docs/env-secrets-management/end-to-end-encryption/ Description: Learn how End-to-End Encryption in ENV ensures your secret keys and .env files remain secure and inaccessible to Hyphen. ENV is built for developers ❤️ but with enterprise features such as [Access Log](access-log), [Rotating an Encryption Key](rotating-an-encryption-key), and end-to-end encryption, ensuring it can be deployed in any environment. ## No Access to Your Secret Key All of your `.env` files are stored fully encrypted using a local **secret key** that Hyphen never has access to. Both encryption and decryption happen locally, ensuring that your `.env` files and the secrets they contain are never accessible by Hyphen. ## Secure Network with Authentication Not only are your files encrypted locally, but all data is transferred over SSL-encrypted connections and stored fully encrypted at rest. ENV includes robust user and API key authentication by default, with full [Access Log](access-log) audits on every `push` and `pull` request. For additional security, enable **IP Access Rules** in ENV so that any request from an IP address that does not match the configured rules is blocked, even if it includes valid authentication credentials. ## Why Aren't Our Secrets Visible in the Dashboard? As we’ve emphasized, the reason we don’t display secrets in the dashboard is that we have no access to your application’s **secret key**. Everything remains fully encrypted and out of Hyphen’s reach. ### ENV with GitHub Actions URL: https://hyphen.ai/docs/env-secrets-management/env-secrets/ Description: Action to retrieve, decrypt, and manage environment secrets for GitHub Actions workflows. This action retrieves secrets for the specified environment, decrypts them using the provided profile's key file, and outputs them either as standard `.env` files or exports them as environment variables. ## Prerequisites Before using the ENV service, ensure that: - The [Setup hx Command Line](../github-actions/setup-command-line) action has been run. - You have access to the `.hxkey` file for decrypting the environment secrets. ## Parameters - `hxKeyFile` _(required)_: The contents of the `.hxkey` file. This will NOT be sent to Hyphen and will only be used within the action container. - `environment` _(required)_: The ENV environment to pull (e.g., `production`, `staging`). - `outputs` _(optional)_: Specifies how the secrets should be provided: - `files` _(default)_: Writes the secrets to standard `.env` files on the file system. - `variables`: Exports the secrets as environment variables. - `variablePrefix` _(optional)_: If using the `variables` option, adds a prefix to the exported environment variables. - `path` _(optional)_: Specifies the path where the source code is located, defaults to `GITHUB_WORKSPACE`. ## Example Usage ```yml action.yml - name: Checkout id: checkout uses: actions/checkout@v4 - name: setup hx CLI id: setup uses: Hyphen/setup-hx-action@v1 with: apiKey: ${{ secrets.HYPHEN_API_KEY }} - name: Pull ENV id: pull-env uses: Hyphen/env-action@v1 with: hxKeyFile: ${{ secrets.HYPHEN_KEY_FILE }} environment: production outputs: |- files variables ``` ### Toggle Quickstart URL: https://hyphen.ai/docs/feature-flags/toggle-quickstart/ Description: A quickstart guide to using Hyphen's Toggle feature release management system with the OpenFeature standard. [Toggle](https://hyphen.ai/toggle) is a seamless feature release management system built on the robust [OpenFeature](https://openfeature.dev) standard. Hyphen publishes openFeature providers for the most common languages, but our Toggle services supports and documents an open API allowing you to consume it how you see fit. Toggles are grouped and belong to a [Hyphen Project](../introduction/project); [Targeting](toggle-concepts#targeting) can be used to provide different values for a project's applications and environments. ## Get a Project's Public Key To use Toggle, you will need a project [public key](project-public-key). To get the public key for a project: 1. Navigate to your [Hyphen Dashboard](https://app.hyphen.ai). 2. Select your **Project** from the list. 3. Go to the **Access** tab. 4. Copy the **Public Key** for your project. All public keys start with `public_` to make them easy to identify. ## Creating a Feature Flag 1. From the Project Details page, navigate to **Feature Flags**, then **Create Feature Flag** button. 2. Select a type, provide a key (for SDK references), set a logical default value. 3. Mark the feature flag as **perpetual** if the flag is meant to be long-lived in your codebase and will provide control for an extended period of time after the release of a given feature. 4. While optional, adding a clear description helps team members understand the toggle’s purpose. 5. Click **Create** to save, which redirects you to the feature flag detail page. This page contains [Telemetry](toggle-concepts#telemetry) information and also allows you to configure targets. ### Targeting 1. On the feature flag detail page scroll down to the `Targets` sections click `Add a Target`. 2. In the drawer, select one or more target criteria. For each criterion, choose a value from the [context](toggle-concepts#context) to evaluate, then specify the value to match against. Feature flags can include multiple targets. Evaluation proceeds sequentially—from the first target to the last—and stops as soon as a match is found. At that point, the matching target’s value is returned. (Targets can be reordered within the application.) > ℹ️ It is recommended to use the context's application and environment properties in your targets. ## Using a feature flag in your code As mentioned above, Hyphen publishes OpenFeature providers for the most common languages. In this example we will be using the JavaScript Server provider. Provider specific documentation can be found in the left nav. ### Installation Install the provider and the OpenFeature server SDK: ```shell npm install @openfeature/server-sdk @hyphen/openfeature-server-provider ``` ### Setup and Initialization To begin using the Hyphen Provider, follow these steps: 1. Import the required modules. 2. Configure the provider with your `publicKey` and application options. 3. Register the provider with OpenFeature. ```typescript import { OpenFeature } from "@openfeature/server-sdk"; import { HyphenProvider, type HyphenProviderOptions, } from "@hyphen/openfeature-server-provider"; const publicKey = "your-public-key-here"; const options: HyphenProviderOptions = { application: "your-application-name", environment: "production", }; await OpenFeature.setProviderAndWait(new HyphenProvider(publicKey, options)); ``` ### Consume a feature flag value In this example we are providing the [context](toggle-concepts#context) object at read time but a global [context](toggle-concepts#context) object can also be set if your context does not change. ```typescript const context: HyphenEvaluationContext = { targetingKey: "user-123", ipAddress: "203.0.113.42", customAttributes: { subscriptionLevel: "premium", region: "us-east", }, user: { id: "user-123", email: "john.doe@example.com", name: "John Doe", customAttributes: { role: "admin", }, }, }; const flagDetailsWithContext = await client.getBooleanDetails( "feature-flag-key", false, context, ); console.log(flagDetailsWithContext.value); // true or false ``` ### Toggle Concepts URL: https://hyphen.ai/docs/feature-flags/toggle-concepts/ Description: Understand the core concepts of feature toggles including context, targeting, segments, and telemetry in the context of the Hyphen platform. ## Context The context is a collection of properties and their values that feature flags use to determine targeting. While only a few properties are required, developers can extend the context with additional, custom properties to enable more complex targeting logic for a toggle. ## Targeting Targeting is the process of returning a value based on specific properties within the evaluated context. For example, a developer might target all users whose email address belongs to a certain domain. Hyphen uses the [JSON Logic](https://jsonlogic.com/) standard to support rich and complex targeting rules. ## Segments A segment is a reusable set of targeting rules based on context properties that can be applied across multiple feature flags within a project. Segments are useful because they let you define a common audience once and then reuse that audience across many toggles without duplicating logic. For example, “beta testers,” “premium customers,” or “users in Mexico". This makes targeting more consistent, reduces the chance of errors, and speeds up rollout changes, since updating a segment instantly updates all feature flags that reference it. Segments are especially valuable for maintaining large-scale feature flag systems where multiple teams work on different features but need to share consistent targeting criteria. ## Telemetry Hyphen collects two types of telemetry when you use toggle, Evaluation and Usage. ### Evaluations An evaluation is the result of applying a context to all toggles in a given project. Hyphen evaluates all the toggles at once for performance reasons. There are several layers of caching, invalidated by changes to the context or toggles, that allow Hyphen to provide unparalleled performance. Evaluation is the metric on which an organization is billed. ### Usage Usage telemetry is the consumption of the toggle's value for a given evaluation. This information is used to help developers determine what toggles are being used and what their values are being evaluated to. This telemetry is collected by our SDKs and may be turned off with SDK options. Doing so will reduce the information available to your developer in the hyphen application. Organizations are not billed based on usage metrics. ### Segments URL: https://hyphen.ai/docs/feature-flags/segments/ Description: Learn how to create and use segments to define reusable audience targeting rules for your feature flags, ensuring consistency and efficient rollouts. ## Overview A segment is a reusable set of targeting rules. Segments are useful because they let you define a common audience once and then reuse that audience across many feature flags without duplicating logic. For example, “beta testers,” “premium customers,” or “users in Mexico". A segment is scoped to the project it is created in. Segment rules are based on context properties and can be used across the environments within a project. Segments make targeting more consistent, reduces the chance of errors, and speeds up rollout changes, since updating a segment instantly updates all feature flags that reference it. Segments are especially valuable for maintaining large-scale feature flag systems where multiple teams work on different features but need to share consistent targeting criteria. ### Example Scenarios Here are some example scenarios where segments would be useful: 1. **Beta Testing Programs**\ You can create a segment for users who have opted into early access or beta testing. Any feature flag that should be tested by this group can simply reference the “Beta Testers” segment with the appropriate return value. When the membership of that segment changes (new testers join, others leave), all feature flags automatically update without needing manual edits. 2. **Geographic Rollouts**\ Release a new feature only to users in Canada and Mexico. You can define a “North America (non-US)” segment once, then apply it across multiple feature flags. This makes it easy to roll out region-specific features consistently. 3. **Premium or Enterprise Customers**\ If your product differentiates between free, premium, and enterprise tiers, you might create a “Premium Customers” segment. That segment can then be reused to unlock advanced features across many parts of the application without repeating the same subscription-level check. 4. **Internal Employees**\ Many teams test features internally before exposing them to customers. You can define an “Employees” segment that targets all users with company email domains. Any feature under internal testing can be gated behind that segment. ## Create a Segment 1. In the Hyphen app, navigate to any project you have at least collaborator access on. Click the **Segments** tab, then the "**Create Segment**" button. 2. ![Create segment form](https://files.readme.io/7dea68b2afd587b594644ba50a07a0c5e3fbb76c5e9d8dbb1717fd19a3db9958-Screenshot_2025-08-18_at_10.09.17_AM.png) Give the segment a name. ### Naming Conventions | Good | Bad | Why | | --------------- | ----------------------- | ---------------------------- | | `region-mexico` | `mx` | Descriptive, clear | | `plan-premium` | `pp` | Avoids cryptic abbreviations | | `role-admins` | `new-dashboard-testers` | Avoids feature tie-in | 3. Provide an optional description if the name of the segment is not descriptive enough 4. Click "**Create Segment**" to create an empty segment. 5. On the segment details page, you'll see: * **Segment key** — reference this in your code * **Creator** — who added the segment * **Flags** — feature flags using this segment * **Rules** — the targeting criteria ![Segment details page in Hyphen app](https://files.readme.io/8a9dcfb06ace6616d743a85090e1372b5690bf62ebeea92125fbc15615af9a42-Screenshot_2025-08-18_at_11.27.44_AM.png) 6. To add a rule, click the "**Add Rule**". Then click "**Add Criteria**". You'll see a list of options to create your first rule. Select `user.email`. 7. Select the `in` operator for the rules operator and enter a email address(es) separated by commas. Click "**Save**" to add the rule to the segment. 8. You can continue to add more rules to the segment, but know that rules will be evaluated in the order they appear (top-down) and the first matching rule will result in the evaluation context falling within the segment. If none of the rules are satisfied for a given context, then the segment context will not be in the segment. ## Use a segment in a feature flag To use a segment as a target in a feature flag 1. Create or navigate to an existing feature flag in the same project you've created a segment. 2. Click "**Add Target**". For the target criteria, select **Segment** from the dropdown menu. ![](https://files.readme.io/49161b7b776c9a09222818dde658720381f9f68640b277e0f85fc71e3154d445-Screenshot_2025-08-18_at_11.38.11_AM.png) 3. Choose `in` or `not in` as the operator, and then select your segment. 4. Select the return value of the feature flag if the target criteria is met and click "**Save**". You should now see the segment target in the list of feature flag targets. ![](https://files.readme.io/038676d265081c93bbcdade64f5c37a3b151dc12565b9ca2d899b93740324f8f-Screenshot_2025-08-18_at_11.39.48_AM.png) > ❗️ **Segments that are used by feature flags can not be deleted**\ > ❗️ A segment that is in use cannot be deleted. If you'd like to delete a segment that is in use, you must first remove the segment from all feature flags that use it. ## JSON Logic Segment rules are written in [JSON logic](https://jsonlogic.com/). Once you've created rules in a segment in the Hyphen app, you can access the segment's underlying JSON logic by clicking the "Copy JSON Logic" button next. ![Screenshot of Hyphen app showing where the "copy json logic" button is](https://files.readme.io/af687178b4bbe90b38ee8b429301cdea397ac760b54334b4a26a315b360a564e-Screenshot_2025-08-18_at_11.30.45_AM.png) Here's an example: ```json Segment JSON Logic { "or": [ { "and": [{ "==": [{ "var": "application" }, "location-app"] }] }, { "and": [{ "==": [{ "var": "user.id" }, "1234"] }] }, { "and": [ { "in": [ { "var": "user.email" }, ["one@example.com", "two@example.com", "three@example.com"] ] } ] } ] } ``` ## Rules Operator Reference | Name | Description | | ---------- | ------------------------------------------------------------------- | | `==` | Checks if the value is equal to the target value. | | `!=` | Checks if the value is not equal to the target value. | | `in` | Checks if the value exists within a list of comma-separated values. | | `contains` | Checks if a list or string contains the given value. | | `>=` | Checks if the value is greater than or equal to the target value. | | `<=` | Checks if the value is less than or equal to the target value. | ## Best Practices * Reuse segments across flags, don’t duplicate logic * Keep rules broad enough to be reused * Add descriptions when names aren’t self-explanatory ## Common Pitfalls * Overlapping segments that cause conflicting flag rules * Using feature names in segment names * Forgetting that editing a segment affects all flags instantly ### Project Public Key URL: https://hyphen.ai/docs/feature-flags/project-public-key/ Description: Learn how to find and use your Project Public Key in the Hyphen Dashboard for client-side API authentication and read-only access to features like Toggles. > ℹ️ This key is designed for client-side use and is safe to include in your frontend code. A Project Public Key is a unique identifier that allows developers to authenticate requests to Hyphen’s API. With this key, you have limited, read-only access to features like Toggle feature evaluations. Getting Your Project's Public Key 1. Navigate to your **Hyphen Dashboard**. 2. Select your project from the **Projects** list. 3. Your project's public key will appear on the right-hand column. 4. Your project public key is available on the project's **Access** tab. All public keys start with `public_` to make them easy to identify. ![](https://files.readme.io/992054417ee6ad40cff16b24831203f866a5135f65ee06aacd10046e528dae39-Screenshot_2025-01-03_at_5.41.41_PM.png)




To see all public keys for your organization: 1. in the main navigation, click **Settings** 2. Then click "Public Keys" to see all public keys that have been created. ### SDKs URL: https://hyphen.ai/docs/feature-flags/toggle-sdks/ Description: Explore Hyphen's native SDKs for Node.js, JavaScript, and React, along with its OpenFeature providers for Go, Python, and Swift, to integrate feature flagging into your applications. Hyphen has built out SDK's for `go`, `python`, `react`, `nodejs`, `javascript`, and `swift` either via our native support or via Open Feature. # Native SDK's ## @hyphen/sdk Server-side Node.js SDK for feature flag evaluation and management. Ideal for backend services, APIs, and server-rendered applications. **Simple use case:** ```javascript import { HyphenClient } from "@hyphen/sdk"; const client = new HyphenClient({ apiKey: "your-api-key" }); await client.initialize(); const isEnabled = await client.isEnabled("new-feature", { userId: "123" }); if (isEnabled) { // Execute new feature code } ``` ## @hyphen/browser-sdk Client-side JavaScript SDK for web browsers. Optimized for client-side feature flag evaluation with minimal bundle size. **Simple use case:** ```javascript import { HyphenBrowserClient } from "@hyphen/browser-sdk"; const client = new HyphenBrowserClient({ apiKey: "your-client-key" }); await client.initialize(); const showNewUI = await client.isEnabled("new-ui-design", { userId: user.id, }); ``` ## @hyphen/react-sdk React-specific SDK with hooks and components for seamless feature flag integration in React applications. **Simple use case:** ```javascript import { HyphenProvider, useFeatureFlag } from "@hyphen/react-sdk"; function App() { return ( ); } function MyComponent() { const isEnabled = useFeatureFlag("new-feature"); return isEnabled ? : ; } ``` We are currently planning to support native sdk's for `python`, `go`, `.net`, and `java` in the near future. # Open Feature SDK's [OpenFeature](https://openfeature.dev/) is an open standard that provides a vendor-agnostic, unified API for feature flagging. Hyphen supports OpenFeature through providers for multiple languages and frameworks. Hyphen has made the following open feature providers for you to use: - [GO](provider-go) - [Javascript (Node)](provider-javascript-node) - [Javascript (Web)](provider-javascript-web) - [Python](provider-python) - [React](provider-react) - [Swift](provider-swift) ### GO URL: https://hyphen.ai/docs/feature-flags/provider-go/ Description: Integrate Hyphen's feature flagging system into your Go applications using the OpenFeature SDK with the Hyphen Toggle Provider. Learn how to install, set up, and use the provider for dynamic feature management. **Hyphen Toggle Provider** for Go is an OpenFeature provider implementation that enables seamless feature flag evaluation in Go applications. This provider integrates Hyphen's feature flagging system with the OpenFeature SDK, providing robust feature management with minimal setup. ## Installation ```bash go get github.com/hyphen/openfeature-provider-go go get github.com/open-feature/go-sdk ``` ## Setup and Initialization To integrate the Hyphen Toggle provider into your application, follow these steps: 1. Configure the provider with your `PublicKey`, `Application` and `Environment`.\ You can specify the environment in one of two formats: * Alternate ID (e.g., "production", "staging") — the environment in which your application is running. * Project Environment ID (e.g., `pevr_abc123`) — useful for internal references. 2. Register the provider with OpenFeature. ```go provider, err := toggle.NewProvider(toggle.Config{ PublicKey: "your-public-key", Application: "your-app-name", Environment: "development", // or project environment ID }) openfeature.SetProvider(provider) ``` 3. Create an OpenFeature client for your application and configure the context needed for feature targeting evaluations, incorporating user or application context. ```go client := openfeature.NewClient("my-app") ctx := openfeature.NewEvaluationContext( "user-123", map[string]interface{}{ "email": "user@example.com", "plan": "premium", "age": 25, "country": "US", "beta_user": true, }, ) ``` ## Usage ### Evaluation Context Example The evaluation context allows you to pass targeting information: ```go stringFlag, _ := client.StringValue(context.Background(), "my-string-flag", "default", ctx) numberFlag, _ := client.NumberValue(context.Background(), "my-number-flag", 0, ctx) log.Printf("String Flag: %s", stringFlag) log.Printf("Number Flag: %f", numberFlag) ``` ## Configuration ### Provider Options | Option | Type | Required | Description | | ------------- | ---------- | :------- | ------------------------------------------------------------------------------------------ | | `PublicKey` | `string` | Yes | Your Hyphen API public key. | | `Application` | `string` | Yes | The application id or alternate id. | | `Environment` | `string` | Yes | The environment identifier for the Hyphen project (project environment ID or alternateId). | | `HorizonUrls` | `[]string` | No | Hyphen Horizon URLs for fetching flags. | | `EnableUsage` | `bool` | No | Enable/disable telemetry (default: true). | | `Cache` | `object` | No | Configuration for caching feature flag evaluations. | ### Caching The provider supports caching of evaluation results: | Property | Type | Default | Description | | :------- | :------- | :------ | :-------------------------------------------------------------- | | `TTL` | number | 300 | Time-to-live in seconds for cached flag evaluations. | | `KeyGen` | Function | - | Custom function to generate cache keys from evaluation context. | Example with cache configuration: ```go config := toggle.Config{ PublicKey: "your-public-key", Application: "your-app", Environment: "development", Cache: &toggle.CacheConfig{ TTL: time.Minute * 5, KeyGen: func(ctx toggle.EvaluationContext) string { return fmt.Sprintf("%s-%s", ctx.TargetingKey, ctx.GetValue("plan")) }, }, } ``` ## Example ```go package main import ( "context" "log" "github.com/open-feature/go-sdk/openfeature" "github.com/hyphen/openfeature-provider-go/pkg/toggle" ) func main() { // Initialize the provider provider, err := toggle.NewProvider(toggle.Config{ PublicKey: "your-public-key", Application: "your-app-name", Environment: "development", // or project environment ID }) if err != nil { log.Fatal(err) } // Set as global provider openfeature.SetProvider(provider) // Create a client client := openfeature.NewClient("my-app") // Create evaluation context ctx := openfeature.NewEvaluationContext( "targeting-key-user-123", map[string]interface{}{ "email": "user@example.com", "plan": "premium", }, ) // Evaluate different types of flags boolFlag, _ := client.BooleanValue(context.Background(), "my-bool-flag", false, ctx) stringFlag, _ := client.StringValue(context.Background(), "my-string-flag", "default", ctx) numberFlag, _ := client.NumberValue(context.Background(), "my-number-flag", 0, ctx) log.Printf("Bool Flag: %v", boolFlag) log.Printf("String Flag: %s", stringFlag) log.Printf("Number Flag: %f", numberFlag) } ``` ### JavaScript (Node) URL: https://hyphen.ai/docs/feature-flags/provider-javascript-node/ Description: Documentation for the Hyphen native Node.js SDK and the OpenFeature provider for server-side feature flag management. # Native SDK @hyphen/sdk The **@hyphen/sdk** is Hyphen's native server-side Node.js SDK for feature flag evaluation and management. It provides a streamlined, purpose-built interface for backend services, APIs, and server-rendered applications without requiring OpenFeature. ## Installation Install the native SDK: ```shell npm install @hyphen/sdk ``` ## Setup and Initialization Initialize the Hyphen client with your API key and configuration: ```javascript import { HyphenClient } from '@hyphen/sdk'; const client = new HyphenClient({ apiKey: 'your-api-key', application: 'your-application-name', environment: 'production' // or project environment ID }); await client.initialize(); ``` ## Usage ### Basic Feature Flag Evaluation Check if a feature is enabled for a user: ```javascript const isEnabled = await client.isEnabled('new-checkout-flow', { userId: 'user-123', email: 'john.doe@example.com' }); if (isEnabled) { // Execute new checkout flow processNewCheckout(); } else { // Use legacy checkout processLegacyCheckout(); } ``` ### Getting Feature Flag Details Retrieve detailed information about a feature flag evaluation: ```javascript const flagDetails = await client.getFlagDetails('feature-flag-key', { userId: 'user-123', customAttributes: { subscriptionLevel: 'premium', region: 'us-east' } }); console.log(flagDetails.enabled); // true or false console.log(flagDetails.variant); // variant name if applicable console.log(flagDetails.metadata); // additional flag metadata ``` ### Targeting Context Provide rich context for advanced targeting rules: ```javascript const context = { userId: 'user-456', email: 'jane.smith@example.com', name: 'Jane Smith', ipAddress: '203.0.113.42', customAttributes: { role: 'admin', subscriptionLevel: 'enterprise', region: 'us-west' } }; const showAdminPanel = await client.isEnabled('admin-panel-v2', context); ``` ## Configuration Options | Option | Type | Required | Description | | :------------------ | :--------- | :------- | :--------------------------------------------------------------- | | `apiKey` | `string` | Yes | Your Hyphen API key | | `application` | `string` | Yes | The application id or alternate ID | | `environment` | `string` | Yes | The environment identifier (project environment ID or alternate) | | `enableTelemetry` | `boolean` | No | Enable/disable usage telemetry (default: true) | | `cacheTTL` | `number` | No | Cache time-to-live in seconds (default: 300) | # Open Feature The **Hyphen Toggle Provider** for Node.js is an OpenFeature provider implementation that enables seamless feature flag evaluation. This section covers setup, usage, and configuration specific to the JavaScript implementation. ## Installation Install the provider and the OpenFeature server SDK: ```shell npm install @openfeature/server-sdk @hyphen/openfeature-server-provider ``` ## Setup and Initialization To begin using the Hyphen Provider, follow these steps: 1. Import the required modules. 2. Configure the provider with your `publicKey` , application name and environment.\ You can specify the environment in one of two formats: * Alternate ID (e.g., "production", "staging") — the environment in which your application is running. * Project Environment ID (e.g., `pevr_abc123`) — useful for internal references. 3. Register the provider with OpenFeature. ```javascript import { OpenFeature } from '@openfeature/server-sdk'; import { HyphenProvider, type HyphenProviderOptions } from '@hyphen/openfeature-server-provider'; const publicKey = "your-public-key-here"; const options: HyphenProviderOptions = { application: 'your-application-name', environment: 'production', // or project environment ID }; await OpenFeature.setProviderAndWait(new HyphenProvider(publicKey, options)); ``` 4. Configure the context needed for feature targeting evaluations, incorporating user or application context. ```typescript const context: HyphenEvaluationContext = { targetingKey: 'user-123', ipAddress: '203.0.113.42', customAttributes: { subscriptionLevel: 'premium', region: 'us-east', }, user: { id: 'user-123', email: 'john.doe@example.com', name: 'John Doe', customAttributes: { role: 'admin', }, }, }; ``` ## Usage ### Evaluation Context Example Evaluate a feature flag using the OpenFeature client and context information: ```typescript const client = OpenFeature.getClient(); const flagDetailsWithContext = await client.getBooleanDetails('feature-flag-key', false, context); console.log(flagDetailsWithContext.value); // true or false ``` ## Configuration ### Options | Option | Type | Required | Description | | :------------------ | :--------- | :------- | :----------------------------------------------------------------------------------------- | | `application` | `string` | Yes | The application id or alternate ID. | | `environment` | `string` | Yes | The environment identifier for the Hyphen project (project environment ID or alternateId). | | `horizonUrls` | `string[]` | No | Hyphen Horizon URLs for fetching flags. | | `enableToggleUsage` | `boolean` | No | Enable/disable telemetry (default: true). | | `cache` | object | No | Configuration for caching feature flag evaluations. | ### Cache Configuration The `cache` option accepts the following properties: | Property | Type | Default | Description | | -------------------- | -------- | ------- | --------------------------------------------------------------- | | `ttlSeconds` | number | 300 | Time-to-live in seconds for cached flag evaluations. | | `generateCacheKeyFn` | Function | - | Custom function to generate cache keys from evaluation context. | Example with cache configuration: ```typescript const options: HyphenProviderOptions = { application: 'your-application-name', environment: 'production', cache: { ttlSeconds: 600, // 10 minutes generateCacheKeyFn: (context: HyphenEvaluationContext) => { return `${context.targetingKey}-${context.user?.id}`; }, }, }; ``` ### Context Provide an `EvaluationContext` to pass contextual data for feature evaluation. | Field | Type | Required | Description | | ----------------------- | --------------------- | :------- | ------------------------------------------------------------------ | | `targetingKey` | `string` | Yes | The key used for caching the evaluation response. | | `ipAddress` | `string` | No | The IP address of the user making the request. | | `customAttributes` | `Record` | No | Custom attributes for additional contextual information. | | `user` | `object` | No | An object containing user-specific information for the evaluation. | | `user.id` | `string` | No | The unique identifier of the user. | | `user.email` | `string` | No | The email address of the user. | | `user.name` | `string` | No | The name of the user. | | `user.customAttributes` | `Record` | No | Custom attributes specific to the user. |
## Example ```typescript const context: HyphenEvaluationContext = { targetingKey: 'user-456', customAttributes: { subscriptionLevel: 'premium', }, }; const flagDetails = await client.getBooleanDetails('enable-discounts', false, context); if (flagDetails.value) { console.log('Discounts enabled for premium users.'); } else { console.log('No discounts available.'); } ``` ### React URL: https://hyphen.ai/docs/feature-flags/provider-react/ Description: Integrate Hyphen's feature flags into your React applications using the native React SDK or the OpenFeature provider. Learn about installation, setup, and usage with hooks and components. # Native SDK @hyphen/react-sdk The **@hyphen/react-sdk** is Hyphen's native React SDK that provides hooks and components for seamless feature flag integration in React applications. It offers a React-idiomatic interface without requiring OpenFeature. ## Installation Install the native React SDK: ```shell npm install @hyphen/react-sdk ``` ## Setup and Initialization Wrap your application with the `HyphenProvider` component: ```javascript import { HyphenProvider } from '@hyphen/react-sdk'; function App() { return ( ); } ``` ## Usage ### Basic Feature Flag Hook Use the `useFeatureFlag` hook to check if a feature is enabled: ```javascript import { useFeatureFlag } from '@hyphen/react-sdk'; function MyComponent() { const isEnabled = useFeatureFlag('new-ui-design'); return (
{isEnabled ? : }
); } ``` ### Feature Flag with User Context Provide user context for targeted feature rollouts: ```javascript import { useFeatureFlag, useHyphenContext } from '@hyphen/react-sdk'; function Dashboard() { const { setContext } = useHyphenContext(); // Set user context (typically in authentication flow) useEffect(() => { setContext({ userId: user.id, email: user.email, customAttributes: { subscriptionTier: 'premium', role: 'admin' } }); }, [user]); const showBetaFeatures = useFeatureFlag('beta-dashboard'); return showBetaFeatures ? : ; } ``` ### Getting Detailed Flag Information Use `useFeatureFlagDetails` to get additional metadata: ```javascript import { useFeatureFlagDetails } from '@hyphen/react-sdk'; function FeatureComponent() { const { enabled, variant, metadata } = useFeatureFlagDetails('ab-test-feature'); if (!enabled) return ; switch (variant) { case 'variant-a': return ; case 'variant-b': return ; default: return ; } } ``` ### Conditional Rendering Component Use the `FeatureFlag` component for declarative conditional rendering: ```javascript import { FeatureFlag } from '@hyphen/react-sdk'; function App() { return (
}> {/* With variant support */}
); } ``` ### Loading States Handle loading states while flags are being fetched: ```javascript import { useFeatureFlag, useHyphenClient } from '@hyphen/react-sdk'; function FeatureComponent() { const { isReady } = useHyphenClient(); const isEnabled = useFeatureFlag('new-feature'); if (!isReady) { return ; } return isEnabled ? : ; } ``` ### Real-time Flag Updates Subscribe to flag changes in real-time: ```javascript import { useFeatureFlag, useFeatureFlagListener } from '@hyphen/react-sdk'; function DynamicFeature() { const isEnabled = useFeatureFlag('live-chat'); useFeatureFlagListener('live-chat', (newValue) => { console.log('live-chat flag changed to:', newValue); // Optionally trigger side effects }); return isEnabled ? : null; } ``` ## HyphenProvider Configuration The `HyphenProvider` accepts the following props: | Prop | Type | Required | Description | | :---------------- | :-------- | :------- | :---------------------------------------------------------- | | `apiKey` | `string` | Yes | Your Hyphen client API key | | `application` | `string` | Yes | The application id or alternate ID | | `environment` | `string` | Yes | The environment identifier (production, staging, etc.) | | `enableTelemetry` | `boolean` | No | Enable/disable usage telemetry (default: true) | | `autoUpdate` | `boolean` | No | Enable automatic flag updates (default: true) | | `updateInterval` | `number` | No | Flag update interval in seconds (default: 60) | | `defaultContext` | `object` | No | Default user context for all flag evaluations | ## Available Hooks | Hook | Description | | :------------------------- | :---------------------------------------------------- | | `useFeatureFlag` | Get boolean value of a feature flag | | `useFeatureFlagDetails` | Get detailed flag information including variants | | `useHyphenContext` | Access and update user context | | `useHyphenClient` | Access the underlying Hyphen client instance | | `useFeatureFlagListener` | Subscribe to real-time flag changes | # Open Feature ## Installation To use the Hyphen Toggle OpenFeature Web Provider for React, install the required packages: ```shell npm install @openfeature/react-sdk @hyphen/openfeature-web-provider ``` ## Setup and Initialization To begin using the Hyphen Provider, follow these steps: 1. Import the required modules. 2. Configure the provider with your `publicKey`, application name and environment.\ You can specify the environment in one of two formats: * Alternate ID (e.g., "production", "staging") — the environment in which your application is running. * Project Environment ID (e.g., `pevr_abc123`) — useful for internal references. 3. Register the OpenFeature provider. ```typescript jsx import { OpenFeature, OpenFeatureProvider } from '@openfeature/react-sdk'; import { HyphenProvider, HyphenProviderOptions } from '@hyphen/openfeature-web-provider'; const publicKey = 'your-public-key'; // Replace with your Hyphen publicKey const options: HyphenProviderOptions = { application: 'your-app-name', environment: 'production', // or project environment ID }; await OpenFeature.setProviderAndWait(new HyphenProvider(publicKey, options)); function App() { return ( ); } ``` 4. Use `OpenFeature.setContext` to configure the context needed for feature targeting. This context should include relevant user information, typically obtained from an authentication process. ```typescript jsx const AuthContext = createContext({ isLoading: true, user: null }); export const MockAuthProvider = ({ children }: { children: React.ReactNode }) => { const [authState, setAuthState] = useState({ isLoading: true, user: null }); useEffect(() => { setTimeout(() => { const user = { id: 'user-123', name: 'John Doe', email: 'user@example.com', }; OpenFeature.setContext({ targetingKey: user.id, user, customAttributes: { role: user.role }, // Additional targeting attributes }); setAuthState({ isLoading: false, user }); }, 1000); }, []); return {children}; }; export const useAuth = () => useContext(AuthContext); ``` ## Usage ### Evaluation Context Example Use any of the OpenFeature evaluation hooks to evaluate flags. ```typescript jsx import { useFlag } from '@openfeature/react-sdk'; function Page() { const { value: isFeatureEnabled } = useFlag('your-flag-key', false); return (
{isFeatureEnabled ?

Welcome to this OpenFeature-enabled React app!

:

Welcome to this React app.

}
) } ``` ## Configuration ### Options | Option | Type | Required | Description | | :------------------ | :--------- | :------- | :----------------------------------------------------------------------------------------- | | `application` | `string` | Yes | The application id or alternate ID. | | `environment` | `string` | Yes | The environment identifier for the Hyphen project (project environment ID or alternateId). | | `horizonUrls` | `string[]` | No | Hyphen Horizon URLs for fetching flags. | | `enableToggleUsage` | `boolean` | No | Enable/disable telemetry (default: true). | ### Context Provide an `EvaluationContext` to pass contextual data for feature evaluation. | Field | Type | Required | Description | | ----------------------- | --------------------- | :------- | ------------------------------------------------------------------ | | `targetingKey` | `string` | Yes | The key used for caching the evaluation response. | | `ipAddress` | `string` | No | The IP address of the user making the request. | | `customAttributes` | `Record` | No | Custom attributes for additional contextual information. | | `user` | `object` | No | An object containing user-specific information for the evaluation. | | `user.id` | `string` | No | The unique identifier of the user. | | `user.email` | `string` | No | The email address of the user. | | `user.name` | `string` | No | The name of the user. | | `user.customAttributes` | `Record` | No | Custom attributes specific to the user. | ### Javascript (Web) URL: https://hyphen.ai/docs/feature-flags/provider-javascript-web/ Description: Documentation for Hyphen's JavaScript SDKs (@hyphen/browser-sdk and @hyphen/openfeature-web-provider) for web browsers, covering installation, setup, usage, and configuration. # Native SDK @hyphen/browser-sdk The **@hyphen/browser-sdk** is Hyphen's native client-side JavaScript SDK for web browsers. It provides a lightweight, optimized solution for feature flag evaluation in browser environments without requiring OpenFeature. ## Installation Install the native browser SDK: ```shell npm install @hyphen/browser-sdk ``` Or include via CDN: ```html ``` ## Setup and Initialization Initialize the Hyphen browser client with your client key and configuration: ```javascript import { HyphenBrowserClient } from '@hyphen/browser-sdk'; const client = new HyphenBrowserClient({ apiKey: 'your-client-key', application: 'your-application-name', environment: 'production' // or project environment ID }); await client.initialize(); ``` ## Usage ### Basic Feature Flag Evaluation Check if a feature is enabled for the current user: ```javascript const isEnabled = await client.isEnabled('new-ui-design', { userId: user.id, email: user.email }); if (isEnabled) { // Show new UI renderNewUI(); } else { // Show legacy UI renderLegacyUI(); } ``` ### Real-time Flag Updates Listen for feature flag changes in real-time: ```javascript client.on('flagsChanged', (flags) => { console.log('Feature flags updated:', flags); updateUIBasedOnFlags(flags); }); ``` ### Getting Feature Flag Details Retrieve detailed information about a feature flag evaluation: ```javascript const flagDetails = await client.getFlagDetails('beta-features', { userId: user.id, customAttributes: { accountType: 'premium', region: 'us-west' } }); console.log(flagDetails.enabled); // true or false console.log(flagDetails.variant); // variant name if applicable ``` ### User Context Provide user context for targeted feature rollouts: ```javascript const context = { userId: 'user-789', email: 'user@example.com', name: 'John Doe', customAttributes: { accountType: 'enterprise', betaTester: true, region: 'eu-west' } }; const showBetaFeatures = await client.isEnabled('beta-dashboard', context); ``` ### Browser-Specific Features The browser SDK automatically captures browser context: ```javascript // SDK automatically includes: // - User agent // - Screen resolution // - Browser language // - Timezone const isEnabled = await client.isEnabled('mobile-optimized-view', { userId: user.id }); ``` ## Configuration Options | Option | Type | Required | Description | | :---------------- | :-------- | :------- | :--------------------------------------------------------------- | | `apiKey` | `string` | Yes | Your Hyphen client API key (use client key, not server key) | | `application` | `string` | Yes | The application id or alternate ID | | `environment` | `string` | Yes | The environment identifier (project environment ID or alternate) | | `enableTelemetry` | `boolean` | No | Enable/disable usage telemetry (default: true) | | `autoUpdate` | `boolean` | No | Enable automatic flag updates (default: true) | | `updateInterval` | `number` | No | Flag update interval in seconds (default: 60) | # Open Feature ## Installation Install the provider and the OpenFeature server SDK: ```shell shell npm install @openfeature/web-sdk @hyphen/openfeature-web-provider ``` ## Setup and Initialization To begin using the Hyphen Provider, follow these steps: 1. Import the required modules. 2. Configure the provider with your `publicKey` , `application` and `environment`.\ You can specify the environment in one of two formats: * Alternate ID (e.g., "production", "staging") — the environment in which your application is running. * Project Environment ID (e.g., `pevr_abc123`) — useful for internal references. 3. Register the provider with OpenFeature. ```javascript import { OpenFeature } from '@openfeature/web-sdk'; import { HyphenProvider, type HyphenProviderOptions } from '@hyphen/openfeature-web-provider'; const publicKey = "your-public-key-here"; const options: HyphenProviderOptions = { application: 'your-application-name', environment: 'production', // or project environment ID }; await OpenFeature.setProviderAndWait(new HyphenProvider(publicKey, options)); ``` 4. Use `OpenFeature.setContext` to configure the required context for feature targeting evaluations, incorporating user or application context. ```javascript const context: HyphenEvaluationContext = { targetingKey: 'user-123', ipAddress: '203.0.113.42', customAttributes: { subscriptionLevel: 'premium', region: 'us-east', }, user: { id: 'user-123', email: 'john.doe@example.com', name: 'John Doe', customAttributes: { role: 'admin', }, }, }; OpenFeature.setContext(context); ``` ## Usage ### Evaluation Context Example Use the `OpenFeature.getClient()` to evaluate feature flags in your application. ```javascript const client = OpenFeature.getClient(); const isEnabled = client.getBooleanDetails('your-flag-key', false); console.log('isEnabled', isEnabled) // true or false ``` ## Configuration ### Options | Option | Type | Required | Description | | :------------------ | :--------- | :------- | :----------------------------------------------------------------------------------------- | | `application` | `string` | Yes | The application id or alternate ID. | | `environment` | `string` | Yes | The environment identifier for the Hyphen project (project environment ID or alternateId). | | `horizonUrls` | `string[]` | No | Hyphen Horizon URLs for fetching flags. | | `enableToggleUsage` | `boolean` | No | Enable/disable telemetry (default: true). | ### Context Provide an `EvaluationContext` to pass contextual data for feature evaluation. | Field | Type | Required | Description | | ----------------------- | --------------------- | :------- | ------------------------------------------------------------------ | | `targetingKey` | `string` | Yes | The key used for caching the evaluation response. | | `ipAddress` | `string` | No | The IP address of the user making the request. | | `customAttributes` | `Record` | No | Custom attributes for additional contextual information. | | `user` | `object` | No | An object containing user-specific information for the evaluation. | | `user.id` | `string` | No | The unique identifier of the user. | | `user.email` | `string` | No | The email address of the user. | | `user.name` | `string` | No | The name of the user. | | `user.customAttributes` | `Record` | No | Custom attributes specific to the user. | ### Python URL: https://hyphen.ai/docs/feature-flags/provider-python/ Description: A guide on how to install, set up, and use the Hyphen Provider with the OpenFeature Python SDK for feature flag management. ## Installation Install the provider and the OpenFeature Python SDK: ```bash pip install openfeature-sdk hyphen-openfeature-provider ``` ## Setup and Initialization To begin using the Hyphen Provider, follow these steps: 1. Import the required modules 2. Configure the provider with your `publicKey`, application name and environment.\ You can specify the environment in one of two formats: * Alternate ID (e.g., "production", "staging") — the environment in which your application is running. * Project Environment ID (e.g., `pevr_abc123`) — useful for internal references. 3. Register the provider with OpenFeature and create an OpenFeature client for your application. ```python from openfeature import api from openfeature_provider_hyphen import ( HyphenProvider, HyphenProviderOptions, HyphenEvaluationContext ) # Initialize provider options options = HyphenProviderOptions( application="your-app-name", environment="production" ) # Create and set the provider provider = HyphenProvider( public_key="your-public-key", options=options ) api.set_provider(provider) # Create a client client = api.get_client() ``` 4. Use `HyphenEvaluationContext` to configure the required context for feature targeting evaluations, incorporating user or application context. ```python from openfeature_provider_hyphen import HyphenUser # Create user details user = HyphenUser( id="user-123", email="user@example.com", name="John Doe", custom_attributes={ "role": "admin", "subscription": "premium" } ) # Create evaluation context context = HyphenEvaluationContext( targeting_key="user-123", attributes={ "user": user, "ip_address": "203.0.113.42", "custom_attributes": { "device": "mobile", "platform": "ios" } } ) ``` ## Usage ### Evaluation Context Example Use the client to evaluate different types of feature flags in your application. ```python try: # Boolean flag evaluation is_enabled = client.get_boolean_value( flag_key="your-flag-key", default_value=False, evaluation_context=context ) print(f"Feature enabled: {is_enabled}") # String flag evaluation theme = client.get_string_value( flag_key="app-theme", default_value="light", evaluation_context=context ) # Integer flag evaluation max_items = client.get_integer_value( flag_key="max-items", default_value=10, evaluation_context=context ) # Object flag evaluation config = client.get_object_value( flag_key="feature-config", default_value={ "enabled": True, "timeout": 30 }, evaluation_context=context ) except Exception as e: print(f"Error evaluating flag: {e}") ``` ## Configuration ### Options | Option | Type | Required | Description | | ----------------------- | ----------- | -------- | ------------------------------------------------------------------------------------------ | | `application` | `str` | Yes | The application id or alternate ID. | | `environment` | `str` | Yes | The environment identifier for the Hyphen project (project environment ID or alternateId). | | `horizon_urls` | `List[str]` | No | Custom Hyphen server URLs. | | `enable_toggle_usage` | `bool` | No | Enable/disable telemetry (default: true). | | `cache_ttl_seconds` | `int` | No | Cache TTL in seconds (default: 300). | | `generate_cache_key_fn` | `Callable` | No | Custom cache key generation function. | ### Context | Field | Type | Required | Description | | ------------------------------ | ---------------- | -------- | ------------------------------------------------- | | `targeting_key` | `str` | Yes | The key used for caching the evaluation response. | | `attributes` | `Dict` | No | Dictionary containing context attributes. | | `attributes.user` | `HyphenUser` | No | User information for targeting. | | `attributes.ip_address` | `str` | No | The IP address of the user. | | `attributes.custom_attributes` | `Dict[str, Any]` | No | Additional contextual information. | #### HyphenUser Fields | Field | Type | Required | Description | | ------------------- | ---------------- | -------- | -------------------------------------- | | `id` | `str` | Yes | The unique identifier of the user | | `email` | `str` | No | The email address of the user | | `name` | `str` | No | The name of the user | | `custom_attributes` | `Dict[str, Any]` | No | Custom attributes specific to the user | ### .NET URL: https://hyphen.ai/docs/feature-flags/provider-dotnet/ Description: Integrate Hyphen's feature flagging system into your .NET applications using the OpenFeature SDK with the Hyphen Toggle OpenFeature Provider. Learn how to install, set up, and use the provider, including context configuration and cache options. Hyphen Toggle OpenFeature Provider for .NET is an OpenFeature provider implementation that enables seamless feature flag evaluation in .NET applications. This provider integrates Hyphen's feature flagging system with the OpenFeature SDK, providing robust feature management with minimal setup. ## Installation Install the provider and OpenFeature using NuGet: ```shell dotnet add package Hyphen.OpenFeature.Provider dotnet add package OpenFeature ``` ## Setup and Initialization To integrate the Hyphen Toggle provider into your application, follow these steps: 1. Configure the provider with your `publicKey`, application name and environment.\ You can specify the environment in one of two formats: * Alternate ID (e.g., "production", "staging") — the environment in which your application is running. * Project Environment ID (e.g., `pevr_abc123`) — useful for internal references. 2. Register the provider with OpenFeature. ```csharp using OpenFeature; using Hyphen.OpenFeature.Provider; var publicKey = "your-public-key-here"; var options = new HyphenProviderOptions { Application = "your-application-name", Environment = "production" // or project environment ID }; await OpenFeature.SetProviderAsync(new HyphenProvider(publicKey, options)); ``` 3. Configure the context needed for feature targeting evaluations, incorporating user or application context. ```csharp HyphenEvaluationContext hyphenEvaluationContext = new HyphenEvaluationContext { TargetingKey = "user-123", IpAddress = "203.0.113.42", CustomAttributes = new Dictionary { { "subscriptionLevel", "premium" }, { "region", "us-east" } }, User = new UserContext { Id = "user-123", Email = "user@example.com", Name = "John Doe", CustomAttributes = new Dictionary { { "role", "admin" } } } }; EvaluationContext context = hyphenEvaluationContext.GetEvaluationContext(); ``` ## Usage ### Evaluation Context Example Evaluate a feature flag using the OpenFeature client and context information: ```csharp var client = OpenFeature.GetClient(); var flagValue = await client.GetBooleanValue("feature-flag-key", false, context); ``` ## Configuration ### Options | Option | Type | Required | Description | | ------------------- | -------------- | -------- | ------------------------------------------------------------------------------------------- | | `Application` | `string` | Yes | The application id or alternate id | | `Environment` | `string` | Yes | The environment identifier for the Hyphen project (project environment ID or alternate ID). | | `HorizonUrls` | `string[]` | No | Hyphen Horizon URLs for fetching flags. | | `EnableToggleUsage` | `bool?` | No | Enable/disable telemetry (default: true). | | `Cache` | `CacheOptions` | No | Configuration for caching evaluations. | ### Cache Configuration The `Cache` option accepts the following properties: | Property | Type | Default | Description | | :------------------- | :------- | :------ | :-------------------------------------------------------------- | | `TtlSeconds` | number | 300 | Time-to-live in seconds for cached flag evaluations. | | `GenerateCacheKeyFn` | Function | - | Custom function to generate cache keys from evaluation context. | Example with cache configuration: ```csharp var options = new HyphenProviderOptions { Application = "your-application-name", Environment = "production", Cache = new CacheOptions { TtlSeconds = 600, // 10 minutes GenerateCacheKeyFn = (context) => $"{context.TargetingKey}-{context.User?.Id}" } }; ``` ### Context Provide an `EvaluationContext` to pass contextual data for feature evaluation. | Field | Type | Required | Description | | ----------------------- | ---------------------------- | -------- | --------------------------------------- | | `TargetingKey` | `string` | Yes | Caching evaluation key. | | `IpAddress` | `string` | No | User's IP address. | | `CustomAttributes` | `Dictionary` | No | Additional context information. | | `User` | `UserContext` | No | User-specific information. | | `User.Id` | `string` | No | Unique identifier of the user. | | `User.Email` | `string` | No | Email address of the user. | | `User.Name` | `string` | No | Name of the user. | | `User.CustomAttributes` | `Dictionary` | No | Custom attributes specific to the user. | ### Swift URL: https://hyphen.ai/docs/feature-flags/provider-swift/ Description: Integrate Hyphen's feature flagging system into your Swift applications using the OpenFeature SDK with the Hyphen Toggle Provider. This guide covers installation, setup, configuration, and usage for iOS and macOS. **Hyphen Toggle Provider** for Swift is an OpenFeature provider implementation that enables seamless feature flag evaluation in iOS and macOS applications. This provider integrates Hyphen's feature flagging system with the OpenFeature SDK, providing robust feature management with minimal setup. ## Installation Add the package using Swift Package Manager. Either through Xcode's UI (File > Swift Packages > Add Package Dependency) or by adding this line to your `Package.swift`: ```swift .package(url: "https://github.com/hyphen/hyphen-openfeature-swift", from: "0.2.0") ``` Select the `Toggle` target during installation. You'll also need the OpenFeature Swift SDK: ```swift .package(url: "https://github.com/open-feature/swift-sdk", from: "0.1.0") ``` ## Setup and Initialization To integrate the Hyphen Toggle provider into your application, follow these steps: 1. Configure the provider with your `publicKey`, `application` and `environment`.\ You can specify the environment in one of two formats: * Alternate ID (e.g., "production", "staging") — the environment in which your application is running. * Project Environment ID (e.g., `pevr_abc123`) — useful for internal references. 2. Register the provider with OpenFeature. ```swift import Toggle import OpenFeature let configuration = HyphenConfiguration( using: "your-public-key", application: "your-app-name", environment: "development" // or project environment ID ) let provider = HyphenProvider(using: configuration) await OpenFeatureAPI.shared.setProviderAndWait(provider: provider) ``` 3. Create an evaluation context for feature targeting evaluations, incorporating user or application context. ```swift let context = hyphenEvaluationContext( targetingKey: "user-123", values: [ "CustomAttributes": .structure([ "plan": .string("premium"), "betaAccess": .boolean(true) ]), "User": .structure([ "Email": .string("user@example.com"), "Name": .string("User Name"), "CustomAttributes": .structure([ "subscription": .string("pro") ]) ]) ] ) await OpenFeatureAPI.shared.setProviderAndWait( provider: provider, initialContext: context ) ``` ## Usage ### Basic Flag Evaluation ```swift let client = OpenFeatureAPI.shared.getClient() // Boolean flag let boolFlag = client.getBooleanValue(key: "my-bool-flag", defaultValue: false) // String flag let stringFlag = client.getStringValue(key: "my-string-flag", defaultValue: "default") // Number flag let numberFlag = client.getIntegerValue(key: "my-number-flag", defaultValue: 0) ``` ### Getting Flag Details For more detailed information about flag evaluations: ```swift let client = OpenFeatureAPI.shared.getClient() let flagDetails: FlagEvaluationDetails = client.getDetails( key: "my-feature-flag", defaultValue: false ) print("Value: \(flagDetails.value)") print("Variant: \(flagDetails.variant ?? "unknown")") print("Reason: \(flagDetails.reason ?? "unknown")") ``` ## Configuration ### Provider Options | Option | Type | Required | Description | | ------------------- | ---------- | :------- | -------------------------------------------------------------------------------------------- | | `publicKey` | `String` | Yes | Your Hyphen API public key. | | `application` | `String` | Yes | The application id or alternate id. | | `environment` | `String` | Yes | The environment identifier for the Hyphen project (project environment ID or alternateId). | | `horizonUrls` | `[String]` | No | Custom Hyphen Horizon URLs for fetching flags. | | `enableToggleUsage` | `Bool` | No | Enable/disable telemetry (default: true). | ### Network Configuration | Property | Type | Default | Description | | :----------------- | :----- | :------ | :----------------------------------- | | `useCellularAccess`| Bool | true | Allow cellular network usage. | | `timeout` | Number | 10 | Request timeout in seconds. | | `maxRetries` | Number | 3 | Maximum retry attempts. | | `retryDelay` | Number | 3 | Delay between retries in seconds. | | `cacheExpiration` | Number | 900 | Cache TTL in seconds. | ### Evaluation Context | Field | Type | Required | Description | | :----------------- | :---------------------- | :------- | :---------------------------------------------------- | | `targetingKey` | `String` | Yes | Unique identifier used for caching and targeting. | | `CustomAttributes` | `[String: Value]` | No | Custom attributes for targeting rules. | | `User` | `Structure` | No | User information including Email, Name, Id. | | `User.CustomAttributes` | `[String: Value]` | No | User-level custom properties. | ## Example ```swift import Toggle import OpenFeature @main struct MyApp: App { init() { Task { await setupFeatureFlags() } } func setupFeatureFlags() async { // Initialize the provider let configuration = HyphenConfiguration( using: "your-public-key", application: "your-app-name", environment: "development" ) let provider = HyphenProvider(using: configuration) // Create evaluation context let context = hyphenEvaluationContext( targetingKey: "user-123", values: [ "CustomAttributes": .structure([ "plan": .string("premium"), "betaAccess": .boolean(true) ]), "User": .structure([ "Email": .string("user@example.com"), "Name": .string("John Doe") ]) ] ) // Set provider with context await OpenFeatureAPI.shared.setProviderAndWait( provider: provider, initialContext: context ) // Evaluate flags let client = OpenFeatureAPI.shared.getClient() let showNewFeature = client.getBooleanValue( key: "new-feature-enabled", defaultValue: false ) let theme = client.getStringValue( key: "app-theme", defaultValue: "light" ) print("New Feature Enabled: \(showNewFeature)") print("App Theme: \(theme)") } var body: some Scene { WindowGroup { ContentView() } } } ``` ### Create a Short Link URL: https://hyphen.ai/docs/url-shortening/create-short-link/ Description: Learn how to create custom short URLs using the Hyphen app and API, including setting up custom domains and tracking link performance. Take advantage of Hyphen’s URL-shortening service by creating custom short URLs, generating QR codes, and tracking user click/scan rates and geographic data for up to 12 months. ## Prerequisites - You have added a [Custom Domain](../introduction/custom-domain) to your Hyphen organization - Your Hyphen organization member account allows you to create a custom short URL in your organization. ## Creating a short URL in the Hyphen app 1. [Sign in to your Hyphen account](https://app.hyphen.ai). 2. In the main navigation, select **Link** 3. Click the **Create a short URL** button. 4. Enter the url you would like to shorten in the **Destination** field. - Optionally, give the link a label so that it's easier to find later on. If you do not give it a label, a time stamp will be used as the label. 5. Choose the [custom domain](../introduction/custom-domain) that you would like to use. 6. Enter a custom back-half to make your short URL more recognizable or unique. 7. Click **Create Short URL** to generate your short URL. Your new short URL will be automatically copied to your clipboard and ready for you to share. ## Create a short URL using the Hyphen API [Create a short URL using the Hyphen API](ref:post_api-organizations-organizationid-link-codes) ### Creating a Custom QR Code URL: https://hyphen.ai/docs/url-shortening/create-a-qr-code/ Description: Learn how to create and customize QR codes with your own branding, including logos and custom colors, to enhance your marketing efforts. This guide also covers the prerequisite of creating a short link. QR codes provide a convenient way to share links in a scannable format, making it easy for users to access information instantly on their mobile devices. They are especially useful in scenarios where typing a URL is impractical, such as on physical media (posters, business cards) or digital displays. ## Why Use QR Codes? - **Quick Access**: Users can scan a QR code to instantly access a website without typing a URL. - **Versatile Use**: QR codes are scannable by any smartphone camera, making them accessible to a wide audience. - **Customizable**: You can customize QR codes with colors, logos, and sizes to align with your brand. - **Trackable**: If linked to a short URL with analytics, you can monitor engagement metrics like total and unique clicks. ## Prerequisite: Create a Short Link Before you can create a QR code, you must first generate a short URL. If you haven't done this yet, see the guide to [Create a Short Link](create-short-link). Once your short link is ready, you can proceed with the steps below. ## Step-by-Step Instructions ![](https://files.readme.io/e5386359434f20dc9d89bb357bcf1467ed9bcd6c421c2ccbea1c5c74abff569a-Screenshot_2024-11-13_at_9.04.36_AM.png)
1. **Enter a Title (Optional)** - In the "Title" field, add a descriptive title for the QR code. This is optional but helps in organizing QR codes if you create multiple. If one is not provided, the current date/time will be used. 2. **Select the Size** - Use the "Size" dropdown menu to choose the dimensions of the QR code. Options might include Small, Medium, or Large, depending on your intended use. - Consider the intended use: a small QR code is ideal for digital screens, while larger sizes may be better for print. 3. **Upload a Logo (Optional)** - Click on "Upload Logo" to add a custom logo to the center of the QR code. - 1 Mb max size - A logo can make your QR code recognizable and aligned with your branding. 4. **Choose Foreground and Background Colors** - Click on the color box next to "Foreground Color" to change the color of the QR code itself. - Click on the color box next to "Background Color" to change the background color. - **Note**: Ensure high contrast between foreground and background colors to maintain QR code readability. 5. **Create the QR Code** - Once you've customized the settings, click the "Create QR Code" button. - Your QR code will be generated and displayed on the right side of the panel. 6. **Download or Save the QR Code** - After creating the QR code, you can download it to use in your marketing materials, websites, or print media. ### Metrics URL: https://hyphen.ai/docs/url-shortening/link-metrics/ Description: A comprehensive guide to understanding the key metrics and analytics available for your short URLs, including total clicks, unique clicks, referral sources, user locations, browser, and device usage. Every short url provides a detailed analytics dashboard, offering insights into user engagement. Here’s a breakdown of the available metrics and how to interpret them. ![](https://files.readme.io/e197564aa01c9d9ac5542ee7f81fc22c8bc536dd5ba6cd2bfdf861303ddc2be0-Screenshot_2024-11-13_at_8.42.44_AM.png)
## Key Metrics 1. **Total Clicks** * Shows the total number of times your short URL has been clicked over the specified time period. 2. **Unique Clicks** * Indicates the number of unique users who have clicked the URL. This excludes repeated clicks from the same user. 3. **Clicks Over Time** * A bar chart displays total and unique clicks across selected dates, allowing you to monitor engagement patterns over time. * The chart is customizable; use the dropdown to change the timeframe (e.g., last 7 days, last 30 days). 4. Referral URLs * Websites or sources that directed users to your short URL. This helps identify where your traffic is coming from. 5. User Locations * Geographic data, listing the countries from which users accessed the short URL. * This information can help you understand the regional reach of your links. 6. Browser Usage * The Browser Usage chart shows which browsers users are using to access the URL. * This data is categorized by browser type, such as Chrome, Safari, Firefox, etc., which is useful for ensuring compatibility across platforms. 7. Device Usage * This metric categorizes clicks by device type, showing the distribution between desktop and mobile users. * Understanding device usage can help optimize content for different platforms.
## Interpreting the Data * **Spike in Total Clicks**: High engagement on certain dates could be due to marketing campaigns or social media shares. * **High Unique Clicks, Low Total Clicks**: This suggests that most users clicked the link only once, which might indicate a single-use nature of the content or efficient information delivery. * **Dominant Browser or Device**: If most users access the link via mobile or a specific browser, it’s beneficial to ensure content appears correctly on those devices. * **Referral Patterns**: Frequent referrals from specific sites (like `docs.hyphen.ai`) indicate valuable sources of traffic and can guide future placement or promotion efforts. ### net.info - Quick Start URL: https://hyphen.ai/docs/net-info/netinfo-quickstart/ Description: A quick start guide to using the net.info service for IP address to location lookups, including API key creation and usage examples. [net.info](https://net.info) is a core service for cost-effective and scalable geo-location services.\ This service provided an easy-to-use IP address to location API. To learn more about the API go to our [API Reference](/docs/api). # Create an API Key To use the API you will need to create an API key. To create an API key, log on to the [Hyphen Dashboard](). Then go to `Settings` -> `API Keys` and click on `Create API Key`. Once this key is created you will want to save the secret in a secure location as you will not be able to see it again. # Using the API To use the API you will need to make a GET request to the following endpoint: ``` curl --request GET \ --url https://net.info/ip/ipAddress \ --header 'accept: application/json' \ --header 'authorization: Bearer YOUR_API_KEY' \ ``` Replace `ipAddress` with the ip address you want to look up. This will return a JSON object with the location information for the ip address. ```json { "ip": "string", "type": "private", "location": { "country": "string", "region": "string", "city": "string", "lat": 0, "lng": 0, "postalCode": "string", "timezone": "string", "geonameId": 0 } } ``` You are charged per lookup so make sure to use the API responsibly. Here is the pricing for the API: [https://hyphen.ai/pricing](https://hyphen.ai/pricing) # Bulk Lookups If you need to do bulk lookups you can use the bulk lookup API. This API allows you to look up multiple ip addresses at once. To use the bulk lookup API you will need to make a POST request to the following endpoint: ``` curl --request POST \ --url https://net.info/ip \ --header 'accept: application/json' \ --header 'authorization: Bearer YOUR_API_KEY' \ --header 'content-type: application/json' \ --data ' [ "1.1.1.1", "2.2.2.2", "3.3.3.3" ] ' ``` this will return a response similar to what you had before but with an `data` array of ip addresses. ```json { "data": [ { "ip": "string", "type": "private", "location": { "country": "string", "region": "string", "city": "string", "lat": 0, "lng": 0, "postalCode": "string", "timezone": "string", "geonameId": 0 } }, { "ip": "string", "type": "error", "errorMessage": "string" } ] } ``` ### AWS URL: https://hyphen.ai/docs/integrations/aws-integration/ Description: A comprehensive guide on setting up and configuring the AWS integration, including prerequisites, CloudFormation stack deployment, resource creation, and connection management. # Prerequisites This AWS integration relies on [IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html) to manage access. An Identity Store must be set up before the integration can be added to Hyphen. # Setup ### 1. Create or sign into your Amazon Web Services account [Sign in to the AWS console](https://console.aws.amazon.com/) _or_ [Create a new AWS account](https://aws.amazon.com/free) *** ### 2. Create an Organization in your AWS account If your account is not already part of an AWS Organization, [create one here](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_create.html). *** ### 3. Launch the CloudFormation Stack Click the button in the integration setup guide to open the pre-filled CloudFormation stack creation page. > The stack will automatically provision the required IAM Role, permissions, SSO Instance ID, and Administrator permission set for Hyphen. *** ### 4. Confirm IAM Resource Creation On the AWS CloudFormation page: * Scroll down to the **Capabilities** section. * Check the following box: **“I acknowledge that AWS CloudFormation might create IAM resources with custom names.”** Then click **Create stack**. *** ### 5. What Resources Will Be Created? When you launch the integration stack, Hyphen automatically provisions the following resources in your AWS account via CloudFormation: #### ✅ **IAM Role: `hyphen`** * Grants Hyphen access to perform specific actions in your AWS Organization and SSO. * Can only be assumed by Hyphen service principals: * `arn:aws:iam::640168453690:user/hyphen` * `arn:aws:iam::640168453690:role/hyphen-integration-role-prod` #### ✅ **Attached IAM Policy** * Grants only the minimum required permissions to: * Manage AWS Organizations (list/move/create accounts and OUs) * Access AWS SSO (list and assign permission sets) * Interact with AWS Identity Store (groups and memberships) > ⚠️ **Note:** All permissions are scoped to the minimum necessary for the integration to work securely. #### ✅ **Administrator SSO Permission Set** * Creates a new `AdministratorAccess` permission set in your AWS SSO instance. * Grants full admin access using AWS’s managed `AdministratorAccess` policy. * Used to assign roles to users through Hyphen. #### ✅ **SSO Instance Auto-Detection** * If multiple SSO instances exist, the oldest one is selected automatically. #### ✅ **Integration Registration** * The stack reports back to Hyphen with integration metadata: * AWS Account ID and Region * IAM Role ARN * SSO Instance ID * Admin Permission Set ARN *** ### Why Are These Resources Needed? Hyphen uses these resources to securely automate user, account, and permission management in your AWS environment — without requiring you to set things up manually. *** ### 6. Wait for Completion Once the stack is launched, the setup will run automatically in the background. > Please wait a moment — Hyphen will redirect you to the integration details page as soon as the setup is complete. *** # Configuration | **Field** | **Type** | **Description** | | ------------------ | ------------------- | ------------------------------------------------------------------------ | | `region` | `string` (required) | AWS region provided by the user, used for future requests. | | `accountId` | `string` (required) | AWS account ID provided by the user, used for future requests. | | `name` | `string` | Management account name, pulled during setup for reference and display. | | `identityStoreId` | `string` | Identity store ID, pulled during setup for reference and display. | | `identityStoreArn` | `string` | Identity store ARN, pulled during setup for reference and display. | | `permissionSetArn` | `string` | Admin permission set ARN, pulled during setup for reference and display. | *** # Connections ## Permission Group Permission Group connections link to AWS Groups in AWS IAM Identity Center. Hyphen will automatically create a new group if a connection input is not provided. When creating a new group, Hyphen will use the Team name. ### Configuration | **Field** | **Type** | **Description** | | ------------ | -------- | ------------------------------------------------------------ | | `groupId` | `string` | Unique group ID in AWS, used for reference and future calls. | | `instanceId` | `string` | `identityStoreId` from the integration configuration. | | `groupName` | `string` | Group name in AWS, used for display. | ### Connection Input Provide the AWS Group name to connect to an existing Group. ### Verification A verification email will be sent to the AWS Management Account email to verify existing groups. ### Access A User connection will be added as a member when added to the group. *** ## Folder Folder connections link to existing Organization Units in AWS or create a new one if none is provided. When creating a new organization unit, the Hyphen Project name will be used as the folder name, adjusted to contain only alphanumeric characters. ### Configuration | **Field** | **Type** | **Description** | | -------------------- | -------- | -------------------------------------------------------------- | | `organizationUnitId` | `string` | Unique organization unit ID in AWS, used for reference. | | `name` | `string` | Organization unit name in AWS, used for display and reference. | ### Connection Input Provide the AWS organization unit ID to connect to an existing Organization Unit. *** ## Cloud Workspace Cloud Workspace connections link to existing AWS Accounts or create a new one if none is provided. An AWS account relies on a Folder connection. If no Folder connection exists for the Hyphen project environment, a new Folder will be created. A Cloud Workspace connection requires a Google Workspace or Office 365 Distribution List. If neither exists, a new one will be created. When creating a new account, the account name will combine the Hyphen project name and environment name. ### Configuration | **Field** | **Type** | **Description** | | ----------- | -------- | ----------------------------------------------------------------- | | `accountId` | `string` | Unique account ID in AWS, used for reference and future requests. | | `name` | `string` | Account name in AWS, used for display and future requests. | | `parentId` | `string` | Parent folder connection `organizationUnitId`. | | `email` | `string` | Account or distribution list email, used for future requests. | ### Connection Input Provide the AWS account ID to connect to an existing Account. ### Verification A verification email will be sent to the AWS account email to verify existing accounts. ### Smart Access A Team connection will be added as a group when added to the account. *** ## User User connections link to AWS Users in AWS IAM Identity Center. Hyphen will not automatically create Users in AWS. If no connection input is provided, the Hyphen Member's email address will be used to look up the AWS User. ### Configuration | **Field** | **Type** | **Description** | | ------------ | -------- | ----------------------------------------------------- | | `userId` | `string` | Unique user ID in AWS. | | `email` | `string` | Email in AWS. | | `instanceId` | `string` | `identityStoreId` from the integration configuration. | | `username` | `string` | Unique username of the User in AWS | ### Connection Input Provide the username of the AWS User account to connect to an existing User. ## First Deployment: Why It May Take Longer During the first deployment, the platform must provision and initialize new infrastructure components required to run the application (such as compute, networking, and traffic routing services). These components need time to be created, validated, and become fully available across the system. In some cases, they also require global propagation before traffic can be routed reliably. As a result, even if the deployment reports success, the application may take a few additional minutes to become responsive on its first run. Subsequent deployments reuse the existing infrastructure and typically become available much faster. ### Azure URL: https://hyphen.ai/docs/integrations/azure-integration-setup-guide/ Description: A comprehensive guide to integrating with Azure, covering account setup, required permissions, OAuth scopes, and configuration details for various connection types. ## Setup 1. **Create or sign into your Azure account** 2. **Connect your Azure organization to Hyphen** - Sign in with your Azure account - Select the Azure tenant you wish to connect - Select a subscription to use for resource management > ⚠️ **Important:** The user performing the integration **must have the Global Administrator role** in the Azure Active Directory tenant and **must be assigned as Owner** on the subscription that will be used. That's it! After you've completed these steps, Hyphen will automatically: - Verify the credentials and selected tenant - Grant necessary permissions to the Hyphen service - Configure the required role assignments for resource management ## Required Permissions The one-click installation requires the following Microsoft Graph API permissions: - `CrossTenantInformation.ReadBasic.All` - `AppRoleAssignment.ReadWrite.All` - `Application.ReadWrite.All` - `RoleManagement.ReadWrite.Directory` ## Required OAuth Scopes To perform the setup and ongoing management securely, Hyphen requires access to the following Azure scope: ### `https://management.azure.com/user_impersonation` This scope allows Hyphen to manage resources across your Azure organization. It is required to: - List subscriptions and tenants - Create and manage resource groups - Assign roles and permissions to users and groups - Manage Azure resources on your behalf These permissions are necessary to let Hyphen create and manage Azure resources and access control on your behalf. *** # Configuration | **Field** | **Type** | **Description** | | ---------------- | ------------------- | --------------------------------------------------------------------------- | | `azureTenantId` | `string` (required) | Azure Tenant ID provided by the user, used to authenticate future requests. | | `subscriptionId` | `string` (required) | Azure Subscription ID provided by the user, used for future requests. | | `name` | `string` | Name pulled during setup, used for reference and display. | *** # Connections ## Permission Group Permission Group connections link to existing Azure Groups or create a new group if none is provided. When creating a new group in Azure, the name will be the Hyphen Team name. ### Configuration | **Field** | **Type** | **Description** | | ----------- | -------- | -------------------------------------------------------------- | | `groupId` | `string` | Unique group ID in Azure, used for reference and future calls. | | `groupName` | `string` | Group name in Azure, used for display. | ### Connection Input Provide the Azure group ID to connect to an existing group. ### Verification A verification email will be sent to the group owners' emails to verify existing groups. ### Access A Member connection will be added as a member when added to the group. *** ## Cloud Workspace Cloud Workspace connections link to existing Resource Groups in Azure or create a new one if none is provided. When creating a new resource group, the name will combine the Hyphen project name and the Hyphen project environment name. ### Configuration | **Field** | **Type** | **Description** | | ------------------- | -------- | -------------------------------------------------------------------------- | | `resourceGroupId` | `string` | Unique resource group ID in Azure, used for reference and future requests. | | `resourceGroupName` | `string` | Unique resource group name in Azure, used for display and reference. | ### Connection Input Provide the Azure resource group name to connect to an existing Resource Group. ### Access A Team connection will be added with the “Owner” role when added to the resource group. *** ## User User connections link to existing Azure Users. If no input is provided, the member email will be used to find the existing User. ### Configuration | **Field** | **Type** | **Description** | | --------- | -------- | --------------------------- | | `userId` | `string` | Unique user ID in Azure. | | `email` | `string` | Unique user email in Azure. | ### Connection Input Provide the Azure member email to connect to an existing User. ### Docker Hub URL: https://hyphen.ai/docs/integrations/docker-hub/ Description: A guide on how to set up and configure your Docker Hub organization for integration with Hyphen, including creating necessary access tokens and providing configuration details. # Setup 1. **Create or sign into your Docker Hub organization** 2. **Create an organization access token** While logged in as a user with administrative rights to the Docker Hub organization, use the Docker Hub Admin Console to create an Organization Access Token with these permissions: **Expiration Date** * None **Repository**: * Repository: All organization repositories * Scopes: check all boxes **Organization** * Scopes: check all boxes 3. **Create an admin user personal access token** **Expiration Date** * None **Access Permissions**: * Read, Write, Delete 4. **Connect Your Docker Hub organization to Hyphen** * Verify and enter the Organization name, access token, admin user name, and admin personal access token That's it! After you've completed these steps, Hyphen will automatically: * Grant necessary permissions to the Hyphen service * Configure the required role assignments for resource management
***
# Configuration
**Field** **Type** **Description**
`organizationName` `string` (required) Organization name
`adminUsername` `string` (required)
`secrets.encryptedOrganizationAccessToken` `string` (required) Organization access token with: * No expiration date * Access to all repositories and scopes * Access to all organization scopes
`secrets.encryptedPersonalAccessToken` `string` (required) Personal access token of Docker Hub organization admin user with: * No expiration date * Read, Write, Delete permissions
*** ### Google Cloud URL: https://hyphen.ai/docs/integrations/google-cloud-integration/ Description: A guide on how to set up and connect your Google Cloud organization with Hyphen, detailing required permissions, OAuth scopes, and connection types. # Setup ## 1. **Create or sign into your Google Cloud account** * [Sign in to Google Cloud console](https://console.cloud.google.com/)\ or * [Create a new Google Cloud account](https://cloud.google.com/docs/get-started) ## 2. **Connect your Google Cloud organization to Hyphen** * Sign in with your Google account * Select the GCP organization you wish to connect * (Optional) Select a billing account That's it! After you've completed these steps, Hyphen will automatically: * Verify the credentials and selected organization * Grant necessary permissions to the Hyphen service * Configure the domain-restricted sharing policy to allow access from Hyphen ## Required Permissions The one-click installation requires the following permissions: ``` resourcemanager.organizations.getIamPolicy resourcemanager.organizations.setIamPolicy resourcemanager.organizations.get billing.accounts.list orgpolicy.policies.create orgpolicy.policies.update orgpolicy.policies.get orgpolicy.policies.list resourcemanager.tagKeys.create resourcemanager.tagKeys.get resourcemanager.tagKeys.list resourcemanager.tagValues.create resourcemanager.tagValues.get resourcemanager.tagValues.list ``` ## Required OAuth Scopes To perform the setup and ongoing management securely, Hyphen requires access to specific Google Cloud scopes: ### `https://www.googleapis.com/auth/cloud-platform` This broad scope allows Hyphen to manage resources across your GCP organization. It is required to: * List organizations * Set the domain restricted sharing policy * Assign roles to the Hyphen service account, including: * Organization Administrator * Folder Creator * Project Creator * Artifact Registry Administrator * Compute Network Admin * Cloud Run Admin * Service Usage Admin * Billing Account User * Secret Manager Admin * Secret Version Manager * Service Account Admin * Service Account Key Admin * Tag Viewer * Tag User These roles are necessary to let Hyphen create and manage GCP projects and resources on your behalf. ### `https://www.googleapis.com/auth/cloud-billing.readonly` This scope allows Hyphen to: * List available billing accounts This is optional but recommended to allow you to associate a billing account during project creation. *** # Connections ## Permission Group Permission group connections correspond to Google Workspace distribution lists and require an existing Google Workspace integration within the Hyphen organization. Connections can link to existing Groups in Google Workspace, or a new group will be created if no input is provided. If a distribution list already exists for the same resource in Google Workspace, it will be used as the Permission Group connection. When creating a new Group in Google Workspace, the Hyphen team name will be used as the group name. ### Configuration | **Field** | **Type** | **Description** | | ------------ | -------- | --------------------------------------------------------- | | `groupId` | `string` | Unique group ID in Google Workspace. | | `groupName` | `string` | Display name of the group in Google Workspace. | | `groupEmail` | `string` | Unique group email used for reference in future requests. | ### Connection Input Provide the Google Workspace group email to create a connection to an existing Group. ### Verification | **Scenario** | **Action** | | ------------------ | ------------------------------------------------ | | Group has an owner | Verification handled by the owner. | | No owner exists | A verification email is sent to the group email. | *** ## Folder Folder connections can link to existing folders in Google Cloud, or a new folder will be created if no input is provided. When creating a new folder in Google Cloud, the Hyphen project name will be used as the folder name, adjusted to include only alphanumeric characters. ### Configuration | **Field** | **Type** | **Description** | | ------------ | -------- | ------------------------------------------- | | `folderId` | `string` | Unique folder ID in Google Cloud. | | `folderPath` | `string` | Path in the format `folders/{folderId}`. | | `folderName` | `string` | Display name of the folder in Google Cloud. | ### Connection Input Provide the Google Cloud folder ID to create a connection to an existing Folder. *** ## Cloud Workspace Cloud Workspace connections can link to existing projects in Google Cloud, or a new project will be created if no input is provided. A Google Cloud project relies on a Folder. If no Folder connection exists for the Hyphen project, a new Folder will be created. When creating a new project in Google Cloud, the project name will combine the Hyphen project name and the Hyphen project environment name. ### Configuration | **Field** | **Type** | **Description** | | ------------- | -------- | -------------------------------------------- | | `projectId` | `string` | Unique project ID in Google Cloud. | | `projectPath` | `string` | Path in the format `projects/{projectId}`. | | `projectName` | `string` | Display name of the project in Google Cloud. | ### Connection Input Provide the Google Cloud project ID to create a connection to an existing Project. ### Access A Team connection will be added with the "Owner" role when added to the project. *** ## User User connections correspond to Google Workspace users and require an existing Google Workspace integration within the Hyphen organization. User connections can only link to existing users in Google Workspace. If no input is provided, the member email will be used to locate the user. ### Configuration | **Field** | **Type** | **Description** | | --------- | -------- | -------------------------------------- | | `userId` | `string` | Unique user ID in Google Workspace. | | `email` | `string` | Unique user email in Google Workspace. | ### Connection Input A connection to an existing user can be created by providing the user email. [Test](#) [Connect](#) ### Google Workspace URL: https://hyphen.ai/docs/integrations/google-workspace-integration/ Description: A comprehensive guide on how to integrate with Google Workspace, covering account setup, service account authorization, and connection configurations for distribution lists and users. # Setup ### 1. **Create or sign into your Google Workspace account** * [Sign in to Google Admin Console](https://admin.google.com)\ or * [Create a new Google Workspace](https://workspace.google.com/) ### 2. **Authorize a service account for Hyphen to your Google Workspace** * In the Admin console, go to **Menu > Security > Access and data control > API controls > Manage Domain Wide Delegation**. *You must be signed in as a super administrator for this task.* * Click **Add new**. * Enter the service account ID for either the service account or the OAuth2 client. * In **OAuth Scopes**, add the following OAuth scopes and click **Authorize**. ``` https://www.googleapis.com/auth/admin.directory.group, https://www.googleapis.com/auth/admin.directory.group.member, https://www.googleapis.com/auth/admin.directory.user.alias.readonly, https://www.googleapis.com/auth/admin.directory.rolemanagement.readonly, https://www.googleapis.com/auth/admin.directory.group.member.readonly, https://www.googleapis.com/auth/admin.directory.group.readonly, https://www.googleapis.com/auth/admin.directory.user.readonly, https://www.googleapis.com/auth/admin.directory.domain.readonly, https://www.googleapis.com/auth/admin.reports.audit.readonly, https://www.googleapis.com/auth/apps.groups.settings ``` * Point to the new client ID, click **View details**, and make sure that every scope is listed. If a scope is not listed, click **Edit**, enter the missing scope, and click **Authorize**. *You can't edit the client ID.* More detailed information can be found at the Google Workspace documentation for [Setting up domain-wide delegation for a client](https://support.google.com/a/answer/162106?hl=en#zippy=%2Cset-up-domain-wide-delegation-for-a-client).\ Changes can take up to 24 hours but typically happen more quickly. ### 3. **Connect Workspace** Enter your workspace domain and admin user email to connect your Google Workspace account to Hyphen. * **Domain** * **Admin User Email** --- # Configuration | **Field** | **Type** | **Description** | | ---------------- | ------------------- | ---------------------------------------------------- | | `domain` | `string` (required) | Unique Google Workspace domain set by the user. | | `adminUserEmail` | `string` (required) | Unique Google Workspace admin email set by the user. | --- # Connections ## Distribution List Distribution List connections can link to existing Groups in Google Workspace, or a new group will be created if no input is provided. If a Permission Group already exists for the same resource within a Google Cloud integration, it will be used as the Distribution List connection. When creating a new Group in Google Workspace, the name will be a combination of the Hyphen project name and the Hyphen project environment name, or just the Hyphen project environment name. ### Configuration | **Field** | **Type** | **Description** | | -------------------- | -------- | --------------------------------------------------------- | | `distributionListId` | `string` | Unique group ID in Google Workspace used for reference. | | `name` | `string` | Group name in Google Workspace used for display. | | `email` | `string` | Unique group email used for reference in future requests. | ### Connection Input Provide the Google Workspace group email to create a connection to an existing Group. ### Verification | **Scenario** | **Action** | | ------------------ | ------------------------------------------- | | Group has an owner | Verification handled by the group owner. | | No owner exists | Verification email sent to the group email. | ### Access A Member connection will be added with the "Member" role when added to the group. *** ## User User connections can only link to existing Users in Google Workspace. If no input is provided to connect to an existing User, the member email will be used to locate the user. ### Configuration | **Field** | **Type** | **Description** | | --------- | -------- | -------------------------------------- | | `userId` | `string` | Unique user ID in Google Workspace. | | `email` | `string` | Unique user email in Google Workspace. | ### Connection Input Provide the Google Workspace email to create a connection to an existing User. [Test](#) [Connect](#) ### GitHub URL: https://hyphen.ai/docs/integrations/github-integration/ Description: Detailed guide on setting up and configuring the GitHub integration within the Hyphen application, including steps for organization connection, user, permission group, code repository, and project board configurations. # Setup On the Github integration page in the Hyphen app: 1. [Add Hyphen to your Github organization](https://github.com/apps/hyphen). 2. Submit your **GitHub Installation ID** and **Backup Verification Email** to connect it to Hyphen. If an integration connection cannot be automatically setup, the backup verification email will be sent a link where it can be verified manually. *** # Configuration | **Field** | **Type** | **Description** | | ------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `installationId` | `number` (required) | Unique installation ID generated when installing an application in GitHub. Used for generating an access token and pulling `githubOrgId` and `githubOrgName`. | | `githubOrgId` | `number` | Pulled during the integration setup. Used for reference. | | `githubOrgName` | `string` | Pulled during the integration setup. Used for requests that reference this key. | | `verificationEmail` | `string` (required) | Backup email address used to verify ownership of a resource when no associated email address is available. | *** # Connections ## User User connections can only connect to existing users in GitHub. If no input is provided to connect to an existing user, the member email will be used. **Prerequisites:** * Users must be "active" in the GitHub organization. ### Configuration | **Field** | **Type** | **Description** | | ------------ | ------------------- | ------------------------------------------------------------------------------------------------------ | | `userId` | `string` (optional) | GitHub username. | | `email` | `string` | Public email address of the GitHub user. Defaults to member email in Hyphen if not publicly available. | | `orgSlug` | `string` | The `githubOrgName` from the integration configuration. | | `profileUrl` | `string` | URL of the GitHub public profile page. | ### Connection Input A connection can be created by providing the GitHub username. ### Verification | **Scenario** | **Action** | | -------------------------------------------- | ----------------------------------------------------------------------------- | | Public email matches the member email | No verification needed. | | Public email does not match the member email | A verification email is sent to the GitHub user email address. | | No public email available | A verification email is sent to the integration's backup `verificationEmail`. | *** ## Permission Group These can connect to existing teams in GitHub, or a new team will be created if no input is provided. #### Configuration | **Field** | **Type** | **Description** | | ---------- | -------- | ----------------------------------------------------------------- | | `teamSlug` | `string` | Unique team slug in GitHub used for reference in future requests. | | `orgSlug` | `string` | The `githubOrgName` from the integration configuration. | | `teamName` | `string` | Display name of the team in GitHub. | | `teamId` | `number` | Unique team ID in GitHub. | ### Connection Input Provide the GitHub team name to create a connection to an existing team. ### Verification | **Scenario** | **Action** | | ------------------------------ | ------------------------------------------------------------------------ | | Admin with public email exists | Verification handled by the admin. | | No admin with public email | Verification email sent to the integration's backup `verificationEmail`. | #### Access A User connection will be added as the default “Member” role when added to the team. *** ## Code Repository These can connect to existing repositories in GitHub, or a new repository will be created if no input is provided. ### Configuration | **Field** | **Type** | **Description** | | ---------------- | -------- | ------------------------------------------------------- | | `repositoryId` | `string` | Unique repository ID in GitHub. | | `orgSlug` | `string` | The `githubOrgName` from the integration configuration. | | `repositoryName` | `string` | Repository name in GitHub for display and reference. | ### Connection Input Provide the GitHub repository name to create a connection to an existing repository. ### Verification A verification email is sent to the integration's `verificationEmail` for existing repositories. ### Access A Team connection will be added as a “Maintain” role when added to the code repository. *** ## Project Board These can connect to existing projects in GitHub, or a new project will be created if no input is provided. ### Configuration | **Field** | **Type** | **Description** | | ---------------- | -------- | ------------------------------------------------------------ | | `id` | `string` | Unique project ID in GitHub. | | `projectSlug` | `string` | GitHub project number used for reference in future requests. | | `orgSlug` | `string` | The `githubOrgName` from the integration configuration. | | `repositoryName` | `string` | Repository name in GitHub for display and reference. | ### Connection Input Provide the GitHub project slug to create a connection to an existing project. ### Verification A verification email is sent to the integration's `verificationEmail` for existing projects. ### Access A Team connection will be added as a “Read” role when added to the project. ### incident.io URL: https://hyphen.ai/docs/integrations/incidentio/ Description: A comprehensive guide to setting up and configuring the incident.io integration, including API key generation and connection management. # Setup ### 1. Sign in or create your incident.io account - [Sign in to incident.io](https://app.incident.io/login) _or_ - [Create an incident.io account](https://incident.io/) ### 2. Generate an API key 1. In the incident.io dashboard, go to **Settings** > **API keys**. - _You need admin permissions to access this section._ 2. Click **+ Add new** and provide a name for the API key (e.g., "Hyphen Integration"). 3. Select the following permissions for the API key: `catalog_editor` and `catalog_viewer`. These permissions ensure the API key has the necessary access to integrate with catalog teams and catalog services. 4. Once created, you will see the generated API key. Copy the API key and save it securely, as it won't be shown again. ### 3. Connect incident.io Enter the API key you generated to connect incident.io to Hyphen. --- # Configuration | **Field** | **Type** | **Description** | | ----------------------- | ------------------- | ------------------------------------------------------------------------------- | | `apiKey` | `string` (required) | Secret API key provided by the user. Encrypted and stored as `encryptedToken`. | | `organizationName` | `string` | Name of the organization pulled during integration setup for reference. | | `dashboardUrl` | `string` | URL of the dashboard pulled during integration setup for reference. | | `catalogServiceTypeId` | `string` | Service catalog type ID used for reference and future requests. | | `catalogUserTypeId` | `string` | User catalog type ID used for reference and future requests. | | `catalogTeamType` | `object` | Contains team catalog details. | |   `id` | `string` | ID used for future requests. | |   `memberAttributeId` | `string` | ID used for future access requests. | | `secrets` | `object` | Built during integration setup containing: | |   `encryptedToken` | `string` | Encrypted `apiKey` used to authenticate future requests. | --- # Connections ## Permission Group Permission groups connect to existing entries in the Teams catalog or create new entries if none are provided. When creating a new Teams entry, the name will match the Hyphen Team name. ### Configuration | **Field** | **Type** | **Description** | | --------------- | -------- | --------------------------------------------------- | | `teamId` | `string` | Unique ID in the Teams catalog used for reference. | | `teamName` | `string` | Name in the Teams catalog used for display. | ### Connection Input Provide the incident.io team entry ID to connect to an existing Teams entry. ### Access A Member connection will be added as a new attribute value when included in the Teams entry. --- ## User User connections link to existing Users in incident.io. If no input is provided, the member email will be used to search for an existing User. ### Configuration | **Field** | **Type** | **Description** | | --------------- | -------- | --------------------------------------------------- | | `userId` | `string` | Unique user ID in incident.io. | | `email` | `string` | Unique user email in incident.io. | ### Connection Input Provide the incident.io member email to connect to an existing User. --- ## Incident Management Incident management connections link to existing entries in the Service catalog or create new entries if none are provided. When creating a new Service entry, the name will match the Hyphen App name. ### Configuration | **Field** | **Type** | **Description** | | --------------- | -------- | ----------------------------------------------------- | | `serviceId` | `string` | Unique ID in the Service catalog used for reference. | | `serviceName` | `string` | Name in the Service catalog used for display. | ### Connection Input Provide the incident.io service entry ID to connect to an existing Service entry. ### JIRA URL: https://hyphen.ai/docs/integrations/jira/ Description: A comprehensive guide to setting up and configuring Jira integrations, including API token generation, ID retrieval, and connection management for users, permission groups, and project boards. # Setup ### 1. Create or sign into your Jira account [Sign in to Jira](https://www.atlassian.com/software/jira)\ *or* [Create a new Jira Cloud account](https://www.atlassian.com/try/cloud/signup) ### 2. Generate an API token 1. Go to [Atlassian API tokens](https://id.atlassian.com/manage/api-tokens) 2. Click "Create API token" 3. Give your token a label (e.g., "Hyphen Integration") 4. Copy the generated token - you'll need it in the next step ### 3. Get your Cloud ID and Organization ID 1. Go to [Atlassian Home](https://home.atlassian.com) 2. After logging in, check your browser's URL bar 3. Your Organization ID can be found in the URL:\ `https://home.atlassian.com/o/[your-org-id]` 4. Your Cloud ID can be found in your Jira instance URL:\ `https://[your-cloud-id].atlassian.net` ### 4. Connect Jira Enter your API token and IDs below to complete the integration. --- # Configuration | **Field** | **Type** | **Description** | | ---------------- | ------------------- | ------------------------------------------------------------------------------------ | | `cloudId` | `string` (required) | JIRA cloud ID provided by the user, used for future requests. | | `email` | `string` (required) | JIRA admin email provided by the user, used for reference and to authenticate future requests. | | `organizationId` | `string` (required) | Atlassian organization ID provided by the user, used for reference and future requests. | | `apiToken` | `string` (required) | Secret Atlassian API Token provided by the user. Encrypted and stored as `encryptedToken`. | | `secrets` | `object` | Built during integration config setup containing: | |   `encryptedToken` | `string` | Encrypted `apiToken` used to authenticate future requests. | | `accountId` | `string` | JIRA admin account ID, used for reference and display. | --- # Connections ### User User connections can only connect to existing Users in JIRA. If a connection is created without providing input to connect to an existing User, the member email will be used to try and find the existing User. #### Configuration | **Field** | **Type** | **Description** | | ---------------- | -------- | ------------------------------------------------ | | `userId` | `string` | JIRA user account ID. | | `email` | `string` | JIRA user email address or Hyphen member email. | | `displayName` | `string` | Display name of the JIRA user. | #### Connection Input Provide the JIRA email to connect to an existing User. #### Verification - No verification needed if the user's public email matches the member’s email. - If the emails don't match, a verification email will be sent to the JIRA user's email. --- ### Permission Group Permission Group Connections can connect to existing Groups in JIRA or one will be created if no connection input is provided. When creating a new group in JIRA, the Hyphen team name will be used as the group name. #### Configuration | **Field** | **Type** | **Description** | | ---------------- | -------- | ------------------------------------------------- | | `organizationId` | `string` | `organizationId` from the integration configuration. | | `groupName` | `string` | Group name in JIRA used for display. | | `groupId` | `number` | Unique group ID in JIRA. | #### Connection Input Provide the JIRA group name to connect to an existing Group. #### Verification Existing groups will be verified by the organization admin who set the email in the integration config. #### Access A User connection will be added as a member when added to the group. --- ### Project Board Project Board Connections can connect to existing Project Boards in JIRA or one will be created if no connection input is provided. When creating a new project board, the Hyphen App or Project name will be used as the project board name. The name will be converted to uppercase, spaces and hyphens will be removed, and only the first ten characters will be used. #### Configuration | **Field** | **Type** | **Description** | | ---------------- | -------- | ------------------------------------------------ | | `projectId` | `string` | Unique code project board ID in JIRA. | | `projectKey` | `string` | Unique code project board key in JIRA. | | `orgSlug` | `string` | `githubOrgName` from the integration configuration. | | `projectName` | `string` | Project board name in JIRA, used for display and reference. | #### Connection Input Provide the JIRA project board name to connect to an existing Project Board. #### Verification A verification email will be sent to the lead email to verify the existing project board. #### Access A Team connection will be added with a "Member" role when added to the project board. ### Microsoft Office 365 URL: https://hyphen.ai/docs/integrations/microsoft-office-365/ Description: A comprehensive guide to integrating Microsoft Office 365 with Hyphen, covering setup, required permissions, and configuration details. # Setup 1. **Create or sign into your Microsoft 365 account** To integrate with Microsoft Office 365, you'll need to sign in using an **educational or enterprise account** that has **Global Administrator** permissions on the tenant. 2. **Connect your Microsoft 365 tenant to Hyphen** * Sign in with your Microsoft 365 administrator account * Grant the required admin consent for the application * Select the Microsoft 365 tenant you wish to connect That's it! After you've completed these steps, Hyphen will automatically: * Verify the credentials and selected tenant * Grant necessary permissions to the Hyphen service ## Required Admin Consent Permissions During the authentication process, Hyphen will request the following permissions: - Application.ReadWrite.All - User.Read - AppRoleAssignment.ReadWrite.All - CrossTenantInformation.ReadBasic.All These permissions are required to: * Create the Hyphen service principal * Assign application roles to the service principal * Read tenant and organizational information * Obtain tenant information by ID ## Microsoft Graph API Permissions Granted by Hyphen Once the user is authenticated, Hyphen will automatically create a **service principal** in your tenant and consent the following Microsoft Graph permissions on your behalf: - Directory.Read.All - Group.ReadWrite.All - User.Read.All - Channel.Create - ChannelMember.ReadWrite.All - ChannelSettings.Read.All - Team.ReadBasic.All These permissions are necessary to: * Manage Azure AD groups and users * Read organization and tenant information * Create and manage distribution lists * Synchronize team membership with Office 365 groups These permissions enable Hyphen to create and manage Microsoft 365 groups and users on your behalf. *** # Configuration | **Field** | **Type** | **Description** | | --------------- | ------------------- | -------------------------------------------------------------------- | | `azureTenantId` | `string` (required) | Azure Tenant ID provided by the user for authentication purposes. | | `name` | `string` | Display name pulled during integration setup for reference purposes. | *** # Connections ## Distribution List Distribution list connections link to existing Azure Groups or create a new group if none is provided. When creating a new group, the name will match the Hyphen Organization, Team, Project, App, or Project Environment name. ### Configuration | **Field** | **Type** | **Description** | | -------------- | -------- | -------------------------------------------------------------- | | `groupId` | `string` | Unique group ID in Azure, used for reference and future calls. | | `groupName` | `string` | Group name in Azure, used for display and future requests. | | `emailAddress` | `string` | Group email address in Azure, used for display. | ### Connection Input Provide the Azure group ID to connect to an existing Group. ### Verification A verification email will be sent to the group email address to confirm ownership for existing groups. ### Access A Member connection will be added as a member when included in the group. *** ## User User connections link to existing Azure Users. If no input is provided, the member email will be used to search for an existing User. ### Configuration | **Field** | **Type** | **Description** | | --------- | -------- | --------------------------- | | `userId` | `string` | Unique user ID in Azure. | | `email` | `string` | Unique user email in Azure. | ### Connection Input Provide the Azure user email to connect to an existing User. ### Microsoft Teams URL: https://hyphen.ai/docs/integrations/microsoft-teams/ Description: A comprehensive guide on setting up and configuring Microsoft Teams integration with Hyphen, including necessary API permissions and connection details. # Setup 1. **Create or sign into your Microsoft 365 account** To integrate with Microsoft Office 365, you'll need to sign in using an **educational or enterprise account** that has **Global Administrator** permissions on the tenant. 2. **Connect your Microsoft 365 tenant to Hyphen** * Sign in with your Microsoft 365 administrator account * Grant the required admin consent for the application * Select the Microsoft 365 tenant you wish to connect That's it! After you've completed these steps, Hyphen will automatically: * Verify the credentials and selected tenant * Grant necessary permissions to the Hyphen service ## Required Admin Consent Permissions During the authentication process, Hyphen will request the following permissions: - Application.ReadWrite.All - User.Read - AppRoleAssignment.ReadWrite.All - CrossTenantInformation.ReadBasic.All These permissions are required to: * Create the Hyphen service principal * Assign application roles to the service principal * Read tenant and organizational information * Obtain tenant information by ID ## Microsoft Graph API Permissions Granted by Hyphen Once the user is authenticated, Hyphen will automatically create a **service principal** in your tenant and consent the following Microsoft Graph permissions on your behalf: - Directory.Read.All - Group.ReadWrite.All - User.Read.All - Channel.Create - ChannelMember.ReadWrite.All - ChannelSettings.Read.All - Team.ReadBasic.All These permissions are necessary to: * Manage Azure AD groups and users * Read organization and tenant information * Create and manage distribution lists * Synchronize team membership with Office 365 groups These permissions enable Hyphen to create and manage Microsoft 365 groups and users on your behalf. *** # Configuration | **Field** | **Type** | **Description** | | --------------- | ------------------- | ------------------------------------------------------------------------ | | `azureTenantId` | `string` (required) | Azure Tenant ID provided by the user. | | `name` | `string` | Name pulled during setup, used for reference and display. | | `defaultTeamId` | `string` | Default Team ID to create channels in when creating channel connections. | *** # Connections ## Permission Group Distribution list connections link to existing Microsoft Teams or create a new team if none is provided. When creating a new Team, the name will be the Hyphen Organization, Team, Project, App, or Project Environment name. ### Configuration | **Field** | **Type** | **Description** | | ------------- | -------- | -------------------------------------------------------------------------------- | | `groupId` | `string` | Unique group ID in the Azure tenant associated with the team, used for requests. | | `teamId` | `string` | Unique Team ID, used for future requests. | | `name` | `string` | Team name used for display. | | `externalUrl` | `string` | Direct URL to the associated Team, used for verification and dashboard links. | ### Connection Input Provide the Azure group ID to connect to an existing Group. If a Team exists for the Group, it will be used; otherwise, a new Team will be created for the Group. ### Verification A verification email will be sent to the group email to verify existing groups. ### Access A Member connection will be added as a member when added to the group. *** ## Channel Channel connections link to an existing Microsoft Teams channel or create a new private channel if none is provided. When creating a new Channel, the name will be the Hyphen Organization, Team, Project, App, or Project Environment name. ### Configuration | **Field** | **Type** | **Description** | | ------------- | -------- | -------------------------------------------------------------------------------- | | `name` | `string` | Name of the channel in Teams, used for display. | | `channelId` | `string` | Unique ID for the channel in Teams, used for future requests. | | `teamId` | `string` | Unique ID for the Team this channel is a part of, used for requests. | | `externalUrl` | `string` | Direct URL to the associated Channel, used for verification and dashboard links. | ### Connection Input Provide the channel name to connect to an existing Channel. ### Verification A verification email will be sent to the channel admin emails to verify existing channels. ### Access A member connection created for the associated Hyphen entity will automatically add or remove members in the Teams channel. *** ## User User connections link to existing Users in the associated Azure tenant. If no input is provided, the member email will be used to find the existing User. ### Configuration | **Field** | **Type** | **Description** | | --------- | -------- | --------------------------- | | `userId` | `string` | Unique user ID in Azure. | | `email` | `string` | Unique user email in Azure. | ### Connection Input Provide the Azure member email to connect to an existing User. ### New Relic URL: https://hyphen.ai/docs/integrations/new-relic/ Description: A comprehensive guide to setting up the New Relic integration, including account creation, API key generation, and connection configuration. # Setup ### 1. Create or sign into your New Relic account New Relic uses API keys to authenticate and verify your identity. These keys allow approved people to: - Report data to New Relic - Access and query your data - Configure features and settings [Sign in to New Relic](https://login.newrelic.com/login) _or_ [Create a new New Relic account](https://newrelic.com/signup) ### 2. Generate User API Key You'll need a User API key to access NerdGraph, New Relic's GraphQL API. This key is essential for: - Querying data from your New Relic account - Configuring features and settings - Managing user access and permissions [Go to API Keys UI to generate your key](https://one.newrelic.com/launcher/api-keys-ui.api-keys-launcher) #### Required API Key Permissions: - User management - Authentication domain management - Group management #### Security Recommendations: - Keep your API keys secure and treat them like passwords - Implement key rotation strategy for license and browser keys - Remove user IDs when team members leave the organization - Create additional ingest keys instead of using original ones for better security ### 3. Connect New Relic Account Enter your User API key below to complete the integration. This key will be used to: - Authenticate your account - Enable data access and management - Configure integration settings --- # Configuration | **Field** | **Type** | **Description** | | ------------------ | ------------------- | ------------------------------------------------------------------------------------ | | `apiKey` | `string` (required) | Secret New Relic API key provided by the user. Encrypted and stored as `encryptedToken`. | | `accountId` | `string` | Account ID pulled during integration config setup for reference. | | `accountName` | `string` | Account name pulled during integration config setup for reference. | | `secrets` | `object` | Built during integration setup containing: | |   `encryptedToken` | `string` | Encrypted `apiKey` used to authenticate future requests. | --- # Connections ## Permission Group Permission groups can connect to existing New Relic Groups or create new ones if no connection input is provided. When creating a new Group in New Relic, the name will be the Hyphen Team name. ### Configuration | **Field** | **Type** | **Description** | | ---------------- | -------- | ------------------------------------------------- | | `groupId` | `string` | Unique group ID in the New Relic group. | | `groupName` | `string` | Group name in the New Relic group. | ### Connection Input Provide the New Relic group ID to connect to an existing Group. ### Access A Member connection will be added as a member when added to the group. --- ## User User connections link to existing Users in New Relic. If no input is provided, the member email will be used to try and find the existing User. ### Configuration | **Field** | **Type** | **Description** | | ---------------- | -------- | ------------------------------------------------ | | `userId` | `string` | Unique user ID in New Relic. | | `email` | `string` | Unique user email in New Relic. | ### Connection Input Provide the New Relic member email to connect to an existing User. ### NPM URL: https://hyphen.ai/docs/integrations/npm/ Description: A comprehensive guide on setting up and configuring NPM integration, including account creation, access token generation, and connection management for teams, users, and code registries. # Setup ### 1. Create or sign into your NPM account [Sign in to NPM](https://www.npmjs.com/login) _or_ [Create a new NPM account](https://www.npmjs.com/signup) ### 2. Generate Access Token [Follow the NPM documentation to create an access token](https://docs.npmjs.com/creating-and-viewing-access-tokens) Make sure to grant the following permissions: - Read and write organization members - Read and write teams - Read and write packages ### 3. Connect NPM Organization Enter your Access Token below to complete the integration. --- # Configuration | **Field** | **Type** | **Description** | | ---------------- | ------------------- | ------------------------------------------------------------------------------------ | | `accessToken` | `string` (required) | Secret NPM access token provided by the user. Encrypted and stored as `encryptedToken`. | | `organizationName`| `string` (required) | NPM organization name provided by the user, used for reference in future requests. | | `secrets` | `object` | Built during integration config setup containing: | |   `encryptedToken` | `string` | Encrypted `accessToken` used to authenticate future requests. | --- # Connections ## Permission Group Permission group connections can link to existing NPM Teams or create new ones if no connection input is provided. When creating a new Team in NPM, the name will be the Hyphen Team name. ### Configuration | **Field** | **Type** | **Description** | | ---------------- | -------- | ------------------------------------------------- | | `teamId` | `string` | Unique team ID in the NPM team. | | `teamName` | `string` | Team name in the NPM team, used for reference. | ### Connection Input Provide the NPM team name to connect to an existing Team. ### Access A Member connection will be added as a member when added to the NPM team. --- ## User User connections can only connect to existing Users in NPM by providing input. ### Configuration | **Field** | **Type** | **Description** | | ---------------- | -------- | ------------------------------------------------ | | `userId` | `string` | Unique username in NPM. | | `email` | `string` | Hyphen member email, used for display. | ### Connection Input Provide the NPM username to connect to an existing User. --- ## Code Registry Code registry connections can only connect to existing NPM packages within the NPM organization using a provided input. ### Configuration | **Field** | **Type** | **Description** | | ---------------- | -------- | ------------------------------------------------- | | `packageId` | `string` | Unique package name in the NPM organization. | | `packageName` | `string` | Unique package name in the NPM organization, used for display. | ### Connection Input Provide the NPM package name to connect to an existing Package. ### Access A Team connection will be added with ‘read-write’ permissions when added to the NPM package. ### Slack URL: https://hyphen.ai/docs/integrations/slack-integration/ Description: A guide to setting up and configuring Slack integrations, including details on workspace, channel, and user connections. # Setup ### 1. **Add Hyphen to your Slack workspace** * [Install the App](#) *** # Configuration | **Field** | **Type** | **Description** | | ---------------- | ------------------- | -------------------------------------------------------------------------------- | | `workspaceId` | `string` | Unique workspace ID pulled during setup, used for reference and future requests. | | `workspaceName` | `string` | Workspace name pulled during setup, used for reference and display. | | `secrets` | `object` (required) | Contains authentication information for future requests. | | `encryptedToken` | `string` (required) | Encrypted Slack token, retrieved when installing a Slack app. | *** # Connections ## Channel Channel connections link to existing Slack Channels or create a new public channel if none is provided. When creating a new channel, the name will be normalized to include only lowercase letters, numbers, hyphens, and underscores, and must be 80 characters or fewer. The name will match the Hyphen Organization, Team, Project, or App name. ### Configuration | **Field** | **Type** | **Description** | | ------------- | -------- | ---------------------------------------------------------------- | | `id` | `string` | Unique channel ID in Slack, used for reference and future calls. | | `name` | `string` | Channel name in Slack, used for display and future requests. | | `workspaceId` | `string` | `workspaceId` from the integration configuration. | ### Connection Input Provide the Slack channel name to connect to an existing channel. ### Verification * Existing public channels do not require verification. * Private channels require verification from an admin with a public email in their profile. ### Access A Member connection will be invited to the channel. *** ## User User connections link to existing Slack Users. If no input is provided, the member email will be used to search for the existing User. ### Configuration | **Field** | **Type** | **Description** | | ------------- | -------- | ------------------------------------------------- | | `userId` | `string` | Unique user ID in Slack. | | `email` | `string` | Unique user email in Slack. | | `userName` | `string` | User's display name in Slack. | | `workspaceId` | `string` | `workspaceId` from the integration configuration. | ### Connection Input Provide the Slack user email to connect to an existing User. ### hx Command Line URL: https://hyphen.ai/docs/github-actions/setup-command-line/ Description: A GitHub Action to download, install, and authenticate the Hyphen command line tool (hx). This GitHub Action downloads, installs, and authenticates the Hyphen command line tool (hx) using the provided API Key. Once the action is run, the `hx` CLI will be available in the path of the action container and can be used in subsequent steps. > 📘 Many other Hyphen actions require this action to be run first, as they rely on the `hx` CLI being available in the container's path. ## Prerequisites Before getting started, ensure you have: * Signed up for a Hyphen account and have access to an organization * You have access to a Hyphen API key for the organization ## Parameters * **`apiKey`***(required)*: The API key used to authenticate the command line tool. * **`version`** *(optional)*: The specific version of the command line to install. If not set, the latest version will be installed. ## Example Usage ```yml action.yml steps: - name: Checkout id: checkout uses: actions/checkout@v4 - name: Setup Hyphen CLI id: setup-hx uses: Hyphen/setup-hx-action@v1 with: apiKey: ${{ secrets.HYPHEN_API_KEY }} - name: List Projects id: list-projects run: hx project list ``` ### Specifying a Version ```Text action.yml steps: - name: Setup Hyphen CLI with Specific Version uses: Hyphen/setup-hx-action@v1 with: apiKey: ${{ secrets.HYPHEN_API_KEY }} version: "1.2.3" # specify the desired version here ``` ### Security & Technology URL: https://hyphen.ai/docs/policies/security-and-technology/ Description: Comprehensive overview of Hyphen AI's security policies, risk management, access controls, business continuity, data protection, and incident response procedures. Hyphen AI is committed to providing a secure, reliable platform for managing your application deployments, secrets, and infrastructure. This document outlines our security policies and practices. ## Security Policy, Risk, and Governance Hyphen AI conducts regular risk assessments covering: - Information security risks - Operational and infrastructure risks - Compliance and regulatory risks - Third-party and vendor risks Identified risks are classified by severity and prioritized for remediation based on likelihood and impact. Risk register is maintained and reviewed on a regular cadence. Regular compliance validation activities include: - Backup restoration testing - Access reviews across all systems - Vendor management review - Risk assessment and monitoring - Technical compliance validation - Policy and documentation review - Recovery objective validation ## Access Management ### Authentication & Authorization Access to Hyphen AI systems and customer data is controlled through: - Role-based access control with defined permissions - Multi-factor authentication (MFA) enforced for all accounts - Single sign-on (SSO) integration capabilities - API key authentication with audit trails ### Access Control Principles **Internal access follows:** - **Least Privilege:** Users granted minimum access needed for their role - **Need-to-Know:** Access based on job function and business need - **Regular Review:** Periodic verification that access remains appropriate **Administrative access:** - Limited to essential personnel - Subject to additional controls and monitoring - All administrative actions logged and auditable ### Access Review Process - Regular reviews of user accounts, administrative access, and infrastructure permissions - Dormant account detection and remediation - Timely access removal upon identification of unnecessary permissions - Access revocation procedures for departing team members ### Audit Logging All access to systems and customer data is logged, including: - Authentication events and access attempts - Administrative actions and configuration changes - Data access and modifications - Access logs are retained and available for audit purposes ## Business Continuity & Disaster Recovery ### Operations - Fully remote operations with no dependency on physical office locations - Distributed team structure for operational resilience - Communication and collaboration infrastructure with high availability ### Backup & Recovery - Automated database backups with defined retention policies - Configuration and infrastructure definitions version controlled - Multi-zone data replication for redundancy - Defined Recovery Time Objectives (RTO) for critical services - Defined Recovery Point Objectives (RPO) to limit data loss - Regular backup restoration testing to validate recovery procedures ### Service Dependencies Hyphen AI infrastructure relies on enterprise-grade cloud platforms with: - Multi-zone and multi-region deployment capabilities - High availability service level agreements - Built-in redundancy and automatic failover - Established disaster recovery capabilities *Note: These recovery objectives apply to Hyphen AI systems. Customer-specific data recovery scenarios are addressed through product capabilities documented separately.* ## Communications Security ### Network Security - All communications encrypted in transit using industry-standard protocols - API endpoints secured with SSL/TLS - Network segmentation and access controls - Multi-zone deployments for availability and resilience ### Monitoring - Continuous monitoring of systems and infrastructure - Security event logging and analysis - Automated alerting for anomalous activity - Centralized log aggregation and retention ## Cryptography & Encryption ### Encryption Architecture Hyphen AI employs a zero-knowledge encryption architecture for secrets management: - Customer secrets encrypted locally using either Hyphen AI-managed or customer-managed encryption keys - Encryption and decryption operations performed client-side - Sensitive data never accessible to Hyphen AI in plaintext ### Data Protection - Data encrypted at rest using industry-standard encryption - Data encrypted in transit using SSL/TLS - Encryption key rotation capabilities available - Cryptographic operations follow industry best practices ### Customer Data Isolation - Customer data logically isolated and access-controlled - Cloud provider integrations follow principle of least privilege - Temporary credentials and role assumption where applicable - Permissions scoped to minimum required for functionality ## Operations ### Infrastructure Hyphen AI infrastructure is deployed across multiple cloud providers: - Multi-zone deployments for high availability - Regional redundancy for critical services - Automated deployment and configuration management - Infrastructure as code for consistency and auditability ### Change Management All changes to production systems follow a defined process: - Peer review required before deployment - Automated testing and validation - Staged rollout procedures - Documented rollback capabilities - Emergency change procedures with appropriate approval and documentation ### Version Control - All code and configuration changes version controlled - Full audit trail of changes with attribution - Rollback capabilities for recovery - Protection against unauthorized modifications ## Privacy Hyphen AI's architecture is designed to protect customer privacy: - Customer data encrypted end-to-end with either Hyphen AI-managaed or customer-managed keys - Customers maintain complete control over their sensitive data - Data collection limited to what is necessary to provide services - Compliance with applicable data protection regulations ## Security Incident Management ### Incident Classification Security incidents are classified by severity with corresponding response procedures: - **Critical** incidents: Active breach, data exposure, complete service outage - **Major** incidents: Suspected compromise, significant service degradation - **Minor** incidents: Security vulnerability, limited impact ### Response Process Hyphen AI follows a structured incident response process: 1. **Detection & Reporting** - Incident declaration and team mobilization 2. **Assessment** - Severity determination and scope identification 3. **Containment** - Immediate actions to limit impact 4. **Investigation** - Root cause analysis and impact assessment 5. **Resolution** - Remediation and service restoration 6. **Post-Incident Review** - Lessons learned and preventive measures ### Customer Communication Customers are notified promptly for: - Data breaches or potential exposure of customer data - Extended service outages affecting availability - Security incidents that may impact customer operations Breach notifications follow applicable regulatory requirements including GDPR, CCPA, and other relevant data protection laws. ## Supplier Management Third-party vendors that process, store, or transmit data are evaluated for: - Security posture and certifications (SOC 2, ISO 27001, or equivalent) - Data handling and privacy practices - Access controls and audit capabilities - Availability commitments and historical reliability - Compliance with data protection regulations (GDPR, CCPA) Critical vendors are reviewed regularly to ensure: - Security certifications remain current - Service quality meets commitments - No material changes to data handling or security practices - Continued alignment with Hyphen AI security standards ## System Acquisition, Development, and Maintenance ### Secure Development Practices - Security considerations integrated throughout development lifecycle - Code review requirements for all changes - Automated security testing in deployment pipelines - Dependency scanning and vulnerability management - Secure coding standards and developer training ### Change Control Production changes are managed through: - Documented change control processes - Peer review and approval requirements - Automated testing and validation - Rollback procedures for failed changes - Exception processes for emergency security fixes with appropriate oversight ## Questions & Support For questions about our security practices or to report a security concern email help@hyphen.ai. --- *Last updated: 2025-10-30* ## API Reference URL: https://hyphen.ai/docs/api ### Hyphen API OpenAPI Spec URL: https://api.hyphen.ai/docs/json ### Net.Info API OpenAPI Spec Source: /home/runner/work/public-website/public-website/docs-site/api/net-info/swagger.json { "openapi": "3.0.3", "info": { "title": "@net.info/net-info", "description": "\nEnable location-based experiences, security and analytics with city-level ip geolocation information, \nincluding latitude, longitude, time zone, postal code, and more.\n\nTo learn more about this service visit [docs.hyphen.ai](https://docs.hyphen.ai)\n", "version": "3.6.6" }, "components": { "schemas": {} }, "paths": { "/ip": { "get": { "summary": "get your ip info", "tags": [ "ip address" ], "parameters": [ { "schema": { "type": "string", "pattern": "^org_[a-fA-F0-9]{24}$" }, "in": "query", "name": "organizationId", "required": false, "description": "The organization Id." } ], "responses": { "200": { "description": "Successfully got user IP info", "headers": { "X-Cache": { "schema": { "type": "string", "enum": [ "HIT", "MISS" ] }, "description": "The cache status of the response." } }, "content": { "application/json": { "schema": { "type": "object", "description": "Successfully got user IP info", "properties": { "ip": { "type": "string" }, "type": { "type": "string", "enum": [ "private", "public" ] }, "location": { "type": "object", "properties": { "country": { "type": "string" }, "region": { "type": "string" }, "city": { "type": "string" }, "lat": { "type": "number" }, "lng": { "type": "number" }, "postalCode": { "type": "string" }, "timezone": { "type": "string" }, "geonameId": { "type": "number" } }, "required": [ "country", "region", "city", "lat", "lng", "postalCode", "timezone", "geonameId" ] } }, "required": [ "ip", "type" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "description": "Bad Request", "properties": { "statusCode": { "type": "number", "enum": [ 400 ] }, "error": { "type": "string", "enum": [ "Bad Request" ] }, "message": { "type": "string", "description": "The error message." } }, "example": { "statusCode": 400, "error": "Bad Request", "message": "Invalid IP Address" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "description": "Forbidden", "properties": { "statusCode": { "type": "number", "enum": [ 403 ] }, "error": { "type": "string", "enum": [ "Forbidden" ] }, "message": { "type": "string", "description": "The error message." } }, "example": { "statusCode": 403, "error": "Forbidden", "message": "Forbidden" }, "type": "object" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "description": "Not Found", "properties": { "statusCode": { "type": "number", "enum": [ 404 ] }, "error": { "type": "string", "enum": [ "Not Found" ] }, "message": { "type": "string", "description": "The error message." } }, "example": { "statusCode": 404, "error": "Not Found", "message": "IP Address not found: ::1" }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error", "properties": { "statusCode": { "type": "number", "enum": [ 500 ] }, "error": { "type": "string", "enum": [ "Internal Server Error" ] }, "message": { "type": "string", "description": "The error message." } }, "example": { "statusCode": 500, "error": "Internal Server Error", "message": "Unable to lookup Ip: ::1" }, "type": "object" } } } } } }, "post": { "summary": "get bulk ip info", "tags": [ "ip address" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string", "description": "The IP address." }, "uniqueItems": true, "minItems": 1, "maxItems": 100 } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^org_[a-fA-F0-9]{24}$" }, "in": "query", "name": "organizationId", "required": false, "description": "The organization Id." } ], "responses": { "200": { "description": "Successfully get bulk IP info", "content": { "application/json": { "schema": { "type": "object", "description": "Successfully get bulk IP info", "properties": { "data": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "ip": { "type": "string" }, "type": { "type": "string", "enum": [ "private", "public" ] }, "location": { "type": "object", "properties": { "country": { "type": "string" }, "region": { "type": "string" }, "city": { "type": "string" }, "lat": { "type": "number" }, "lng": { "type": "number" }, "postalCode": { "type": "string" }, "timezone": { "type": "string" }, "geonameId": { "type": "number" } }, "required": [ "country", "region", "city", "lat", "lng", "postalCode", "timezone", "geonameId" ] } }, "required": [ "ip", "type" ] }, { "type": "object", "properties": { "ip": { "type": "string" }, "type": { "type": "string", "enum": [ "error" ] }, "errorMessage": { "type": "string", "description": "Error message" } }, "required": [ "ip", "type", "errorMessage" ] } ] } } }, "required": [ "data" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "description": "Bad Request", "properties": { "statusCode": { "type": "number", "enum": [ 400 ] }, "error": { "type": "string", "enum": [ "Bad Request" ] }, "message": { "type": "string", "description": "The error message." } }, "example": { "statusCode": 400, "error": "Bad Request", "message": "Invalid IP Address" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "description": "Forbidden", "properties": { "statusCode": { "type": "number", "enum": [ 403 ] }, "error": { "type": "string", "enum": [ "Forbidden" ] }, "message": { "type": "string", "description": "The error message." } }, "example": { "statusCode": 403, "error": "Forbidden", "message": "Forbidden" }, "type": "object" } } } } } } }, "/ip/{ipAddress}": { "get": { "summary": "get ip info", "tags": [ "ip address" ], "parameters": [ { "schema": { "type": "string", "pattern": "^org_[a-fA-F0-9]{24}$" }, "in": "query", "name": "organizationId", "required": false, "description": "The organization Id." }, { "schema": { "type": "string" }, "in": "path", "name": "ipAddress", "required": true, "description": "The IP address." } ], "responses": { "200": { "description": "Successfully got IP info", "headers": { "X-Cache": { "schema": { "type": "string", "enum": [ "HIT", "MISS" ] }, "description": "The cache status of the response." } }, "content": { "application/json": { "schema": { "type": "object", "description": "Successfully got IP info", "properties": { "ip": { "type": "string" }, "type": { "type": "string", "enum": [ "private", "public" ] }, "location": { "type": "object", "properties": { "country": { "type": "string" }, "region": { "type": "string" }, "city": { "type": "string" }, "lat": { "type": "number" }, "lng": { "type": "number" }, "postalCode": { "type": "string" }, "timezone": { "type": "string" }, "geonameId": { "type": "number" } }, "required": [ "country", "region", "city", "lat", "lng", "postalCode", "timezone", "geonameId" ] } }, "required": [ "ip", "type" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "description": "Bad Request", "properties": { "statusCode": { "type": "number", "enum": [ 400 ] }, "error": { "type": "string", "enum": [ "Bad Request" ] }, "message": { "type": "string", "description": "The error message." } }, "example": { "statusCode": 400, "error": "Bad Request", "message": "Invalid IP Address" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "description": "Forbidden", "properties": { "statusCode": { "type": "number", "enum": [ 403 ] }, "error": { "type": "string", "enum": [ "Forbidden" ] }, "message": { "type": "string", "description": "The error message." } }, "example": { "statusCode": 403, "error": "Forbidden", "message": "Forbidden" }, "type": "object" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "description": "Not Found", "properties": { "statusCode": { "type": "number", "enum": [ 404 ] }, "error": { "type": "string", "enum": [ "Not Found" ] }, "message": { "type": "string", "description": "The error message." } }, "example": { "statusCode": 404, "error": "Not Found", "message": "IP Address not found: ::1" }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error", "properties": { "statusCode": { "type": "number", "enum": [ 500 ] }, "error": { "type": "string", "enum": [ "Internal Server Error" ] }, "message": { "type": "string", "description": "The error message." } }, "example": { "statusCode": 500, "error": "Internal Server Error", "message": "Unable to lookup Ip: ::1" }, "type": "object" } } } } } } }, "/ping": { "get": { "summary": "ping", "tags": [ "system" ], "description": "Ping route to check server status", "security": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "description": "Successful response", "type": "object", "properties": { "pong": { "type": "string" } } } } } } } } }, "/healthz": { "get": { "summary": "healthz", "tags": [ "system" ], "description": "Health Check Route", "security": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "description": "Successful response", "type": "object", "properties": { "status": { "type": "string" } } } } } } } } } }, "servers": [ { "url": "https://net.info" } ] } ## Changelog URL: https://hyphen.ai/docs/changelog ### Agent Can Optimize Your Deployment Environment URL: https://hyphen.ai/docs/changelog/agent-can-optimize-your-deployment-environment Date: April 9, 2026 Tag: added
You can now ask the **Hyphen Agent** to optimize a project environment based on real workload behavior. When prompted, the Agent creates an optimizer task, analyzes CPU usage, memory usage, and traffic patterns, and generates ranked configuration recommendations to better align infrastructure with demand. --- ### What’s new - The notification badge now displays the Agent tasks that need approval - Prompt the Agent to **optimize a project environment** - Automatic investigation of **CPU, memory, and requests per second** - Ranked recommendations for environment configuration improvements - Suggested updates to **min and max instance counts** - Suggested updates to **traffic region placement** - Support for **provider- and region-specific scaling adjustments** - Deployment runs triggered after approved changes are applied --- ### How it works The Agent creates an optimizer task and evaluates the selected project environment. It then produces a sequence of recommended configuration updates. Each recommendation: - includes the proposed change - identifies region and provider scope - is labeled with a risk level - may require approval before execution Depending on the **severity** and **confidence** of a recommendation, the Agent may apply changes automatically or request approval before proceeding. --- ### Why this matters Right-sizing infrastructure is usually manual and reactive. The Optimizer skill evaluates real usage signals and proposes targeted improvements so your environment better matches workload demand. - Reduce cloud spend from unused capacity - Improve responsiveness during traffic spikes - Strengthen availability configuration - Adapt infrastructure to real regional demand patterns --- ### Things to know - Optimization runs as an **Agent task** with investigation and recommendation phases - The Agent ranks the severity of each recommendation to determine whether approval is required - High risk changes require approval before execution - Recommendations are scoped to the selected **project environment** - Future releases will allow approval behavior to be controlled by policies ### Project UX Updated Around Environments URL: https://hyphen.ai/docs/changelog/project-ux-update Date: March 31, 2026 Tag: improved
Projects now center around **project environments** as the primary way to configure and understand deployments. With the move to a [one-to-one relationship between project environments and deployment configuration](project-environment-types-and-one-to-one-deployment-policies), the Project experience has been updated to make environments the main entry point for deployment settings and resource architecture visibility. Each environment now represents its own deployment configuration, replacing the previous model based on named deployment policies. --- ### What’s new - Projects now reflect a **one-to-one relationship** between environments and deployment configuration - The environment of type `development` is the default selected environment. - Deployment settings are configured directly on **project environments** - Named deployment policies are no longer the primary configuration surface. The project environment name or alternateId is. - If a project environment is deployed, a **resource architecture diagram** for the selected environment is displayed, otherwise an option to set up the deployment is displayed - Environment selection now determines the infrastructure view and settings shown --- ### Why this matters This update makes deployment configuration easier to understand by aligning infrastructure settings with the environments they affect. - Clearer mental model for how deployments are structured - Environment-specific infrastructure visibility - Simpler navigation between development, production, and other custom environment setups - Fewer indirections when configuring deployment behavior --- ### Things to know - Deployment configuration now lives on project environments - Resource architecture diagrams reflect the selected environment - Each environment represents a single deployment configuration - Named deployment policies have been replaced by environment-based configuration ### Project Environment Types and One-to-One Deployment Policies URL: https://hyphen.ai/docs/changelog/project-environment-types-and-one-to-one-deployment-policies Date: March 23, 2026 Tag: improved Project environments now have clearer roles and a simpler deployment model. You can now assign a **type** to each project environment and map exactly **one deployment policy** to each environment. Deployment policies are now environment-specific, replacing the previous model where a single policy could target multiple environments. Each environment now acts as the primary anchor for its deployment configuration, making infrastructure behavior more predictable across development and production workflows. *** ### What’s new * Assign environment types: **development**, **production**, or **custom** * Only one **development** environment is allowed per project * Only one **production** environment is allowed per project * Each environment now maps to exactly **one deployment policy** * Deployment policies can no longer target multiple environments * Deployments are now directly associated with their **project environment** *** ### Why this matters Environments now represent distinct lifecycle stages with dedicated infrastructure behavior. One-to-one policy mapping removes ambiguity and makes deployments easier to reason about across teams and projects. * Clearer separation between development and production infrastructure * Predictable deployment behavior per environment * Simpler deployment configuration model * Stronger foundation for environment-aware automation and scaling *** ### Things to know * Every project environment now includes a required **type** * **development** and **production** environments must be unique within a project * Each environment is associated with exactly one deployment policy * Deployment policies are no longer shared across multiple environments * Deployments are now anchored to a single project environment * **Custom** environments remain available for specialized workflows ### Prompt Hyphen Agent URL: https://hyphen.ai/docs/changelog/prompt-the-hyphen-agent Date: March 16, 2026 Tag: added
You can now prompt the **Hyphen Agent** to run operational tasks on demand. Hyphen Agent normally performs tasks automatically based on your organization’s policies and everyday usage. With this release, you can also **manually prompt the Agent** to run these skills whenever you want them. This is useful when you want to immediately clean up resources, review stale feature flags, or prepare your infrastructure for an upcoming event. *** ### Available skills The following skills can be triggered manually: * **Cloud resource cleanup** Identify and remove unused infrastructure created by previous deployments according to configured retention policies. When prompting the Agent, specify an **“archived prior to”** date to determine which deployment resources should be cleaned up. * **Stale feature flag removal** Detect feature flags that have no usage or consistently return the same value and generate cleanup recommendations. * **Schedule Event** Prepare your deployment for upcoming traffic spikes by scaling infrastructure ahead of an event. Events can be scheduled with a specific start and end time or configured as recurring. *** ### Why this matters Agent skills normally run automatically based on organization policies. Prompting the Agent allows you to run these tasks immediately when needed. * Trigger operational tasks on demand * Clean up infrastructure without waiting for scheduled runs * Proactively prepare deployments for upcoming traffic events *** ### Things to know * Skills will continue to run automatically based on organization policies. * Additional Agent skills will be introduced in future updates.
## Other updates * You can filter the Events by `agent-task.create`, `agent-task.update`, `agent-task.delete` to see agent related actions * The list of items in the Agent Inbox changed from paginated to infinite scrolling * Misc bug fixes and performance improvements ### Deployment Previews URL: https://hyphen.ai/docs/changelog/deployment-previews Date: March 10, 2026 Tag: added

We’re introducing **Deployment Previews**, which are ephemeral, fully isolated deployments that let you spin up temporary environments tied to your existing deployment configurations. Whether you’re validating a feature branch or sharing a working demo, previews give you a real, production-like environment without long-term infrastructure overhead. Check out our Deployment Preview Guide to get started right away. ***

### What you can do * Add a **preview** to any existing deployment configuration * Assign a **unique subdomain** for each preview * Access that subdomain inside the running container via an environment variable * Trigger a deployment run for a specific preview * Delete a preview when it’s no longer needed * Automatically clean up infrastructure when a preview is deleted * Create and run previews from both the **CLI and the UI** *** ### How it works Previews inherit the base configuration of your deployment but run as isolated, ephemeral instances. Each preview: * Gets its own subdomain (e.g. `feature-x-subdomain.yourapprul.com`) * Receives that subdomain as an environment variable inside the container * Provisions its own infrastructure * Can be independently deployed, re-deployed, or removed When a preview is deleted, all associated infrastructure is automatically cleaned up by the Hyphen Agent, no manual teardown required. *** ### What this means for you * 🌿 Safe testing without touching staging or production * 🔁 Branch-based workflows with real infrastructure * ⚡ Faster iteration cycles * 🧹 No lingering preview environments * 💰 No paying for infrastructure you forgot to delete *** ### Things to know * Previews are tied to an existing deployment configuration. * At least one app in the deployment must have a hostname and DNS zone configured to create a preview deployment * Each preview must use a unique subdomain within that configuration. * Infrastructure is fully torn down upon deletion. * Previews can be created, deployed, and deleted from both the Hyphen UI and CLI. ### Deployment Policy Filters URL: https://hyphen.ai/docs/changelog/deployment-policy-filters Date: March 9, 2026 Tag: improved
Finding the right deployment policy is now faster and easier. You can now filter your list of **deployment policies** to quickly narrow results based on the project, app that gets deployed, or a search query. This makes it much easier to locate the exact policy you need, especially in organizations with many deployments. *** ### What’s new * Filter deployment policies by **project** * Filter policies by **application** * Use **search** to quickly locate a specific policy * Faster navigation through large policy lists *** ### Why this matters As your organization grows, deployment policies can accumulate across multiple projects and applications. These new filtering options help you quickly find and manage the policies that matter most. *** ### Things to know * Filters can be combined to narrow results further * Search works across policy names for quick discovery * Available anywhere deployment policies are listed ### Enhanced JSON Editing for Feature Flag Return Values URL: https://hyphen.ai/docs/changelog/enhanced-json-editing-for-feature-flag-return-values Date: March 2, 2026 Tag: improved

We’ve upgraded the editing and viewing experience for **JSON-based feature flag return values** in Toggle, making it easier to work with complex objects confidently and efficiently. Whether you're returning structured configuration, multi-variant payloads, or nested objects, the new editor experience is designed to reduce mistakes and improve clarity. ### What’s new * **Syntax highlighting** for improved readability * **Line numbers** for easier debugging and collaboration * **Collapsible sections** for navigating large or deeply nested JSON objects * Improved formatting and validation feedback ### What this means for you Feature flags are increasingly used to return structured data, not just booleans. With enhanced JSON editing: * 🧠 Large payloads are easier to understand * 🔎 Nested structures are easier to navigate * 🛠 Debugging is faster with line references * ⚠️ Syntax errors are easier to spot before saving * 🤝 Teams can collaborate more effectively with consistent formatting ### Things to know * Applies to all JSON-based feature flag return values * Existing flags automatically benefit from the new experience * No configuration changes required This update makes working with advanced feature flags feel less like editing raw text, and more like working in a modern development environment. ### Automated Deployment Resource Cleanup URL: https://hyphen.ai/docs/changelog/automated-deployment-resource-cleanup Date: February 23, 2026 Tag: added Keeping your infrastructure tidy shouldn’t require a weekly calendar reminder. We’re introducing **Automated Deployment Resource Cleanup**, a new Hyphen Agent capability that detects and safely removes unused or stale cloud resources created during deployments. Over time, environments accumulate: * Orphaned containers * Unused load balancers * Detached volumes * Expired preview environments * Outdated build artifacts These resources quietly increase cloud spend, clutter your infrastructure, and add operational risk.
Hyphen now automatically identifies deployment-created resources that are no longer in use and cleans them up according to your organizational, project, or deployment-level retention policies. ### How it works * Hyphen tracks resources created during each deployment. * When a deployment is archived or re-deployed, associated resources are evaluated. * Resources that are no longer referenced by active services are automatically removed. * Cleanup actions are logged and visible in the Agent Inbox for full transparency.
### What this means for you * 💸 Reduced cloud spend from unused infrastructure * 🔒 Lower operational risk from forgotten resources * 🧹 Cleaner deployment environments * ⚡ Zero manual cleanup scripts required ### Things to know * Cleanup only applies to resources provisioned through Hyphen-managed deployments. * Active environments are never impacted. * Retention policies can be configured at the organization, project, or individual deployment level. * The feature is enabled automatically. ### Stale feature flag removal via Agent URL: https://hyphen.ai/docs/changelog/stale-feature-flag-removal-via-agent Date: February 13, 2026 Tag: added Today we’re introducing the first of many Hyphen Agent capabilities: automated stale feature flag detection and removal. Feature flags are powerful — but over time, unused and long-running flags accumulate, adding technical debt and increase release risk. Hyphen Agent analyzes flag activity and identifies flags with no recent usage or unchanged return values over a 90-day period. Once identified, the Agent marks them as stale. If your apps' GitHub repository is connected, Hyphen Agent automatically generates a pull request to safely remove the flag from your codebase — keeping your system clean, maintainable, and production-ready. This is the beginning of a broader vision: autonomous infrastructure and code hygiene that improves continuously in the background. **Things to know** * Only apps with connected Github repos will be analyzed for stale feature flags * Feature flags that have been marked as **perpetual** are excluded from becoming stale * The service is enabled by default — no configuration required * All changes are delivered via pull request for review before merge * When the agent issues a new pull request for stale feature flags, the previous pull request will be closed ### Deployment Container Registry Validation URL: https://hyphen.ai/docs/changelog/2026-02-09-deployment-container-registry-validation Date: February 9, 2026 Tag: improved While creating a deployment policy, we validate that the parent project has a container registry available for your target cloud, or that a new one will be created. Previously deployment policies could be created without a container registry connected to the parent project, which would result in an error when trying to run the deployment. ### Improved payment notifications URL: https://hyphen.ai/docs/changelog/2026-02-02-improved-payment-notifications Date: February 4, 2026 Tag: improved Added clearer messaging for failed payment and subscription cancellation emails. ### 2026-01-26 Python SDK 0.5.0 URL: https://hyphen.ai/docs/changelog/2026-01-26-python-sdk-050 Date: January 27, 2026 Tag: added The **Hyphen Python SDK** is now feature complete and stable, providing full programmatic access to: * **Toggle** – evaluate feature toggles with targeting * **NetInfo** – look up IP geolocation data * **Link** – create branded short URLs and QR codes ## Installation ```bash pip install hyphen ``` Use it in your Python applications to power feature flags, geolocation lookups, and branded link generation. The code is available in our [GitHub repository](https://github.com/Hyphen/python-sdk) and pull requests are welcome! ### Resiliency Updates with Deploy URL: https://hyphen.ai/docs/changelog/2026-01-26-resillency-updates-with-deploy Date: January 27, 2026 Tag: improved Hyphen Deploy now features seamless restarts and enhanced workflow tracking, making deployments more reliable and observable. ### 2026-01-20 - Better walkthrough experience for users on mobile devices. URL: https://hyphen.ai/docs/changelog/2026-01-20-better-walkthrough-experience Date: January 21, 2026 Tag: improved Better walkthrough experience for users on mobile devices. Users are now required to confirm project or app deletion by entering its name.

### 2026-01-20 - React SDK better for Next.js URL: https://hyphen.ai/docs/changelog/2026-01-20-react-sdk-improvements Date: January 21, 2026 Tag: fixed The React SDK no longer depends on the browser SDK, improving SSR compatibility. Added CommonJS support to the React SDK to avoid requiring Next.js package transpilation. https://npmjs.com/package/@hyphen/react-sdk ### 2025-12-15 - Hyphen CLI v0.21.0 URL: https://hyphen.ai/docs/changelog/2025-12-15-hyphen-cli-v0210 Date: December 15, 2025 Tag: fixed Big updates / fixes with our CLI today. * Fix: return non-zero error code when there are errors * Feat: allow custom docker file path when building * Fix: an issue where refresh tokens were not used and thus needing to log in frequently * Fix: pull and push of env with deleted environments * Fix: added documentation to empty env files * Fix: made hx init respect the global project parameter * Feat: handle CI environments better by not using TUI when CI is detected * Fix: switched to better websocket service for more reliability To update to the latest version just do: ``` hx update ```
### 2025-12-06 - Platform Improvements 🎅 URL: https://hyphen.ai/docs/changelog/2025-12-06-platform-improvements Date: December 11, 2025 Tag: improved Every December we focus on bug fixes and improvements to make it easier for our customers to get things done! This week released the following: * [Hyphen CLI (hx)](https://hyphen.ai/hx) - We have been doing some big updates on hx to make it more robust with deploy and how it interacts with the core system via socket updates. * AWS Integration - A massive amount of bug / resiliency fixes are being done this month to make it much more reliable deploying to AWS infrastructure. * Billing - New billing features are coming live in January to bill on the same day every month! ### 2025-11-23 - React SDK v1.0.0 URL: https://hyphen.ai/docs/changelog/2025-11-23-react-sdk-v100 Date: November 27, 2025 Tag: added The react sdk for using [Toggle](https://hyphen.ai/toggle) is now v1.0.0 and available for download: https://www.npmjs.com/package/@hyphen/react-sdk Installation ``` npm install @hyphen/react-sdk ``` Higher-Order Component (HOC) Pattern ```javascript import { withToggleProvider } from '@hyphen/react-sdk'; import App from './App'; export default withToggleProvider({ publicApiKey: 'public_...', applicationId: 'my-app', environment: 'production', defaultContext: { user: { id: 'user-123', email: 'user@example.com' } } })(App); ``` Provider Component Pattern ```javascript import { ToggleProvider } from '@hyphen/react-sdk'; import App from './App'; function Root() { return ( ); } ``` Using the useToggle Hook ```javascript import { useToggle } from '@hyphen/react-sdk'; function MyComponent() { const toggle = useToggle(); // Get boolean feature flag const isNewFeatureEnabled = toggle.getBoolean('new-feature', false); // Get string feature flag const theme = toggle.getString('theme', 'light'); // Get number feature flag const maxItems = toggle.getNumber('max-items', 10); // Get object feature flag const config = toggle.getObject('ui-config', { layout: 'grid' }); return (
{isNewFeatureEnabled && }

Theme: {theme}

Max Items: {maxItems}

); } ```
### 2025-11-24 - Deploy with Better Messaging URL: https://hyphen.ai/docs/changelog/2025-11-24-deploy-with-better-messaging Date: November 27, 2025 Tag: improved [Deploy](https://hyphen.ai/deploy) uses messaging between your cloud provider and [Hx (CLI)](https://hyphen.ai/cli) or [Hyphen App](https://app.hyphen.ai) to update you on how your deployment is going. With this latest update we have added better socket support for that messaging to make it more resilient. :magic_wand: ### 2025-11-24 - Perpetual Feature Flag URL: https://hyphen.ai/docs/changelog/2025-11-24-perpetual-feature-flag Date: November 27, 2025 Tag: added [Toggle](https://hyphen.ai/toggle) now supports perpetual feature flags so you can specify if this feature flag will most likely evaluate the same all the time. This is great for circuit-breaker type flags where only occasionally would you change it. ### 2025-11-25 - Organization Project Collaborator URL: https://hyphen.ai/docs/changelog/2025-11-25-organization-project-collaborator Date: November 27, 2025 Tag: added You now can set a user at the organization level to Project Collaborator giving them the ability to interact with all projects at the organization level. ### 2025-11-17 - Resiliency Updates with Deploy URL: https://hyphen.ai/docs/changelog/2025-11-17-resiliency-updates-with-deploy Date: November 18, 2025 Tag: improved Hyphen Deploy has been updated with two more stabilization features to make building to cloud even more resilient: * We now have built in more socket streaming support to make live updating easier. * Our system now handles when you retry it understands how to re-apply the naming of systems. ### 2025-11-05 - Billing Usage Metrics Now Available! URL: https://hyphen.ai/docs/changelog/2025-11-05-billing-usage-metrics-now-available Date: November 12, 2025 Tag: added You can now access your usage by billing cycle for active users, seats, env, toggle, and more. Simply go to https://app.hyphen.ai and then Settings > Billing. ### 2025-11-02 - AWS Resource Cleanup with Deploy! URL: https://hyphen.ai/docs/changelog/2025-11-02-aws-route-53-support Date: November 6, 2025 Tag: added We now support cleaning up any unused resources in AWS when using Hyphen Deploy! 🚀 Simply go to integrations from [Hyphen AI](https://app.hyphen.ai) and click "Connect to Amazon Web Services". Yes, cleanup is that easy.
### 2025-10-23 - Hyphen Deploy! 🚀 URL: https://hyphen.ai/docs/changelog/2025-10-23-hyphen-deploy Date: October 24, 2025 Tag: added Forget YAML files, Docker configs, Terraform, and Helm charts. With Hyphen Deploy, you define your target SLA, scale, and performance, and Deploy AI generates your cloud infrastructure automatically. https://hyphen.ai/deploy ### 2025-10-07 - Nodejs SDK v2.0.0 URL: https://hyphen.ai/docs/changelog/2025-10-07-nodejs-sdk-v200 Date: October 7, 2025 Tag: improved Our Nodejs SDK has been released with better Toggle capabilities and enhanced caching! Breaking Changes (v2.0) ⚠️ The Toggle API has been simplified in v2.0. Please review the changes below: * ❌ setContext(context) - Use property setter instead: toggle.defaultContext = context * ❌ setPublicApiKey(key) - Use property setter instead: toggle.publicApiKey = key * ❌ getClient() - No longer needed, use the Toggle instance directly * ❌ throwErrors - Errors are now always emitted via events and default values are returned * Hooks removed from convenience methods (getBoolean, getString, etc.) * Hooks now only available via event system (toggle.on('error', ...)) * All toggle methods now return default values on error instead of throwing To learn more about these changes go to: https://www.npmjs.com/package/@hyphen/sdk#toggle---feature-flag-service ### 2025-10-06 - Docker Hub Integration 🐳 URL: https://hyphen.ai/docs/changelog/2025-10-06-docker-hub-integration Date: October 6, 2025 Tag: added Docker Hub integration is now live! With this new integration Hyphen will automatically manage your teams access management! To set this up go to https://app.hyphen.ai and go to integrations. ### 2025-08-08 - Hyphen Browser SDK for Toggle v1 🎉 URL: https://hyphen.ai/docs/changelog/hyphen-browser-sdk-for-toggle-v1 Date: September 16, 2025 Tag: added We now provide a javascript framework for frameworks such as react, svelte, and more. This new sdk is now downloadable from the web. You can read more about it here: https://www.jsdelivr.com/package/npm/@hyphen/browser-sdk Here is an example on how it works: ```typescript import { Toggle } from '@hyphen/browser-sdk'; // Initialize the Toggle client const toggle = new Toggle({ publicApiKey: 'public_your-api-key-here', applicationId: 'your-app-id', environment: 'production', // or 'development' defaultContext: { targetingKey: 'user-123', user: { id: 'user-123', email: 'user@example.com', name: 'John Doe' } } }); const welcomeMessage = await toggle.getString('welcome-message', 'Hello World'); document.getElementById('welcome').textContent = welcomeMessage; ```
### 2025-08-18 - Firewall, Logout, Azure, and More! URL: https://hyphen.ai/docs/changelog/2025-08-18-firewall-logout-azure-and-more Date: August 19, 2025 Tag: fixed We have released a number of fixes today: * We saw issues with ipv6 and ipv4 compatibility on firewall rules. This has been updated to make it easier * Logout now works much better across all of our systems. * Update to Azure to make it more stable when working with it. * We also added some performance improvements on the ENV homepage in [Hyphen App](https://app.hyphen.ai). ### 2025-08-18 - Segments Documentation! URL: https://hyphen.ai/docs/changelog/2025-08-18-segments-documentation Date: August 19, 2025 Tag: added New segments documentation is live here: [Segments](/docs/feature-flags/segments) A segment is a reusable set of targeting rules. Segments are useful because they let you define a common audience once and then reuse that audience across many feature flags without duplicating logic. For example, “beta testers,” “premium customers,” or “users in Mexico". A segment is scoped to the project it is created in. Segment rules are based on context properties and can be used across the environments within a project. ### 2025-07-30 - ENV Access via Projects with Filtering URL: https://hyphen.ai/docs/changelog/2025-07-30-env-access-via-projects-with-filtering Date: July 30, 2025 Tag: added View ENV access events for a project environment, filtering by project or event type view ENV access events for default secrets, filtering by project or event type finally, navigate to these views by clicking the project environment or "default secrets" links on the project overview view ### 2025-07-30 - Horizon now with ENV! URL: https://hyphen.ai/docs/changelog/2025-07-30-horizon-now-with-env Date: July 30, 2025 Tag: added We now support Toggle and ENV read requests to build resiliency and performance for your production environments when using the Horizon self-hosted option. In addition, we have drastically improved the caching capabilities for horizon. :boom: ### 2025-07-30 - Nodejs SDK with QR Codes! URL: https://hyphen.ai/docs/changelog/2025-07-30-nodejs-sdk-with-qr-codes Date: July 30, 2025 Tag: improved You can create a QR code via the SDK from a short code easily: ```javascript import { Link } from '@hyphen/sdk'; const link = new Link({ organizationId: 'your_organization_id', apiKey: 'your_api_key', }); const code = 'code_1234567890'; // It is the code identifier for the short code you want to create a QR code for const response = await link.createQrCode(code); console.log('Create QR Code Response:', response); ``` ### 2025-07-21 - AWS Integration Even Easier! URL: https://hyphen.ai/docs/changelog/2025-07-21-aws-integration-even-easier Date: July 22, 2025 Tag: improved We have now reduced the steps down dramatically so that you can get your connection to AWS setup in minutes! ### 2025-07-21 - Net Info UX with Infinite Scrolling URL: https://hyphen.ai/docs/changelog/2025-07-21-net-info-ux-with-infinite-scrolling Date: July 22, 2025 Tag: improved In the Hyphen App, you can now look at your events on net.info and keep on scrolling. Just making it a bit easier for all of us... ### 2025-07-15 - Hyphen App Updates! URL: https://hyphen.ai/docs/changelog/2025-07-15-env-usage-in-dashboard Date: July 15, 2025 Tag: improved There are some amazing updates to make it easier to use: * Now in the dashboard you can see your ENV access locations :tada: * There is a `+` button at the top that allow you to create a project, feature flag, segment, short link, team, and even invite a new team member! :boom: * Finally, the dashboard side navigation collapses to make it easier to view! ### 2025-07-09 - Nodejs SDK with Link Support! URL: https://hyphen.ai/docs/changelog/2025-07-09-nodejs-sdk-with-link-support Date: July 9, 2025 Tag: added Our Node.js SDK [@hyphen/sdk](https://npmjs.com/package/@hyphen/sdk) has been updated with the ability to generate short codes via [Link](https://hyphen.ai/link) . Here is how easy it is: ```javascript import { Hyphen } from '@hyphen/sdk'; const hyphen = new Hyphen({ apiKey: 'your_api_key', }); const longUrl = 'https://hyphen.ai'; const domain = 'test.h4n.link'; const options = { tags: ['sdk-test', 'unit-test'], }; const response = await hyphen.link.createShortCode(longUrl, domain, options); console.log('Short Code Response:', response); ``` ### 2025-07-09 - See where your secrets are being accessed 🌏 URL: https://hyphen.ai/docs/changelog/2025-07-09-see-where-your-secrets-are-being-accessed Date: July 9, 2025 Tag: added Now you can log into [Hyphen](https://app.hyphen.ai) and see where your secrets are being accessed! ### 2025-07-09 - Supporting Domain Restriction in Google Cloud URL: https://hyphen.ai/docs/changelog/2025-07-09-supporting-domain-restriction-in-google-cloud Date: July 9, 2025 Tag: improved We have been working hard to make Google Cloud integration secure and easy to use. With this latest update our integration will set the Domain Restriction Policy to enable the users we grant access to. 🫰 ### 2025-06-30 - Google Workspace Integration Updated URL: https://hyphen.ai/docs/changelog/2025-06-30-google-workspace-integration-updated Date: June 30, 2025 Tag: improved We added in some more error handling and also the access permissions you need to complete the task. ### 2025-06-30 - Horizon Self Hosting 🌏 URL: https://hyphen.ai/docs/changelog/2025-06-30-horizon-self-hosting Date: June 30, 2025 Tag: added Horizon is what we run at the edge of our global network to enable high availability and uptime for accessing [Toggle](https://hyphen.ai/toggle) evaluations at scale. Now with self hosting you can build more resiliency and performance by adding Horizon to your local clusters. That means that your local horizon instances are your primary lookup for Toggles and we become the secondary layer. You can read more about it here: [Horizon](/docs/introduction/horizon) ### 2025-06-30 - New Events View! URL: https://hyphen.ai/docs/changelog/2025-06-30-new-events-view Date: June 30, 2025 Tag: improved The new events view shows you where the event took place and also the details in an easy to read view :boom: ### 2025-06-30 - Bulk Geo IP Lookup via Node.js SDK URL: https://hyphen.ai/docs/changelog/2025-06-30-nodejs-sdk-180-released Date: June 30, 2025 Tag: added [@hyphen/sdk](https://www.npmjs.com/package/@hyphen/sdk) has been released (v1.8.0) with the ability to do bulk geo ip address lookups. Here is an example: ```javascript import { NetInfo } from '@hyphen/sdk'; const netInfo = new NetInfo({ apiKey: 'your_api_key', }); const ips = ['8.8.8.8', '1.1.1.1']; const ipInfos = await netInfo.getIpInfos(ips); console.log('IP Infos:', ipInfos); ``` ### 2025-06-23 - Faster Toggle Updates on Edge URL: https://hyphen.ai/docs/changelog/2025-06-23-faster-toggle-updates-on-edge Date: June 23, 2025 Tag: improved We've enhanced our edge nodes to respond more intelligently to Toggle configuration updates. Previously, we cached configurations at the edge for performance. While that remains true, our edge nodes are now instantly notified when a toggle changes—ensuring they update only what's needed in near real time. 🚀 ### 2025-06-23 - Google One-Click Integration URL: https://hyphen.ai/docs/changelog/google-one-click-integration Date: June 23, 2025 Tag: improved You can now do one click integration with Google Workspace and Google Cloud! ### 2025-06-23 - Node SDK with Load Environments and Net Info URL: https://hyphen.ai/docs/changelog/node-sdk-with-load-environments-and-net-info Date: June 23, 2025 Tag: added The @hyphen/sdk has been extended with a function to load your environment variables easily with `loadEnv()`. Here is an example of how to use it: ```javascript import { loadEnv } from '@hyphen/sdk'; //load your default environment variables and envrionment variables loadEnv(); ``` You can also set the environment, env path, and to load `*.local` files. This will load your environment variables in the following order to do overrides: ``` .env -> .env.local -> .env. -> .env..local ``` In addition, We have added `NetInfo` which will be used for geo ip address information. Here is how to use it: ```javascript import { NetInfo } from '@hyphen/sdk'; const netInfo = new NetInfo({ apiKey: 'your_api_key', }); const ipInfo = await netInfo.getIpInfo('8.8.8.8'); console.log('IP Info:', ipInfo); ``` ### 2025-06-23 - Toggle Stats on the Dashboard URL: https://hyphen.ai/docs/changelog/toggle-stats-on-the-dashboard Date: June 23, 2025 Tag: improved Now the dashboard contains your [Toggle](https://hyphen.ai/toggle) usage on the home page if you are using it! ### 2025-06-03 - Microsoft Office 365 - One Click Integration URL: https://hyphen.ai/docs/changelog/microsoft-office-365-one-click-integration Date: June 16, 2025 Tag: added You now can easily integrate your Microsoft Office 365 with Hyphen via one click. The enables you to have Hyphen create groups and manage distribution lists for teams. :magic_wand: ### 2025-06-03 - Integrated Guides on Link, Feature Flags, and more! URL: https://hyphen.ai/docs/changelog/2025-06-03-integrated-guides-on-link-feature-flags-and-more Date: June 4, 2025 Tag: improved Integrated into [Hyphen App](https://app.hyphen.ai) you can now easily walk through specific steps for creating a short link, feature flags, and automating access to services. :tada: ### 2025-06-03 - Hx release with updated QR code fixes URL: https://hyphen.ai/docs/changelog/2025-06-03-hx-release-with-updated-qr-code-fixes Date: June 3, 2025 Tag: fixed We found some issues with QR Code generation via [Hx](https://hyphen.ai/hx) and now that is fixed. If you already have it installed just run: ```shell hx update ``` It's as easy as that! ### 2025-06-03 - New Azure One Click Integration URL: https://hyphen.ai/docs/changelog/2025-06-03-new-azure-one-click-integration Date: June 3, 2025 Tag: improved We made it take minutes to add in Azure to Hyphen. Just click the "Connect Microsoft Azure" and you're up and running in minutes! ### 2025-03-24 - Access Tab for Short Links URL: https://hyphen.ai/docs/changelog/2025-03-24-access-tab-for-short-links Date: March 25, 2025 Tag: added Now you can do access management on your short links! ### 2025-03-24 - New Project View! URL: https://hyphen.ai/docs/changelog/2025-03-24-new-project-view Date: March 25, 2025 Tag: improved We have updated our project view in the dashboard so it now shows the toggles, segments, and access under your project. :boom: ### 2025-03-17 - Improved Integration Connections UX URL: https://hyphen.ai/docs/changelog/2025-03-17-improved-integration-connections-ux Date: March 17, 2025 Tag: improved Integration connections for projects, apps, teams, project environments has been moved to their respective overview pages. You'll see a list of available integration connection types (e.g. permission group, channel, code repo) that have been set up for the organization, or a prompt to create a new integration if one isn't available for the connection type you're trying to make ### 2025-03-10 - Teams with Connections and Project Access URL: https://hyphen.ai/docs/changelog/2025-03-10-teams-with-connections-and-project-access Date: March 11, 2025 Tag: improved We have now made it easier to setup your integrations to things such as Github, Azure, AWS, Google, and more directly on the team page! In addition to that you can setup the teams access to their projects and view which ones they now have access too. # Toggle Updates We have also had some updates to Toggle. :tada: * fix: toggle services to support both environment alternateId and name * fix: toggle now supports daily telemetry ### 2025-01-20 - Introducing Feature Flags URL: https://hyphen.ai/docs/changelog/2025-01-20-introducing-feature-flags Date: January 24, 2025 Tag: added We are pleased to announce the general availability of our Feature Flag service named [Toggle](https://hyphen.ai/toggle)! Toggle is a developer focused feature flag service with enterprise grade features at a cost that makes sense. Here are some of the features: * Simple true-false scenarios to more complex use cases requiring multi-variate flags such as strings, numbers, and JSON objects * Built on the [Open Feature](https://openfeature.dev) specification so little to no lock in * Lightning fast Evaluations :cloud_with_lightning: * Enterprise Grade SLA 99.995% Uptime and Scaled Globally * Install and use our Edge service (Horizon) locally for more redundancy and performance * Logging and statistics are stored up to 12 months by default and you can add in a webhook to your own storage to keep it even longer. * Only pay for the usage against our API (and it is really cost effective) * SDK's for Nodejs, Javascript (client side), .NET, Java, Python, and Golang! To learn more go to [https://hyphen.ai/toggle](https://hyphen.ai/toggle) ### 2024-11-25 - Bot, Dashboard, Public API Keys URL: https://hyphen.ai/docs/changelog/2024-11-25-bot-dashboard-public-api-keys Date: December 4, 2024 Tag: added Our Hyphen bot :robot: used in slack has gotten a big upgrade and now is much faster than before with responding to requests. In addition, we now are more accurate as we are using a larger training set. :tada: You can try this out by adding it to your your slack and asking it: > @hyphen can you create team your\_team\_name ## More Services Coming Soon! In addition, we have been laying the ground work for all of our connected integrations. These are the services that you use everyday such as Amazon Web Services, Google Cloud, Azure, Office 365, etc. We will be building out these services and plan to have more released soon! ## New Dashboard Navigation A brand new dashboard navigation that makes it much easier to get to what you are working on. Check it out! ## Public API Keys Public API Keys are keys that can be used for your front end applications for things such as feature flags which the foundation of [Toggle](https://hyphen.ai) which is coming soon! :crossed_fingers: ### 2024-11-04 - QR Code Styling URL: https://hyphen.ai/docs/changelog/2024-11-04-qr-code-styling Date: November 5, 2024 Tag: added We are pleased to announce availability for QR codes via [Hyphen Link](https://hyphen.ai/link) that is easy to add your logo and styling. Here is an easy example of how to do this: Go to your [Hyphen Dashboard](https://app.hyphen.ai) and then create a short code via Link. After creating it you will be able to create a QR Code for this short link. From there you can easily customize the qr code with title, size, logo, foreground and background color! :tada: If you want to do this via API you can do the following: ``` POST /api/organizations/{organizationId}/link/codes/{codeId}/qrs/ { "title": "My QR Code", "options": { "size": 300, "logo": "https://hyphen.ai/logo.svg", "color": "#000000", "backgroundColor": "#FFFFFF" } } ``` Go to the [Custom QR Code](/docs/url-shortening/create-a-qr-code) for more on using Link! :beers: ### 2024-10-21 - Secrets Management URL: https://hyphen.ai/docs/changelog/secrets-management-initial-release Date: October 21, 2024 Tag: added We are pleased to announce our secrets management system called ENV :tada:. Based on what developers are used, easy for teams to manage, and secure by default. Here are some of the amazing features that are built: * Your data is stored fully encrypted, so we never see or generate the encryption keys. These keys are created locally on your machine with OpenSSL’s AES-256-CBC symmetric encryption cipher to keep your data fully encrypted at all times. * Use the `.env` environment that your developers use today and not something new when moving to production. * ENV Integrates with popular cloud providers, CI/CD tools and developer frameworks so that you can automatically inject secrets during the build and deployment process * Update encryption keys without interrupting the functionality of your apps, ensuring both security and operational continuity :closed_lock_with_key: * Manage access to your secrets by, user, environment, and IP address, ensuring the right people and services have the right access * View past versions of your secrets for any environment, making it simple to revert when needed * An intuitive CLI that makes managing your app’s secrets and configurations fast and effortless. * Every access attempt, success or fail, is logged in detail, providing full visibility into who is accessing your secrets and from where :heart: It is just built into our platform and based on the same team and member system as Smart Access! :boom: Here are some guides to get you started: * [Quickstart](doc:env-secrets-management) - start here as it helps you download the CLI (`hx`)and get up and running in minutes * [Pulling Secrets](doc:pulling-secrets-for-an-existing-app) - easily pull and push your files * [Version Control](doc:version-control) - comprehensive version control * [Rotating an Encryption Key](doc:rotating-an-encryption-key) - enterprise feature that allows you to keep multiple keys going while you do change management. When you're ready to deploy :rocket: here are some quick guides: [Using ENV with Docker](doc:using-env-with-docker), [Configuring Env For Docker](doc:configuring-env-for-docker), and [Deploying with ENV](doc:deploying-with-env) ### 2024-09-20 - Smart Access, Website, Status, and Guides URL: https://hyphen.ai/docs/changelog/welcome-to-hyphenai Date: September 9, 2024 Tag: added Smart Access is now in Beta plus a new website, status page, guides, help via chat / email, and more. Our initial release had the following features / services: ## New Website We have a new website and services built in to make your development experience way better. The website now has [pricing](https://hyphen.ai/pricing) and a couple of examples of what you might expect if you are a startup, small, mid-size, or enterprise business. ## Status and Help You can now get an updated [status](http://status.hyphen.ai) and help via [chat](https://hyphen.ai) or email [help@hyphen.ai](mailto:help@hyphen.ai) ## Guides and API Documentation We have built out a whole new section of guides which you can see by going to [docs.hyphen.ai](/docs) which will get your started with using [Hyphen AI](https://hyphen.ai) :tada:. In addition all of our API is now documented and you can see it by going to [API Reference](/docs/api) ! > 📘 Quick Tip: If you logon when using the API Reference it will enable you to try out the API directly from the web! :magic_wand: ## Smart Access (BETA) One of our core features is now live and ready to be used. Smart access enables you and your team to easily manage the access to specific resources such as cloud, repositories, and specific slack channels all by talking with the Hyphen bot in slack! To get started read [Getting Started](ref:getting-started) guide! All you have to do is create a team in slack and then add users to it just by saying something like this: > @hyphen please create a team called "mobile engineering" and add myself, @sally, and @paul Here are a couple of the things it can do with the supported integrations: * **Slack** - By integrating Hyphen with slack and installing our [Hyphen Bot 🤖](doc:using-hyphen-bot) when you create a team it will automatically create a slack channel for that team and as you add or remove users keep it in sync to make sure the team is in the channel. * **Google Workspace** - Once [Google Workspace](doc:google-workspace-integration) is added as an integration it will create team distribution lists and keep it in sync as you add or remove team members. No more creating tickets to do this work. It just does it like pulling a rabbit from your hat. :tophat: * **Github** - Integrate [GitHub](doc:github-integration) and make your life so much easier as it creates the teams, keeps that team in sync, and in the future will even map it to the repos that the team is in charge of. * **Cloud Integration** - With [Google Cloud Integration](doc:google-cloud-integration), [AWS Integration](doc:aws-integration), or [Azure Integration](doc:azure-integration-setup-guide) it will create a group for your team and keep it in sync. In the future it will also setup the security around your app and project for the team. Interested in trying this out go to [Hyphen AI](https://hyphen.ai) and sign up for our early access! :boom: ## Company - **Name**: Hyphen AI - **Headquarters**: 1201 3rd Avenue, STE 2200, Seattle, WA 98101 - **Website**: https://hyphen.ai - **Documentation**: https://hyphen.ai/docs - [Terms of Service](https://hyphen.ai/terms-of-service) - [Privacy Policy](https://hyphen.ai/privacy-policy) ## Social - **GitHub**: https://github.com/hyphen - **Twitter/X**: https://x.com/hyphen - **LinkedIn**: https://www.linkedin.com/company/hyphen-ai