# 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. ### [Managed Kubernetes | Make Sense of Your Kubernetes Clusters](https://hyphen.ai/managed-kubernetes) Connect the Kubernetes clusters you already run and instantly understand what’s deployed, what’s exposed, what’s failing, and what should be cleaned up, without changing your deployment workflow. ### [Managed DevOps Services | CI/CD, K8s & Cloud](https://hyphen.ai/managed-ops) Senior DevOps engineers embedded in your team to run CI/CD, Kubernetes, and AWS/GCP — from $5,000/mo, 90-day money-back guarantee, runs in your cloud. ### [Hyphen MCP Server | Manage Hyphen from your AI tools](https://hyphen.ai/mcp) Connect Claude, Cursor, VS Code, or any MCP client to your Hyphen organization — deploy apps, manage feature flags, investigate incidents, and operate automations from your AI tools, with the same permissions you have in the app. ### [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 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 quick start guide to setting up your Hyphen AI account, installing the Slack bot, and configuring essential integrations for your organization. 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! 🪄 ### Dashboard Overview URL: https://hyphen.ai/docs/introduction/dashboard/ Description: A comprehensive overview of the Hyphen organization dashboard, detailing its various cards for tracking deployments, activity, Kubernetes, feature flags, ENV access, net.info usage, and project resources. The organization dashboard brings recent activity, operational health, and product usage into one view. Open an organization in the Hyphen App to see the dashboard. The cards you see depend on the products your organization uses and the data Hyphen can access. A card may be hidden when there is no relevant data. ## Deployments **Environments Deployed** shows deployment runs from the last 30 days. The chart groups runs by day and deployment. Select a bar or a run to open the related deployment details. ## Organization Activity **In the last 5 days** summarizes recent organization events by product or resource type. Expand a row to review the individual events behind its count. ## Kubernetes Fleet The **Kubernetes fleet** card appears when your organization has registered clusters. It summarizes: - Connected and healthy clusters. - Ready pods compared with total pods. - Container issues and warnings found in the latest inventory. - Each cluster's provider, latest inventory time, pod readiness, and health. Select the card title to open Kubernetes, or select a cluster to inspect its latest inventory. If no clusters are connected, the card links to the cluster registration flow. For details about the health summary, see [Kubernetes Overview](/docs/kubernetes/overview). ## Toggle Usage The **Toggle** card shows recent feature flag usage over the last 30 days. It highlights up to five flags and links each one to its flag details. Organization-level evaluation and usage charts appear below the list when telemetry is available. The card links to the Toggle quick start when the organization has no flags or no recent usage. Disabling usage telemetry in an SDK reduces the usage information available in Hyphen. See [Toggle Concepts](/docs/feature-flags/toggle-concepts#telemetry). ## ENV Access Locations **ENV Access Locations** maps recent ENV access activity when events contain location data. It also calls out denied ENV access requests from the last 30 days. The card is hidden when there are no mappable events or access denials. ## net.info Usage The **net.info** card shows total requests and a daily request trend for the last 30 days. Select it to open the net.info request view. The card is hidden when the organization has no usage in the period. See the [net.info Quick Start](/docs/net-info/netinfo-quickstart) to begin making requests. ## Projects and Help The dashboard includes the organization's projects and links to API documentation, guides, CLI documentation, and SDK documentation. Members who still have onboarding work may also see a dismissible walkthrough card. ### Organizations URL: https://hyphen.ai/docs/introduction/organizations/ Description: Learn about Hyphen Organizations, collaborative workspaces for managing multiple projects, billing, and user permissions. 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: Understand how to organize and manage applications, environments, and secrets within Hyphen Projects using 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: Guide to adding a custom domain to your Hyphen organization for branded short links, including DNS configuration, redirect settings, 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), including detailed explanations of all available commands and their usage. 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: Guide on how to self-host and deploy Horizon for fast, secure access to feature flags and secrets. 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); ``` ### Agent Overview URL: https://hyphen.ai/docs/agent/agent-overview/ Description: An overview of Hyphen Agent, its capabilities, and how to use it for operations and management tasks within your Hyphen organization. Hyphen Agent is an operations agent for your Hyphen organization. It helps answer questions, investigate activity, analyze logs, recommend optimization work, and prepare routine cleanup changes for review. Hyphen Agent is not a coding assistant. Coding assistants help create application code. Hyphen Agent helps operate the cloud, deployment, Kubernetes, feature flag, link, project, and integration footprint around that code. ## Where You Use Agent You can work with Agent from the Hyphen App and from Slack when the Slack integration is installed. - **Agent inbox** - Review recent Agent runs and chat sessions from the right-side Agent panel in the Hyphen App. - **Chats** - Ask questions, attach resource context, approve actions, and continue previous conversations. - **Tasks and runs** - Review scheduled or triggered Agent work, including status, findings, steps, pull requests, and approval requests. - **Slack** - DM the Hyphen bot or mention it in a channel thread to use the same organization chat functionality from Slack. ## Core Concepts | Concept | Description | | ------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | Chat session | A conversation with Agent. Sessions can answer questions directly or create tasks when work needs to run. | | Agent task | A unit of work Agent creates or runs, such as log analysis, optimization, resource cleanup, or GitHub issue automation. | | Run | An execution of an Agent task. Runs show progress, findings, action requests, linked resources, and output. | | Reference | A linked Hyphen resource, such as a project, app, environment, deployment run, Kubernetes cluster, feature flag, team, member, link, domain, or Agent task. | | Input request | A structured prompt for confirmation, selection, free text, or an option with added text. | | Member memory | Durable preferences or facts that Agent can remember when explicitly asked. Do not store secrets in memory. | ## Scheduled Tasks Policy-driven Agent tasks run automatically on schedules set by organization policy, project-level policy, or project environment-level policy, depending on the task. You can also ask Agent to run supported tasks manually when you have permission to access the related resources. ## Context-Aware Answers Agent uses attached context first. If you start a chat from a project, app, or environment page, Hyphen can attach that context automatically so Agent can scope the answer without requiring you to repeat where you are. Agent also renders supported resource references as links back into Hyphen, so answers can point directly to the project, app, environment, deployment, preview deployment, feature flag, segment, link, domain, team, member, or Agent task involved. ## Action Model Agent can answer many questions directly. When a request would create, delete, change, or propose work against a resource, Agent uses structured input requests for approval or missing information. Code and configuration changes that belong in a repository are proposed through pull requests. Resource changes in Hyphen require the same permissions as the equivalent action in the app. ### Agent Capabilities URL: https://hyphen.ai/docs/agent/capabilities/ Description: Explore the comprehensive capabilities of Hyphen Agent, an AI assistant that blends conversational interactions with powerful task automation for log analysis, Kubernetes management, deployment optimization, and more. Hyphen Agent combines conversational answers with task-based operations work. Availability can depend on your organization permissions, connected integrations, and the resources Agent can access. ## Task Guides For deeper task-specific guidance, see: ### Deployments - [Log Analysis](/docs/agent/log-analysis) - [Deployment Optimizer](/docs/agent/optimizer) - [Stale Feature Flag Cleanup](/docs/agent/stale-feature-flag-cleanup) - [GitHub Pull Request Automation](/docs/agent/github-pull-request-automation) ### Kubernetes - [Kubernetes Optimizer](/docs/agent/kubernetes-optimizer) - [Kubernetes Resource Cleanup](/docs/agent/kubernetes-resource-cleanup) ## Activity Answers Agent can answer questions about organization activity from recorded Hyphen events. It supports listing, counting, finding, and summarizing activity across projects, apps, environments, deployments, preview deployments, teams, members, feature flags, segments, links, domains, ENV, and Agent tasks. Example questions: - "What happened in this project today?" - "How many deployments failed this week?" - "Who created this environment?" - "What has Jordan changed recently?" - "Summarize the last 24 hours of production events." If a resource name matches multiple resources, Agent asks for clarification instead of guessing. ## Chat Sessions and Slack Agent chat sessions support ongoing organization conversations in the Hyphen App. When Slack is connected, you can also DM the Hyphen bot or mention it in a channel thread. Slack chat supports thread continuity, Hyphen resource links, Slack mentions, and input requests for confirmations or follow-up questions. ## Member Memory Agent can remember durable member preferences when you explicitly ask it to remember, update, forget, or clear something. Memory is useful for preferences such as answer format, common environment names, or recurring context. Member memory is not a secret store. Do not save credentials, tokens, private keys, or sensitive personal data in memory. ## [Log Analysis](/docs/agent/log-analysis) Agent can analyze deployment logs and surface findings by severity. By default, Hyphen Agent analyzes available cloud provider container logs. If the app is connected to New Relic APM, Agent can use APM data instead. Log analysis results can include: - Log coverage metrics. - Findings grouped by category and severity. - GitHub issue actions, such as created, commented, or skipped. - Repository and pull request context when a fix is proposed. ## [Deployment Optimizer](/docs/agent/optimizer) Agent can investigate project environment deployment and runtime signals, run optimizer simulations, and recommend changes such as right-sizing, consolidation, or shutting down underused resources. Optimizer recommendations are intended to preserve declared availability expectations. When an optimizer run requires approval, Hyphen presents an input request before Agent proceeds. ## [Stale Feature Flag Cleanup](/docs/agent/stale-feature-flag-cleanup) Agent can identify Toggle flags with no recent usage or unchanged return values over a 90-day window. When the relevant app has a connected GitHub repository, Agent can open a cleanup pull request to remove stale flag references from code. Perpetual feature flags are excluded from stale flag cleanup. ## [GitHub Pull Request Automation](/docs/agent/github-pull-request-automation) When GitHub is connected, Agent can connect findings to GitHub issues and pull requests. For log analysis, Agent can create a new issue, comment on a matching existing issue, or open a pull request with a proposed fix. Agent-created code changes are reviewable. Agent does not merge pull requests automatically as part of this workflow. ## [Kubernetes Optimizer](/docs/agent/kubernetes-optimizer) Agent can analyze a workload in a registered Kubernetes cluster and recommend findings or replica guidance from inventory evidence such as current replicas, ready replicas, related pods, services, warning events, sibling workloads, planned events, and autoscaling context. Kubernetes optimizer recommendations are review-first. Scale recommendations require approval before anything changes, and Agent skips manual replica guidance when matching HorizontalPodAutoscaler evidence is detected. Kubernetes optimizer runs can be scheduled per workload with a policy, or run on demand from chat or the cluster diagram. ## [Kubernetes Resource Cleanup](/docs/agent/kubernetes-resource-cleanup) Agent can scan registered Kubernetes clusters for stale, dead, or unused resources and present cleanup candidates for review. Kubernetes resource cleanup runs inspect cluster inventory, apply the configured stale threshold and ignore lists, and create approval requests before deleting any resource. Kubernetes cleanup policies can be managed at the organization level, and individual clusters can override the organization policy when a cluster needs its own schedule, threshold, or ignore list. ## Deployment Controls Agent can inspect [project environment deployment settings](/docs/deploy/deploy-quickstart#configure-your-project-environment-deployment-settings) and answer deployment readiness questions from chat. You can ask what is configured for an environment, which apps and cloud targets are included, whether the deployment is ready to run, or what the latest non-preview deployment run looked like. Agent can also start a configured deployment or [preview deployment](/docs/deploy/deployment-previews). Before creating a [deployment run](/docs/deploy/deployment-run-methods), Agent checks readiness and presents a [confirmation request](/docs/agent/safety-and-approvals) with the target project, environment, preview context, and selected builds. If builds are not specified, Agent uses the latest app build for non-preview deployments and the latest preview build for preview deployments. Follow-up deployment requests preserve the prior deployment target, including preview deployment context, so requests like "deploy again" can reuse the last confirmed project and environment. ## Deployment Resource Cleanup Agent can detect unused or stale deployment resources created or tracked by Hyphen, including orphaned containers and expired preview deployment resources. Deployment resource cleanup work is presented through Agent runs so you can review status, output, and any required approvals. ## Project, Link, and QR Code Tools From chat, Agent can help with project, short link, and QR code operations. Supported project actions include listing projects and creating a project after collecting required details and confirmation. Supported link and QR code actions include reading short links, creating short links, deleting short links, and helping create, retrieve, or delete QR codes for existing short links. ## Scheduled and Recurring Work Agent tasks can be scheduled or recurring. Task and run detail views show timing, status, related resources, conversation history, and execution output. ## Related Deployment Context Hyphen also surfaces deployment settings drift on project environment views when current deployment settings differ from the latest run snapshot. Agent optimizer work can use deployment and runtime context, but the deployment drift alert itself is documented as a Hyphen Deploy surface rather than an Agent task. ### Setup and Requirements URL: https://hyphen.ai/docs/agent/setup-and-requirements/ Description: A comprehensive guide to setting up the Hyphen Agent, detailing the requirements and configurations needed for various capabilities, including integrations with New Relic, Kubernetes, GitHub, and Slack. Agent is available from the Hyphen App for your organization. Some capabilities require connected integrations or specific Hyphen permissions. ## Requirements by Capability | Capability | Requirements | | --- | --- | | Activity answers | Recorded Hyphen events and permission to view the related resources. | | Chat sessions | Access to the Hyphen organization. | | Slack chat | Installed Slack integration and a Slack user/workspace that Hyphen can resolve to a member and organization. | | Member memory | A signed-in Hyphen member. Memory changes must be requested explicitly. | | Log analysis | Deployment logs from the connected cloud provider, or New Relic APM when configured. | | New Relic-backed log analysis | Connected New Relic integration and an app configuration that maps to the Hyphen environment. | | GitHub issue automation | Connected GitHub integration and repository access. | | Pull requests from Agent findings | Connected GitHub repository for the affected app. | | Stale feature flag cleanup | Hyphen Toggle usage data and a connected GitHub repository for the app. | | Deployment optimizer | Deployment/runtime data Agent can inspect and permission to view the related resources. | | Kubernetes optimizer | A registered Kubernetes cluster with Horizon reporting inventory, a selected workload namespace, kind, and name, permission to view the cluster and run Agent tasks, and permission to approve scale changes when required. A connected New Relic or Google Cloud observability source is optional and adds runtime metrics and logs. | | Resource cleanup | Deployment resources created or tracked by Hyphen and permission to approve cleanup when required. | | Project tools | Organization permissions to list or create projects. | | Short link and QR code tools | Link domain configuration and permission to manage links or QR codes. | ## New Relic Configuration For New Relic-backed log analysis, connect New Relic from the Integrations area first. Hyphen supports two APM connection patterns: - **Shared by environment attribute** - One New Relic APM app uses an environment attribute filter to separate environments. - **Per environment** - Each Hyphen project environment maps to a distinct New Relic APM app name. If New Relic is not connected for an app, Agent uses available cloud provider container logs instead. ## Kubernetes Observability Configuration Kubernetes Optimizer can combine cluster inventory with metrics and logs from New Relic or Google Cloud. Configure the connection from the registered cluster's **Settings** tab. - New Relic connections require the cluster name used by the New Relic Kubernetes integration. - Google Cloud connections require the full GKE resource name and Logs Viewer, Monitoring Viewer, and Kubernetes Engine Cluster Viewer access for the Hyphen service account. Observability is optional. If telemetry is missing, incomplete, or temporarily unavailable, Agent reports the capability gap and continues with the evidence it can safely use. See [Kubernetes Observability](/docs/kubernetes/observability). ## GitHub Configuration GitHub is required for repository-backed automation, including stale feature flag cleanup, issue automation, and pull requests from log analysis findings. Agent uses connected repository context for reviewable changes. If a repository is not connected, Agent can still surface findings where supported, but it cannot open repository pull requests. ## Slack Configuration Install the Slack integration before using Agent from Slack. You can DM the Hyphen bot or mention it in a channel thread. If Hyphen cannot resolve the Slack workspace or user to a Hyphen organization member, the bot returns a blocker message instead of starting a chat. ## Permissions Agent follows Hyphen organization permissions. A member must have permission to view, create, delete, or change the resource involved in an Agent action. When an action requires approval or more information, Agent asks through a structured input request instead of relying on freeform text. ### Safety and Approvals URL: https://hyphen.ai/docs/agent/safety-and-approvals/ Description: Learn how Agent ensures safety and requires approvals for operations through structured input requests, reviewable code changes, resource clarification, permissions management, memory safety, and capability-specific guardrails. Agent is designed to make operations work reviewable. Actions that create, delete, change, or propose changes use confirmations, permissions, and audit-friendly output. ## Structured Input Requests Agent uses structured input requests when it needs approval or missing information. Depending on the request, you may see: - A yes/no confirmation. - A free-text response. - A choice from available options. - A choice with additional text. In Slack, input requests render as buttons or modals. Slack input requests are scoped to the requester who started the Agent turn. ## Reviewable Code Changes When Agent changes code or repository configuration, it proposes the change through a pull request. The pull request can include the context that led to the change, such as a log analysis finding or stale feature flag detection. Review, test, and merge pull requests using your normal repository workflow. ## Resource Clarification If a prompt names a resource that matches multiple projects, apps, environments, links, feature flags, or other resources, Agent asks you to choose the intended resource. Agent uses attached chat context first. Remove context badges before sending a message if you do not want Agent to use the current project, app, or environment as the scope. ## Permissions and Access Agent follows the same access rules as the Hyphen App. If you cannot view or mutate a resource directly, Agent should not perform that action for you. Some capabilities also depend on external integration permissions, such as GitHub repository access or New Relic data access. ## Memory Safety Agent only updates member memory when you explicitly ask it to remember, update, forget, or clear a durable preference or fact. Do not store secrets in member memory. Keep credentials, tokens, private keys, and other sensitive values in the appropriate secret management system. ## Capability-Specific Guardrails - **Stale feature flag cleanup** excludes perpetual feature flags. - **Repository changes** are proposed through pull requests. - **Mutating project, link, QR code, and cleanup actions** require confirmation. - **Log analysis issue automation** is additive when matching existing issues; it comments rather than rewriting existing issue bodies. - **Slack actions** require a resolved Hyphen member and organization. ### Log Analysis URL: https://hyphen.ai/docs/agent/log-analysis/ Description: Learn how Hyphen Agent's log analysis feature automates the process of inspecting deployment logs, identifying operational issues, and linking findings to follow-up actions, reducing manual effort and speeding up incident resolution. Hyphen Agent can analyze deployment logs, summarize operational issues, and connect findings to follow-up work. Log analysis helps teams move from raw runtime data to prioritized findings without manually combing through logs, which makes incidents and recurring errors faster to understand. Use log analysis when you want Agent to investigate errors, anomalies, or recurring runtime behavior for an app or environment. ## Requirements Log analysis needs an app and environment that Agent can inspect. Agent uses the log source available for that app: - Cloud provider container logs by default. - New Relic APM data when the app is connected to New Relic. For New Relic-backed analysis, configure the New Relic integration and map the APM data to the relevant Hyphen environment. See [Setup and Requirements](/docs/agent/setup-and-requirements#new-relic-configuration) for supported connection patterns. ## Automatic and Manual Runs Policy-driven log analysis tasks run automatically from the effective Agent task policy for each deployment target. Hyphen resolves that policy from matching organization, project, project environment, deployment, or project-and-deployment scope, depending on how your policies are configured. By default, production environments have log analysis enabled on a daily recurring schedule. Development and custom environments are disabled until a policy enables them. When a policy is disabled or has no recurring schedule, Hyphen does not create scheduled log analysis tasks for that deployment target. Scheduled policy runs create one-off Log Analysis tasks for the resolved deployment target. The task includes the project, project environment, and deployment references that caused the scheduled run. If you have permission, ask Hyphen Agent to run log analysis manually for the relevant project and environment. Manual Log Analysis tasks are one-off tasks, not recurring tasks. Agent uses attached project and environment context first; if the request is ambiguous, Agent asks you to choose the intended resource before starting the task. ## How It Works Agent scopes the run to the selected app and environment, then analyzes the available log or APM data for patterns that may explain failures or degraded behavior. During a run, Agent can: - Review available log coverage. - Identify findings by category and severity. - Explain likely causes and affected runtime behavior. - Link findings back to the Agent task and run that produced them. If GitHub is connected for the app, Agent can also connect findings to repository follow-up. Depending on the finding and repository context, Agent may create a new issue, comment on a matching existing issue, and comment `/hyphen` so that Agent will attempt to [open a pull request](/docs/agent/github-pull-request-automation) to resolve the issue. ## Repeat Findings When Log Analysis finds an issue that matches a previous finding, Hyphen uses a fingerprint based on the repository, affected apps, and error signature to avoid creating duplicate GitHub issues. If the existing GitHub issue is open, Agent adds a new comment with the latest Log Analysis context instead of creating another issue. This updates the issue record for the latest run, but it does not enqueue another pull request automation run just because the same open issue appeared again. If the existing issue is closed, Agent checks the issue context before deciding what to do next. Issues that appear intentionally declined or not planned are skipped. Issues that appear fixed wait for a 24-hour reopen delay from the latest fix signal, such as a merged linked pull request, before Agent reopens the issue. After that delay, Agent can reopen the issue, add the latest Log Analysis comment, restore the Hyphen Agent label, and enqueue follow-up automation. If GitHub no longer returns a recorded issue, Agent skips creating a replacement issue for that fingerprint. ## Results Log analysis results appear in Agent task and run views. A run can include: - Coverage metrics showing how much data Agent analyzed. - Findings grouped by category and severity. - Issue action summaries, including created, commented, or skipped actions. - Repository and pull request context when Agent proposes a code change. ## Things to Know - Log analysis uses cloud provider container logs unless New Relic APM is connected for the app. - New Relic-backed analysis depends on the app-to-environment mapping configured in Hyphen. - Issue automation is additive. Agent can comment on matching issues, but it does not rewrite existing issue bodies. - Pull requests from log analysis require a connected GitHub repository for the affected app. - Agent-created pull requests are reviewable and are not merged automatically. ### Deployment Optimizer URL: https://hyphen.ai/docs/agent/optimizer/ Description: A guide to using Hyphen Agent's Deployment Optimizer for analyzing runtime signals and recommending deployment configuration changes to reduce waste and improve reliability. Hyphen Agent can optimize a project environment by analyzing runtime signals and recommending deployment configuration changes. Optimizer runs help reduce waste, improve reliability during traffic changes, and keep deployment settings aligned with real workload behavior. Use the optimizer when you want infrastructure sizing and placement to better match current demand. This guide covers deployment optimizer runs for Hyphen project environments. For registered Kubernetes workload optimization, see [Kubernetes Optimizer](/docs/agent/kubernetes-optimizer). ## Requirements Optimizer runs need a project environment Agent can inspect, deployment and runtime data for that environment, and permission to view the related resources. The optimizer can use signals such as: - CPU usage. - Memory usage. - Requests per second. - Current deployment settings. - Recent deployment activity. - Recent optimizer run history. ## Automatic and Manual Runs Policy-driven optimizer tasks run automatically based on the Agent task policy set at the organization level. If you have permission, ask Hyphen Agent to run the optimizer manually for a project environment. When you ask manually, Agent uses attached project and environment context first. If the request is ambiguous, Agent asks you to choose the intended environment before starting the task. ## How It Works Agent creates an optimizer task for the selected project environment. The task investigates workload behavior, compares it to the current deployment configuration, and generates ranked recommendations. Recommendations can include: - Right-sizing container resources. - Adjusting minimum and maximum instance counts. - Changing provider or region-specific scale settings. - Consolidating underused capacity. - Shutting down resources that are no longer needed. Agent uses deployment context before recommending changes so results reflect the current configuration and avoid repeating recent optimizer actions. ## Approvals and Guardrails Optimizer recommendations are designed to preserve declared availability expectations. Agent cannot lower your SLA availability tier, and recommendations that touch scale require approval before they are applied. When approval is needed, Hyphen presents a structured input request. After an approved change is applied, Agent can trigger the deployment run needed to roll out the updated configuration. If you reject a recommendation with a reason, the reason appears alongside the user who responded in the recommendation's details. ## Results Optimizer task and run views show the investigation, recommended changes, approval requests, and execution output. Recommendations include the proposed change, affected scope, and risk or approval context when available. The run view includes a scope summary (the deployment analyzed and its size) and an evidence strip showing the metrics Agent used, each with its trend over the analysis window, the sample count, and the observability provider. ## Things to Know - Optimizer work is scoped to a project environment. - Agent considers current settings, recent deployment activity, and recent optimizer outcomes. - Availability remains user-owned; Agent does not change the SLA availability tier. - Scale changes require approval and are not self-approved. - Deployment settings drift alerts are shown in Hyphen Deploy surfaces, while optimizer work runs as an Agent task. ### Stale Feature Flag Cleanup URL: https://hyphen.ai/docs/agent/stale-feature-flag-cleanup/ Description: Learn how Hyphen Agent automates the identification and cleanup of stale feature flags to reduce release risk and code complexity. Hyphen Agent can identify stale Toggle feature flags and prepare cleanup pull requests for review. Stale feature flag cleanup reduces release risk and code complexity by turning unused or fully settled flags into reviewable removal work. Use it to reduce technical debt from flags that are no longer active or no longer changing behavior. ## Requirements Stale feature flag cleanup needs: - Hyphen Toggle usage data. - Feature flags that are not marked perpetual. - A connected GitHub repository for the app when code cleanup pull requests are needed. - Permission to run or manage the applicable Agent task policy. ## How It Works Agent analyzes Toggle flag activity and identifies flags with no recent usage or unchanged return values over a 90-day window. When Agent finds stale flags, it can: - Mark eligible flags as stale. - Exclude flags marked as perpetual. - Use connected repository context to find stale flag references in code. - Open a cleanup pull request for review. Agent delivers code changes through pull requests. Your team reviews, tests, and merges those changes through your normal repository workflow. ## Automatic and Manual Runs Policy-driven stale feature flag cleanup tasks run automatically based on the Agent task policy set at the organization level. Admins can enable or disable the cleanup policy and choose one of these schedules: - Manual only. - Every day. - Every week. - Every month. - Every quarter. If you have permission, ask Hyphen Agent to run stale feature flag cleanup manually. Teams can ask Agent to run cleanup manually even when the organization policy is set to manual only. ## Results Agent task and run views show the cleanup run, related feature flags, repository context, pull request status, and any required approvals. ## Things to Know - The stale window is based on no recent usage or unchanged return values over 90 days. - Perpetual feature flags are excluded from stale flag cleanup. - Pull request cleanup requires a connected GitHub repository for the affected app. - Cleanup changes are reviewable and are not merged automatically. - Users without policy management access may be able to view the policy but cannot change it. ### Kubernetes Optimizer URL: https://hyphen.ai/docs/agent/kubernetes-optimizer/ Description: A guide to using the Kubernetes Optimizer feature in Hyphen Agent to analyze and recommend optimizations for Kubernetes workloads. Hyphen Agent can analyze a workload in a registered Kubernetes cluster and recommend optimization changes. Kubernetes optimizer runs use cluster inventory, workload context, and connected observability signals to surface findings and replica guidance for a specific workload. Use Kubernetes Optimizer when you want Agent to review whether a workload's current replica count matches expected demand, readiness, and recent cluster signals. ## Requirements Kubernetes optimizer runs need: - A [registered Kubernetes cluster](/docs/kubernetes/add-cluster) with Horizon connected. - A recent [inventory snapshot](/docs/kubernetes/inventory-snapshots) for the cluster. - A selected Kubernetes workload, including namespace, kind, and name. - Permission to view the cluster and run Agent tasks for the organization. - Permission to approve scale changes when approval is required. For runtime metrics and logs, connect a supported provider from the cluster's **Settings** tab. See [Kubernetes Observability](/docs/kubernetes/observability). An observability connection is recommended but not required. Agent can use workload and inventory signals such as: - Current and ready replicas. - Related pods, services, and warning events. - Sibling workloads that appear to belong to the same app. - Inventory truncation state. - Active planned events that may change expected demand. - HorizontalPodAutoscaler evidence when available. - CPU and memory request utilization, restart counts, and workload logs when a supported observability source is connected. ## Automatic and Manual Runs Kubernetes optimizer runs for a workload can be scheduled with a policy, or started manually. Each Deployment or StatefulSet can have its own optimizer policy, configured from the cluster's **Settings** tab. A workload with no policy is not scanned automatically, but can still be optimized on demand. See [Optimizer Policies](/docs/kubernetes/optimizer-policies). You can start a Kubernetes optimizer run manually for a workload in a registered cluster in two ways: - Ask Hyphen Agent from chat. Agent uses attached cluster and workload context first. If the request is ambiguous, Agent asks you to identify the intended cluster or workload before creating the Kubernetes optimizer task. - Click **Optimize now** on a Deployment or StatefulSet's details panel in the cluster diagram. Example prompts: - "Run optimizer for the checkout web deployment in the production cluster." - "Analyze the `checkout/web` workload replicas." - "Should this Kubernetes workload be scaled before the launch event?" While a workload has an optimizer run in progress, the cluster diagram highlights its node. If the run needs a decision, the node also shows a badge you can use to jump to the run. ## How It Works Agent resolves the Kubernetes cluster and workload target, reads the latest workload inventory, and queries connected New Relic or Google Cloud telemetry when available. It analyzes the combined evidence for optimization opportunities. Recommendations can include: - Findings about workload readiness, risk, or missing evidence. - Replica guidance when inventory supports a direct recommendation. - Capability gaps when Agent cannot make a safe recommendation from the available data. Telemetry is bounded to the target workload, relevant pods, and the analysis time range. If a provider query fails or inventory cannot attribute pods precisely, Agent reports the missing evidence instead of treating it as a healthy signal. If the workload appears to be managed by a HorizontalPodAutoscaler, Agent does not recommend manual replica changes. If autoscaling ownership is unknown, Agent calls out the uncertainty before recommending manual replica guidance. ## Approvals and Guardrails Kubernetes optimizer recommendations are review-first. Scale recommendations require explicit approval before anything changes. Before applying an approved replica change, Hyphen rechecks the workload against the replica count that was reviewed. If the workload has changed, cannot be found, or appears to be managed by autoscaling, Agent skips the change and reports why. If you reject a recommendation with a reason, the reason appears alongside the user who responded in the recommendation's details. ## Results Kubernetes optimizer task and run views show the selected cluster, workload, analyzed inventory context, findings, recommendation details, approval requests, and final output. The run view includes a scope summary (the workload analyzed and its size) and an evidence strip showing the metrics Agent used, each with its trend over the analysis window, the sample count, and the observability provider. After an approved scale change, Hyphen refreshes inventory so you can review the updated cluster state. ## Things to Know - Kubernetes optimizer work is scoped to one workload in one registered cluster per run. - Horizon must be connected before Agent can inspect workload inventory. - Agent does not request or use Kubernetes Secret data for optimizer analysis. - Inventory gaps or truncated inventory can lower recommendation confidence. - Missing or partial observability signals can lower recommendation confidence but do not prevent inventory-only analysis. - Manual replica guidance is skipped when matching HorizontalPodAutoscaler evidence is detected. ### Kubernetes Resource Cleanup URL: https://hyphen.ai/docs/agent/kubernetes-resource-cleanup/ Description: Automate and manage Kubernetes resource cleanup with Hyphen Agent. Scan for stale resources, review candidates, and approve deletions to reduce cluster clutter. Hyphen Agent can scan a registered Kubernetes cluster for stale, dead, or unused resources and present cleanup candidates for review. Kubernetes resource cleanup helps reduce cluster clutter by turning risky manual cleanup work into an auditable Agent run with explicit approval for each candidate. Use Kubernetes resource cleanup when you want Agent to find cleanup candidates in a cluster. The internal Agent task type is `KubernetesResourceCleanup`. ## Requirements Kubernetes resource cleanup needs: - A [registered Kubernetes cluster](/docs/kubernetes/add-cluster) that Hyphen Agent can inspect. - Permission to view the cluster and run Agent tasks for the organization. - Permission to manage Agent task policies when changing organization or cluster cleanup policy settings. Agent must be able to collect cluster inventory, including namespaces, workloads, pods, services, endpoints, ingresses, config maps, and events. ## Automatic and Manual Runs By default, Kubernetes resource cleanup is enabled with a daily recurring schedule and a 14-day cleanup threshold. Scheduled runs are created from the effective Kubernetes cleanup policy for each registered cluster. If the effective policy is set to manual only, Hyphen does not create scheduled cleanup scans for that cluster. If you have permission, ask Hyphen Agent to scan a registered Kubernetes cluster manually. Manual cleanup scans are one-off tasks. Agent uses attached cluster context first; if the request does not identify exactly one cluster, Agent asks you to choose the intended cluster before starting the scan. ## Policies Kubernetes resource cleanup is controlled by an Agent task policy. The organization policy defines the default behavior for registered clusters. For step-by-step Kubernetes management instructions, see [Cleanup Policies in the Kubernetes section](/docs/kubernetes/cleanup-policies). The organization policy can configure: - Whether scheduled Kubernetes cleanup is enabled. - The recurring schedule, including manual-only mode. - The cleanup threshold in days. - Ignored namespaces. - Ignored Kubernetes resource UIDs. Individual Kubernetes clusters can override the organization policy. Use a cluster override when one cluster needs a different schedule, cleanup threshold, ignored namespaces, or ignored UIDs than the organization default. Cluster policy overrides apply only to that cluster. Removing the cluster override returns the cluster to the organization policy. The effective ignored namespace and UID lists also include Hyphen's built-in platform exclusions, such as Kubernetes system namespaces. ## How It Works Agent starts by collecting inventory from the selected cluster. It filters out ignored namespaces and ignored UIDs, then scores resources against the cleanup threshold and Kubernetes state signals. Agent can identify cleanup candidates such as: - Empty namespaces. - Workloads scaled to zero. - Completed or failed jobs. - Suspended cron jobs. - Terminal standalone pods. - Unreferenced config maps. - Services without endpoints. - Ingresses without live backends. - Orphan endpoint objects. - Unready workloads with warning events. Each finding includes the resource, category, confidence, reason, and evidence. If Agent finds no cleanup candidates, the run completes without requesting decisions. ## Approvals and Decisions Kubernetes cleanup scans are read-only until a cleanup candidate is explicitly approved. When Agent finds candidates, each candidate becomes an input request. Approved deletions are scoped to the single flagged Kubernetes resource. Agent does not delete related application workloads, namespaces, or other resources unless those resources are separately flagged and explicitly approved. Decision options include: - **Clean up** - Approves deletion of the candidate Kubernetes resource. - **Do nothing** - Skips the candidate for this run. - **Always ignore** - Adds the namespace or resource UID to the cleanup ignore policy when possible. - **Ignore namespace always** - Adds the candidate's namespace to the ignore policy. This option appears for namespaced resources. If an input request times out, Agent records the timeout and does not clean up that resource. If a cleanup deletion fails, the run records the failure so you can review what happened. ## Results Kubernetes resource cleanup task and run views show the scan, cluster, threshold, inventory summary, findings, approval requests, decisions, and cleanup output. Results can include counts for cleaned up resources, skipped resources, ignored resources, timed-out requests, successful deletes, already-absent resources, and delete failures. ## Things to Know - Kubernetes resource cleanup is scoped to one registered cluster per run. - The default cleanup threshold is 14 days. - Built-in platform namespaces are excluded from cleanup scans by default. - Ignored namespaces and ignored UIDs prevent matching resources from being flagged. - Agent does not delete Kubernetes resources unless a cleanup candidate is explicitly approved. - Cluster overrides are useful for clusters with different operational rules than the organization default. ### GitHub Pull Request Automation URL: https://hyphen.ai/docs/agent/github-pull-request-automation/ Description: Learn how Hyphen Agent automates the creation of GitHub pull requests from findings, streamlining the code review process. Hyphen Agent can turn supported findings into reviewable GitHub pull requests. Pull request automation helps teams move from an Agent finding to a concrete code review without losing the context that produced the recommendation. This task is automatically used when an issue created by the Log Analysis task is tagged with the comment `/hyphen`. ## Requirements Pull request automation needs: - A connected GitHub integration. - A connected repository for the affected app. - Repository access for Agent to create branches and open pull requests. - Enough task context for Agent to identify the relevant code change. If a repository is not connected, Agent can still surface findings where supported, but it cannot open repository pull requests. ## What Can Trigger a Pull Request Agent can open pull requests from supported task findings, including: - Log analysis findings where Agent identifies an actionable code fix. - Any time Agent is tagged in a GitHub issue comment. The pull request includes context from the Agent task and run so reviewers can understand why Agent proposed the change. If you have the Hyphen Agent installed in your GitHub organization, you can comment `/hyphen` on an issue to ask it to prepare a pull request to address that issue. When you ask manually, Agent uses the connected repository and task context it can access. ## Review Workflow Agent-created pull requests follow your normal GitHub workflow. Reviewers can inspect the diff, run checks, approve, and merge according to your repository rules. Agent does not automatically update the pull request in response to review comments. Agent does not merge pull requests automatically as part of this workflow. ## Pull Request State Updates When a GitHub webhook reports that an Agent-created pull request was closed or reopened, Hyphen updates the matching Agent task run. The run stores the pull request state and whether GitHub reported it as merged. If the pull request is closed without being merged, the run shows the pull request as closed and not merged. If the pull request is merged, the run records the closed state with `merged` set to true. Hyphen applies this update to both GitHub issue automation runs and app-specific cleanup runs that include pull request cards. Closing a pull request does not automatically rerun Agent or merge code. Review, reopening, and merge decisions remain in GitHub and follow your repository workflow. ## Results Agent task and run views can show: - The repository and base branch Agent used. - Completed automation steps and timing. - Pull request cards with open, closed, or merged states. - Links back to the Agent task, related finding, repository, issue, and pull request. ## Things to Know - Pull requests require GitHub to be connected for the affected app. - Agent proposes code changes through pull requests instead of pushing directly to production code. - Log analysis may create or comment on issues before a pull request is opened. - Review, testing, and merge decisions remain with your team. ### MCP Overview URL: https://hyphen.ai/docs/mcp/mcp-overview/ Description: An overview of the Hyphen MCP server, its capabilities, and how it enables AI assistants and coding agents to interact with the Hyphen platform. The Hyphen MCP server connects AI assistants and coding agents to your Hyphen organization. Once connected, tools like Claude, Cursor, and VS Code can manage feature flags, deployments, ENV secrets metadata, short links, agent tasks, audit events, and more — using the same permissions you have in the Hyphen App. [MCP (Model Context Protocol)](https://modelcontextprotocol.io) is the open standard AI clients use to call external tools. Hyphen hosts an MCP server, so there is nothing to install or run yourself: | Endpoint | URL | | --- | --- | | Production | `https://mcp.hyphen.ai/` | | Explicit organization | `https://mcp.hyphen.ai//` | The server is **authenticated by default**: every request needs a Hyphen credential, and your organization is resolved automatically from it. If you belong to multiple organizations, pin one with the `//` form of the URL. ## What You Can Do The server exposes 60+ tools across the Hyphen platform. Some examples of what a connected agent can handle conversationally: - **Ship code** — "Deploy this repo to a preview environment" walks through project and app setup, Docker packaging, environment variables, the deployment run, and its logs. See [Deploy](../deploy/deploy-quickstart). - **Manage feature flags** — create and update [toggles](../feature-flags/toggle-quickstart) and [segments](../feature-flags/segments), then verify with a live edge evaluation that returns the same answer a real user would receive. - **Clean up stale flags** — telemetry-backed tools find flags that no longer vary, and a guided workflow removes them from your codebase before retiring them in Hyphen. - **Investigate incidents** — search the organization [audit log](../introduction/dashboard) and correlate it with deployment runs, logs, and metrics to answer "what changed right before things broke?" - **Operate Agent tasks** — schedule and inspect [Hyphen Agent](../agent/agent-overview) automations, review their runs, and answer their questions when a run is waiting on input. - **Manage short links** — create [short links](../url-shortening/create-short-link) and QR codes, and analyze click performance. - **Answer platform questions** — search these docs live, so answers come from current documentation instead of stale training data. The full catalog is in the [tool reference](./tools), and the packaged workflows are in [prompts and resources](./prompts-and-resources). ## Access and Safety - **Your credential, your permissions.** Every tool call runs as you. What a connected agent may do is decided by the Hyphen API per request from your organization membership and roles — the same rules as the Hyphen App. Sign in with OAuth or an API key; see [Getting Connected](./getting-connected). - **Permission prompts on writes.** Tools that modify data are annotated as such, and destructive operations (deletes, deployment run triggers, agent chat) carry an additional destructive hint, so well-behaved MCP clients ask for your confirmation before running them. - **A production gate on deployments.** A deployment run that targets a production-type environment is refused unless the call explicitly acknowledges production — and agents are instructed to do that only after you confirm. - **ENV secret values never pass through the server.** Hyphen ENV values are [end-to-end encrypted](../env-secrets-management/end-to-end-encryption) with a key only you hold, so the server can only ever read secrets *metadata* (names, counts, versions). Use the [Hyphen CLI](../introduction/cli) (`hx env pull`) locally when you need values. ## Health Endpoints Two public, unauthenticated endpoints let uptime monitors probe the server: `GET /pingz` for liveness and `GET /healthz` for a health report with per-dependency detail (`200` when healthy, `503` when any dependency is down). ## Next Steps - [Getting Connected](./getting-connected) — authenticate and set up your MCP client - [Tool Reference](./tools) — every tool, grouped by product area - [Prompts and Resources](./prompts-and-resources) — packaged workflows like `deploy_app` and `cleanup_stale_flags` The server is open source at [github.com/Hyphen/mcp](https://github.com/Hyphen/mcp) and published to the [official MCP registry](https://registry.modelcontextprotocol.io) as `ai.hyphen/mcp`. ### Getting Connected URL: https://hyphen.ai/docs/mcp/getting-connected/ Description: A comprehensive guide on connecting various MCP clients to the Hyphen AI platform, detailing authentication methods (OAuth and API keys) and setup instructions for popular tools. Connect your MCP client to `https://mcp.hyphen.ai/` and authenticate with your Hyphen account. This guide covers both authentication options and setup for the most common clients. ## Authentication Every MCP request needs a Hyphen credential. There are two options, and both resolve to the same identity and permissions: 1. **OAuth (recommended)** — clients that support the MCP OAuth discovery flow (Claude Code, Claude Desktop, claude.ai, Cursor) authenticate automatically: the server answers the first unauthenticated request with a challenge, and the client opens a browser window to sign you in through `auth.hyphen.ai`. 2. **API key** — create an API key in the [Hyphen App](https://app.hyphen.ai) under **Settings → API Keys** and send it as the `x-api-key` header. Use this for CI, headless agents, or clients without OAuth support. > 📘 API keys carry the access they were granted at creation time. Scope them to the projects your agent actually needs. ## Claude Code ```bash # OAuth claude mcp add --transport http hyphen https://mcp.hyphen.ai/ # or with an API key claude mcp add --transport http hyphen https://mcp.hyphen.ai/ --header "x-api-key: " ``` With OAuth, adding the server doesn't sign you in yet — inside Claude Code, run `/mcp`, select **hyphen**, and authenticate; a browser window opens the first time. ## Claude Desktop and claude.ai Go to **Settings → Connectors → Add custom connector**, paste `https://mcp.hyphen.ai/`, and sign in when prompted. ## Cursor Use the [one-click install](https://cursor.com/install-mcp?name=hyphen&config=eyJ1cmwiOiJodHRwczovL21jcC5oeXBoZW4uYWkvIn0=), or add the server to `~/.cursor/mcp.json`: ```json { "mcpServers": { "hyphen": { "url": "https://mcp.hyphen.ai/" } } } ``` ## VS Code Use the [one-click install](https://vscode.dev/redirect/mcp/install?name=hyphen&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.hyphen.ai%2F%22%7D), or add the server to your `mcp.json` with an API key: ```json { "servers": { "hyphen": { "type": "http", "url": "https://mcp.hyphen.ai/", "headers": { "x-api-key": "" } } } } ``` > 📘 VS Code's OAuth sign-in depends on dynamic client registration, which Hyphen's authorization server doesn't offer yet (see [troubleshooting](#troubleshooting)) — the API key header is the reliable path in VS Code today. ## Other Clients Any client that speaks streamable HTTP works. The generic `mcpServers` shape, with an API key for clients that don't handle the OAuth flow: ```json { "mcpServers": { "hyphen": { "type": "streamable-http", "url": "https://mcp.hyphen.ai/", "headers": { "x-api-key": "" } } } } ``` ## Picking an Organization Your organization is resolved automatically from your credential. If you belong to more than one organization, pin the one a client should use by putting its ID in the URL: ``` https://mcp.hyphen.ai// ``` ## Verify the Connection Ask your assistant something like *"Who am I in Hyphen?"* — it should call the `whoami` tool and answer with your user, member, and organization. From there, try *"List my projects"* or *"What feature flags haven't been evaluated lately?"* ## Troubleshooting - **The OAuth sign-in fails in your client.** Some clients require OAuth dynamic client registration, which Hyphen's authorization server does not offer yet. Fall back to an [API key](#authentication) in any client that lets you set request headers — Claude Code, Cursor, VS Code, and generic `mcpServers` configs. (Claude Desktop and claude.ai don't accept custom headers, but their connector flow signs in with OAuth and doesn't need one.) - **You see a `401` before signing in.** That is the OAuth flow working as designed: the first unauthenticated request is challenged, and the challenge tells the client where to sign in. If your client never opens a browser after the `401`, configure an API key instead. - **Tools fail with permission errors.** Tool calls run with your Hyphen permissions (or the API key's). If you can't do something in the [Hyphen App](https://app.hyphen.ai), the MCP server can't do it either — ask an organization admin to adjust your role or the key's access. ### Tool Reference URL: https://hyphen.ai/docs/mcp/tools/ Description: A comprehensive reference guide to all tools exposed by the Hyphen MCP server, categorized by product area. Every tool the Hyphen MCP server exposes, grouped by product area. You don't call these directly — your assistant picks the right ones for a request — but knowing what's available helps you ask for the right things. ## Conventions - **Organization scoped.** Every tool operates within the organization resolved from your credential (or pinned in the [server URL](./getting-connected#picking-an-organization)). - **Pagination.** List tools take `page_num` / `page_size` and return a `{ data, totalCount, totalPages }` envelope. - **Permission prompts.** Tools that modify data are annotated as writes, and destructive operations — deletes, deployment run triggers, and the chat tools that drive the platform agent — carry a destructive hint, so MCP clients ask for your confirmation before running them. - **Production gate.** On top of client-side prompts, the server refuses a deployment run that targets a production-type environment unless the call sets `acknowledge_production: true`, which agents are instructed to do only after you explicitly confirm. ## Context | Tool | What it does | | --- | --- | | `whoami` | The authenticated user, member, and organization for the session. | | `get_organization` | Details of the current organization. | ## Projects and Environments | Tool | What it does | | --- | --- | | `list_projects` | List the organization's projects. | | `get_project` | Fetch one project by ID or alternate ID. | | `create_project` | Create a project. | | `list_environments` | List a project's environments, including their types. | ## Apps | Tool | What it does | | --- | --- | | `list_apps` | List apps, optionally scoped to a project. | | `get_app` | Fetch one app. | | `create_app` | Create an app in a project. | ## Deployments Observability and control for [Hyphen Deploy](../deploy/deploy-quickstart). | Tool | What it does | | --- | --- | | `list_deployments` | List deployments with readiness (`isReady`, `readinessIssues`). | | `get_deployment` | Fetch one deployment. | | `get_deployment_metrics` | CPU, memory, requests-per-minute, and instance-count statistics per traffic region. | | `list_deployment_runs` | Run history with statuses (`queued`, `running`, `succeeded`, `failed`, …). | | `get_deployment_run` | One run with pipeline detail. | | `get_deployment_run_logs` | A run's pipeline log entries, for debugging failures. | | `start_deployment_run` | Start a run — each app's latest build by default, or pinned artifacts (`build_id` or a container image URI). Production-gated. | | `cancel_deployment_run` | Stop a run mid-flight. | | `rollback_deployment` | Redeploy the exact build artifacts of a previous successful run; the last known-good run is picked automatically when `run_id` is omitted. Production-gated. | ## Feature Toggles Manage [feature flags](../feature-flags/toggle-quickstart) and their targeting. | Tool | What it does | | --- | --- | | `list_toggles` | List a project's toggles. | | `get_toggle` | One toggle with its targeting configuration. | | `create_toggle` | Create a toggle. | | `update_toggle` | Update a toggle's values or targeting. | | `delete_toggle` | Retire a toggle. | | `evaluate_toggle` | Evaluate a flag against the Horizon edge — the same answer a real user would receive. Auto-discovers your organization's `public_…` evaluation key when you don't pass one. | ## Toggle Segments | Tool | What it does | | --- | --- | | `list_toggle_segments` | List a project's [segments](../feature-flags/segments). | | `create_toggle_segment` | Create a segment. | | `update_toggle_segment` | Update a segment's rules. | | `delete_toggle_segment` | Delete a segment. | ## Toggle Lifecycle Intelligence Hyphen records every edge evaluation as telemetry; these tools turn it into flag hygiene. | Tool | What it does | | --- | --- | | `get_toggle_usage_summary` | Evaluation counts per project and environment (`daily: true` for a time series). | | `list_unused_toggles` | Flags older than 90 days whose evaluations have collapsed to a single constant value. | | `get_toggle_usage` | One flag's daily or raw evaluation telemetry. | | `get_toggle_insights` | Classifies a flag as **dormant** (no traffic), **constant** (traffic but no varying result), or **active**. | ## Audit Events | Tool | What it does | | --- | --- | | `search_events` | Query the organization's audit log — every recorded change and access (toggle updates, deployment runs, ENV secret reads and denials, links, members, integrations, …) with actor, timestamp, entity references, IP address, and geolocation. Newest first, filterable by event type, date window, and referenced entities. | ## Agent Tasks and Runs Schedule and inspect [Hyphen Agent](../agent/agent-overview) automations. Requires the agent entitlement. | Tool | What it does | | --- | --- | | `create_agent_task` | Schedule a `StaleFeatureFlagCleanup`, `Optimizer`, `LogAnalysis`, or `ResourceCleanup` task — one-shot or recurring via cron. | | `list_agent_tasks` | List scheduled tasks. | | `get_agent_task` | One task's configuration and state. | | `delete_agent_task` | Remove a scheduled task. | | `list_agent_task_threads` | Recent activity grouped by task, including pull requests the automations opened. | | `list_agent_task_runs` | Executions of one task. | | `list_runs` | Recent runs across tasks. | | `get_run` | One run's progress, findings, and output. | | `respond_to_run_input_request` | Answer a paused run's questions — runs in `action_required` are waiting on exactly that. | ## ENV Secrets (Metadata) | Tool | What it does | | --- | --- | | `list_dotenvs` | List [ENV](../env-secrets-management/env-secrets-management) environments and their metadata. | | `get_app_dotenv` | One app environment's metadata — version, secret count, size. | > 📘 **Metadata only, by design.** ENV values are [end-to-end encrypted](../env-secrets-management/end-to-end-encryption) with a key only you hold, so the server can never read or return secret values. Use the [CLI](../introduction/cli) (`hx env pull`) locally when you need them. ## Short Links | Tool | What it does | | --- | --- | | `list_short_links` | List the organization's [short links](../url-shortening/create-short-link). | | `get_short_link` | One link's details. | | `get_short_link_stats` | Click analytics — totals, referrers, countries, browsers, devices, clicks over time. | | `list_link_tags` | Tags in use across links. | | `create_short_link` | Shorten a URL, with optional custom code, domain, title, and tags. | | `create_link_qr_code` | Generate a [QR code](../url-shortening/create-a-qr-code) for a link. | | `delete_short_link` | Delete a link. | ## Platform Agent Chat Drive [Hyphen Agent](../agent/agent-overview) chat sessions from your own assistant. Because the platform agent can create, modify, or delete organization resources server-side, these tools carry the destructive hint and prompt for permission. | Tool | What it does | | --- | --- | | `create_chat_session` | Start a chat session with the platform agent. | | `send_chat_message` | Send a message into a session. | | `respond_to_chat_input_request` | Answer the agent's structured confirmation or selection prompts. | | `list_chat_sessions` | List sessions. | | `get_chat_session` | One session's state. | | `get_chat_messages` | A session's message history. | | `close_chat_session` | Close a session when work is complete. | ## Utilities | Tool | What it does | | --- | --- | | `get_ip_info` | IP geolocation via [Net.Info](../net-info/netinfo-quickstart). | | `get_dockerfile_example` | A production-ready Dockerfile example for a language and framework (ASP.NET Core, Express, Fastify, Next.js, React). | | `get_dockerignore_example` | The matching `.dockerignore` example. | | `search_docs` | Search the live Hyphen documentation, so answers come from current docs instead of stale training data. | | `get_docs_page` | Fetch one documentation page. | | `get_migration_guide` | A step-by-step guide for migrating to Hyphen — see [prompts and resources](./prompts-and-resources#migration-guides). | ### Prompts and Resources URL: https://hyphen.ai/docs/mcp/prompts-and-resources/ Description: A guide to Hyphen MCP's built-in prompts and resources, detailing their functionality for automating development workflows, managing feature flags, secrets, and deployments. Beyond individual [tools](./tools), the Hyphen MCP server ships packaged **prompts** — multi-step workflows your assistant follows end to end — and **resources** it can read for context. ## Prompts MCP prompts show up natively in your client: in Claude Code they appear as slash commands (`/mcp__hyphen__deploy_app`), in Claude Desktop and Cursor they're in the prompt picker. Each one turns a multi-step operation into a guided conversation, with your confirmation gating anything that changes state. All arguments are optional unless noted — when omitted, the workflow discovers what it needs or asks you. ### `deploy_app` Turns a coding agent into a ship-it workflow for the repo it has open: detect the language, framework, and port; create the Hyphen project and app if needed; write the `.hx` link file; generate Docker packaging from the built-in examples; check ENV metadata; then deploy **preview-first** — `hx deploy` in your terminal when the working copy has uncommitted changes (only the [CLI](../introduction/cli) can package local code), a deployment run otherwise. It watches the run and logs, fixes failures, and promotes to production only after your explicit confirmation. Arguments: `project_id`, `app_id`, `environment`. ### `rollout_feature_flag` Create or update a toggle, adjust its targeting (default value, percentage, or segments), and verify the rollout with a live edge evaluation — the flag should return the expected value for a representative target. Ends with a before/after summary and how to roll back. Arguments: `toggle_key` (required), `project_id`, `environment`. ### `cleanup_stale_flags` Flag hygiene, done safely. Telemetry names the candidates ([lifecycle intelligence tools](./tools#toggle-lifecycle-intelligence) find flags that are dormant or stuck on one value), a production evaluation confirms which branch the code should collapse to, your coding agent removes the flag conditionals from the codebase it already has open — and only after that change ships does `delete_toggle` retire the flag. Arguments: `project_id`, `toggle_key`. ### `investigate_incident` Answers "what changed right before things broke?" — searches the audit log around the incident window, correlates with deployment runs, logs, and metrics, checks suspect flags with live evaluations, and presents a timeline with the most likely cause and the rollback or fix for each suspect. Arguments: `started_at`, `project_id`, `environment`. ### `analyze_link_performance` Pulls click analytics for your short links — totals, referrers, countries, browsers, devices, clicks over time — summarizes trends and anomalies, and recommends next actions. Arguments: `code_id`. ### `migrate_to_toggle` Guided migration to [Hyphen Toggle](../feature-flags/toggle-quickstart): inventory the flags in your current system, recreate them as Hyphen toggles with equivalent targeting, swap your code to an [OpenFeature provider](../feature-flags/toggle-sdks), and verify with live edge evaluations before retiring the old system. Arguments: `source` (e.g. `launchdarkly`, `split`, `unleash`), `project_id`, `language`. ### `migrate_to_env` Guided migration to [Hyphen ENV](../env-secrets-management/env-secrets-management): export secrets from the current store into per-environment `.env` files, push them with the CLI's [end-to-end encryption](../env-secrets-management/end-to-end-encryption) (`hx push`), verify through metadata, and wire up the runtime. Secret values never pass through the server or the chat. Arguments: `source` (e.g. `dotenv`, `doppler`, `vault`), `app_id`. ## Migration Guides The `get_migration_guide` tool backs the migration prompts and also works standalone — ask your assistant *"help me migrate from LaunchDarkly to Hyphen"* and it maps the old system's concepts onto Hyphen's, orders the steps, and names the MCP tool or `hx` CLI command for each one. | Migrating to | From | | --- | --- | | **Toggle** (feature flags) | LaunchDarkly, Split, Unleash, Statsig, Flagsmith, Optimizely, DevCycle, or homegrown flags | | **ENV** (secrets) | `.env` files, Doppler, HashiCorp Vault, AWS Secrets Manager, AWS Parameter Store, Azure Key Vault, GCP Secret Manager, or Infisical | | **Link** (short links) | Bitly, Rebrandly, Short.io, or TinyURL | ## Resources Resources are read-only context your assistant can attach to a conversation: | Resource | Contents | | --- | --- | | `hyphen://organization` | The authenticated organization, user, and member for the session. | | `hyphen://docs` | A live index of the Hyphen documentation — every page with URL and summary. | | `dockerfile://{language}/{framework}` | Production-ready Dockerfile examples (ASP.NET Core, Express, Fastify, Next.js, React). | | `dockerignore://{language}/{framework}` | The matching `.dockerignore` examples. | ### Hyphen Deploy Quickstart URL: https://hyphen.ai/docs/deploy/deploy-quickstart/ Description: A quickstart guide for deploying containerized applications using Hyphen Deploy, covering cloud provider setup, project creation, CLI initialization, and deployment configuration. > 🚧 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: A comprehensive guide to how Hyphen automatically builds Docker images, pushes them to your container registry, and handles deployment configurations. 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 how to run deployments on Hyphen using various methods including GitHub integration, the 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)
### Deploy with GitHub Actions URL: https://hyphen.ai/docs/deploy/deploy-action/ Description: Automate your Hyphen deployments using GitHub Actions. This guide explains how to set up the Hyphen deploy action, configure secrets, and use it in your workflows. This action runs a Hyphen deployment from a GitHub workflow. It wraps the `hx deploy` CLI command, waits for the deployment run to finish, and exposes the resulting deployment ID, run ID, URL, and status as step outputs so subsequent steps can act on them. ## Prerequisites Before using the deploy action, ensure that: - The [Setup hx Command Line](../github-actions/setup-command-line) action has been run. - Your repository contains a `.hx` file at the root (created by `hx init`), or you supply the project, app, and organization values as action inputs. - A deployment has been configured for the project environment you wish to deploy. - Your cloud provider has been connected to Hyphen and a container registry has been created for the project. - A Hyphen API key is available 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**. ## Parameters All parameters are optional. When omitted, the CLI falls back to values from the `.hx` file at the repository root and auto-detects the development environment. - `deploymentId` _(optional)_: A specific deployment ID to run (e.g., `depl_abc123`). When omitted, deploys the development environment. - `environment` _(optional)_: The environment to deploy (maps to `--env`). - `project` _(optional)_: The project to deploy (maps to `--project`). Defaults to `project_id` from the `.hx` file. - `organization` _(optional)_: The organization ID (maps to `--organization`). - `apps` _(optional)_: A comma-separated list of apps to deploy, each optionally specifying a build (e.g., `app1,app2:latest,app3:abld_xxx`). - `noBuild` _(optional)_: Skip the build step and use the latest build. Defaults to `false`. - `dockerfile` _(optional)_: Path to the Dockerfile (e.g., `./Dockerfile` or `./docker/Dockerfile.prod`). - `preview` _(optional)_: Preview name to deploy to (maps to `--preview`). - `prefix` _(optional)_: Host prefix for the preview deployment (maps to `--prefix`). - `path` _(optional)_: Path, if changed from the default, where the repository has been cloned. - `verbose` _(optional)_: Enable verbose logging. Defaults to `false`. ## Outputs The action sets the following step outputs, available to subsequent steps as `steps..outputs.`: - `deployment-id`: The deployment ID that was run. - `run-id`: The deployment run ID. - `deployment-url`: URL to the deployment run in the Hyphen dashboard. - `status`: Final status of the deployment run (`succeeded | failed | canceled`). - `reason`: Failure reason when status is not `succeeded`. Empty on success. ## 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: Deploy id: deploy uses: Hyphen/deploy-action@v1 with: environment: production - name: Report deployment URL run: echo "Deployed at ${{ steps.deploy.outputs.deployment-url }}" ``` ### Deploying on Push to Main and on Release This workflow deploys to development when a PR is merged to `main`, and to production when a release is created. ```yaml deploy.yml 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: Deploy to Development id: deploy uses: Hyphen/deploy-action@v1 with: environment: development - name: Report deployment URL run: echo "Deployed at ${{ steps.deploy.outputs.deployment-url }}" 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: Deploy to Production id: deploy uses: Hyphen/deploy-action@v1 with: environment: production - name: Report deployment URL run: echo "Deployed at ${{ steps.deploy.outputs.deployment-url }}" ``` ### Pulling ENV Secrets Before Deploying If your deployment depends on Hyphen ENV secrets, add the [ENV action](../env-secrets-management/env-secrets) before the deploy step: ```yml deploy.yml - name: Checkout uses: actions/checkout@v4 - name: Setup Hyphen CLI uses: Hyphen/setup-hx-action@v1 with: apiKey: ${{ secrets.HYPHEN_API_KEY }} - name: Pull ENV secrets uses: Hyphen/env-action@v1 with: hxKeyFile: ${{ secrets.HYPHEN_KEY_FILE }} environment: production outputs: files - name: Deploy uses: Hyphen/deploy-action@v1 with: environment: production ``` ## How It Works When the deploy action runs: 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. 5. The action waits for the deployment run to finish and exposes the result to subsequent steps via outputs. 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 provides and manages environment variables, including system-injected variables and user-defined secrets, for your applications. 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) ### Storage URL: https://hyphen.ai/docs/deploy/storage/ Description: Automate cloud object storage provisioning and integration with Hyphen Deploy for seamless application deployments. Hyphen Deploy can automatically provision and connect cloud object storage to your application as part of the deployment pipeline. When Object Storage is configured for a deployment, Hyphen creates the necessary cloud resources and injects credentials into your application — no manual bucket creation or credential management required. Supported providers: - **AWS** — Amazon S3 - **Google Cloud** — Google Cloud Storage (GCS) - **Azure** — Azure Blob Storage ## Prerequisites - A connected cloud provider integration (AWS, GCP, or Azure). See [AWS](../integrations/aws-integration), [Google Cloud](../integrations/google-cloud-integration), or [Azure](../integrations/azure-integration-setup-guide). - A Cloud Workspace connection for the target project environment. ## Enabling Object Storage for a Deployment In the deployment settings for a project environment, toggle on **Enable Object Storage**. Once enabled, two additional fields appear: - **Object storage provider** — A dropdown pre-populated with the cloud integrations connected to your deployment. Select the provider where the bucket or container should live. - **Bucket name (optional)** — Enter an existing bucket name to connect to it, or enter a preferred name for the bucket Hyphen will create. If left blank, Hyphen generates a name automatically from the project and environment alternate IDs using the pattern `{projectAlternateId}-{envAlternateId}`. ## Provisioning When a deployment run starts, Hyphen automatically: 1. Verifies the Cloud Workspace connection is ready. 2. Creates or adopts the storage bucket or container in the target cloud. 3. Creates a dedicated access identity scoped to that bucket with least-privilege permissions. 4. Generates credentials and injects them into the application as an environment variable. ### AWS (S3) Resources created: - S3 bucket - IAM user (`hx-S3-{bucketName}`) with a scoped bucket policy - Access key ID and secret key ### Google Cloud (GCS) Resources created: - GCS bucket - Service account (named after the bucket) - Storage Admin IAM role binding on the bucket - Service account key (JSON) ### Azure (Blob Storage) Resources created: - Storage account (if one does not already exist) - Blob container - Service principal in Microsoft Entra ID (`objectStorage-{storageAccount}-{container}`) - RBAC role assignment on the container - Client secret ## Application Access Credentials are injected into your application as a single environment variable: | Variable | Description | | -------- | ----------- | | `HYPHEN_OBJECT_STORAGE_CONFIG` | Base64-encoded JSON containing provider-specific connection credentials | The decoded payload structure varies by provider: **AWS:** ```json { "provider": "aws", "region": "us-east-1", "bucketName": "my-project-production", "accessKeyId": "AKIA...", "accessKeySecret": "..." } ``` **Google Cloud:** ```json { "provider": "googleCloud", "bucketName": "my-project-production", "serviceAccountJson": "{...}" } ``` **Azure:** ```json { "provider": "azure", "tenantId": "...", "storageAccountName": "myprojectprod", "containerName": "my-project-production", "accessKeyId": "...", "accessKeySecret": "..." } ``` ### Parsing the config in your application **Node.js:** ```javascript const config = JSON.parse( Buffer.from(process.env.HYPHEN_OBJECT_STORAGE_CONFIG, 'base64').toString('utf8') ); // config.provider, config.bucketName, etc. ``` **Python:** ```python import os, base64, json config = json.loads(base64.b64decode(os.environ['HYPHEN_OBJECT_STORAGE_CONFIG']).decode('utf-8')) # config['provider'], config['bucketName'], etc. ``` **Go:** ```go import ( "encoding/base64" "encoding/json" "os" ) raw, _ := base64.StdEncoding.DecodeString(os.Getenv("HYPHEN_OBJECT_STORAGE_CONFIG")) var config map[string]interface{} json.Unmarshal(raw, &config) // config["provider"], config["bucketName"], etc. ``` ### Deployment Previews URL: https://hyphen.ai/docs/deploy/deployment-previews/ Description: Learn how to create and manage deployment previews with Hyphen to facilitate collaboration and testing throughout the development lifecycle. ## 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. ### Kubernetes Overview URL: https://hyphen.ai/docs/kubernetes/overview/ Description: An overview of Hyphen's Kubernetes management capabilities, including cluster registration, fleet health monitoring, inventory inspection, observability integration, and resource cleanup. Hyphen Kubernetes management connects registered clusters to your organization through Horizon, then gives you a central place to review fleet health, inspect inventory, connect observability, run Agent analysis, configure cleanup policies, and remove clusters. Horizon is the lightweight agent installed in your cluster. It registers the cluster with your Hyphen organization and reports inventory back to Hyphen so the inventory and cleanup features can work. Use the Kubernetes section when you want to: - Add a cluster to Hyphen with the Horizon install command. - Review fleet health across private, AWS, Google Cloud, and Azure environments. - View inventory snapshots and compare changes over time. - Connect New Relic or Google Cloud metrics and logs to a cluster. - Run Kubernetes optimizer analysis for a specific workload, or schedule it with a policy. - Configure Kubernetes cleanup policies for the organization or for a specific cluster. - Remove a cluster from Hyphen. ![Kubernetes cluster list showing private, AWS, Google Cloud, and Azure clusters](/kubernetes/clusters-list.png) ## Fleet Health The organization dashboard and Kubernetes cluster list summarize the latest inventory across your fleet: - Connected clusters and clusters currently considered healthy. - Ready pods compared with total pods. - Container issues and warnings. - Each cluster's cloud provider, latest inventory time, pod readiness, and health status. Hyphen marks a cluster as needing attention when its latest state or inventory contains issues, warnings, or pods that are not ready. A cluster without inventory shows **Inventory pending** until its first snapshot is available. Select a cluster to investigate the underlying inventory. For the other organization cards, see [Dashboard Overview](/docs/introduction/dashboard). ## Cluster Providers Hyphen identifies the cloud provider for each registered cluster when that information is available. Provider badges appear on the cluster detail page, including Private, Amazon Web Services, Google Cloud, and Microsoft Azure clusters. ![Kubernetes cluster provider badges](/kubernetes/provider-badges.png) ## Observability Connect New Relic or Google Cloud telemetry from a cluster's **Settings** tab. Hyphen Agent can combine those runtime metrics and logs with inventory when it analyzes a Kubernetes workload. See [Kubernetes Observability](/docs/kubernetes/observability) for setup instructions and required provider access. ## Guides - [Add a Kubernetes Cluster](/docs/kubernetes/add-cluster) - [Inventory Snapshots](/docs/kubernetes/inventory-snapshots) - [Observability](/docs/kubernetes/observability) - [Kubernetes Optimizer](/docs/agent/kubernetes-optimizer) - [Optimizer Policies](/docs/kubernetes/optimizer-policies) - [Kubernetes Resource Cleanup](/docs/agent/kubernetes-resource-cleanup) - [Cleanup Policies](/docs/kubernetes/cleanup-policies) - [Remove a Cluster](/docs/kubernetes/remove-cluster) For how Agent scans clusters for stale resources, presents cleanup candidates, and handles approvals, see [Kubernetes Resource Cleanup](/docs/agent/kubernetes-resource-cleanup) in the Agent section. ## Requirements Kubernetes management requires: - A Hyphen organization with Kubernetes access enabled. - Permission to manage organization Kubernetes clusters. - Access to run `kubectl` against the cluster you want to register. - Network access from the Horizon pod to Hyphen. Inventory and cleanup features require the Horizon pod to be installed and connected. Until the cluster reports inventory, Hyphen can show the cluster record but cannot render the inventory graph or calculate inventory-based fleet health. Observability connections are optional and require a supported provider integration. ### Add a Kubernetes Cluster URL: https://hyphen.ai/docs/kubernetes/add-cluster/ Description: Learn how to add a Kubernetes cluster to your Hyphen organization by installing the Horizon pod. Add a Kubernetes cluster by installing the Horizon pod in the cluster. Horizon registers the cluster with your Hyphen organization and reports inventory back to Hyphen. ## Start Registration From your organization: 1. Open **Kubernetes**. 2. Click **Add Kubernetes Cluster**. 3. Enter an optional cluster name. 4. Click **Next**. If you leave the cluster name blank, Horizon sends a generated name when the cluster connects. ![Add Kubernetes cluster modal](/kubernetes/add-cluster-modal.png) ## Install Horizon Hyphen creates an API key for Horizon and generates a `kubectl` command. Copy and run the command against the cluster you want to add. ![Kubernetes install command](/kubernetes/install-command.png) The command creates a bootstrap secret in the `hyphen-horizon` namespace and applies the Horizon manifest. After Horizon starts and connects, the cluster appears in the Kubernetes list. ## Things to Know - The generated command includes a one-time visible API key secret. Treat the command as sensitive. - Run the command against the Kubernetes context for the cluster you want Hyphen to manage. You need sufficient permissions, such as cluster-admin, to create namespaces, secrets, and deployments. - A cluster may take a few minutes to appear after Horizon is installed. - Inventory appears after the cluster reports its first snapshot. ### Inventory Snapshots URL: https://hyphen.ai/docs/kubernetes/inventory-snapshots/ Description: A guide to understanding and using Kubernetes inventory snapshots in Hyphen for cluster inspection and health monitoring. Inventory snapshots show the Kubernetes resources Hyphen can see in a registered cluster. Use snapshots to inspect cluster nodes, namespaces, workloads, pods, services, ingresses, config maps, warnings, and how the cluster changes over time. ## Start the First Snapshot Open **Kubernetes**, select a cluster, and stay on the **Inventory** tab. If the cluster has not reported inventory yet, click **Start Inventory Snapshot**. ![Start the first Kubernetes inventory snapshot](/kubernetes/inventory-empty.png) Hyphen starts a snapshot workflow and shows progress while the cluster refreshes inventory. When the workflow completes, the inventory graph appears. ## View Inventory The inventory graph places cluster nodes in a top band, groups namespaced resources, and connects related workloads, ReplicaSets, pods, services, ingresses, and config maps. ![Kubernetes inventory graph](/kubernetes/inventory-graph.png) Use the graph controls to: - Choose the selected inventory snapshot. - Move to the previous or next loaded snapshot. - Load more historical snapshots when available. - Click **Refresh Inventory** to create a new snapshot. - Toggle **All Namespaces** to include namespaces hidden by the default view. - Filter resources by labels. - Click a resource node to inspect its details. ## Review Cluster Health The Kubernetes list and organization dashboard summarize the latest inventory across registered clusters. Fleet metrics include connected and healthy clusters, ready and total pods, container issues, and warnings. Within a cluster, summary rails help focus the graph: - **Nodes** centers the cluster node band. - **Workloads** groups workloads by app and namespace. - **Pods** summarizes ready and not-ready pods and calls attention to pods that need investigation. - Exposure and warning summaries highlight reachable resources and active issues. Cluster health uses the latest cluster state and inventory. Issues take priority over warnings. A cluster with warnings or not-ready pods needs attention, while a cluster without a snapshot remains unknown and shows **Inventory pending**. ## Inspect a Resource Select a node in the graph to open its resource details. Depending on the resource, the panel can show: - Ownership hierarchy, including Deployment, ReplicaSet, and Pod relationships. - Status, readiness, creation time, labels, metadata, and related resources. - Warning events and container startup issues. - A collapsible raw manifest view. The selected resource is stored in the page URL. You can copy the link to share the same resource view, and use browser back and forward navigation to move through previously selected resources. Agent references can also link directly to supported Kubernetes objects. Use **Zoom to node** in the details panel to re-center the graph on the selected resource without losing your selection. ## Compare Snapshots Turn on **Diff with Previous** to compare the selected inventory snapshot with the immediately older snapshot. Added resources and removed resources are highlighted in the graph. ![Kubernetes inventory diff with previous snapshot](/kubernetes/inventory-diff.png) If there is no earlier snapshot, or if the previous snapshot is still loading, Hyphen explains why the diff is not available. ## Things to Know - Inventory snapshots are read-only. - Refreshing inventory starts a new workflow for the selected cluster. - The latest snapshot is selected by default unless you open a link to a specific snapshot. - Historical snapshot navigation depends on the snapshots already loaded in the selector. - Inventory may omit resources when collection limits are reached. Agent reports truncated inventory as a capability gap when it affects analysis. ### Observability URL: https://hyphen.ai/docs/kubernetes/observability/ Description: Connect Kubernetes telemetry data (metrics and logs) to Hyphen Agent for enhanced observability using New Relic or Google Cloud integrations. Connect Kubernetes telemetry to a registered cluster so Hyphen Agent can use runtime metrics and logs alongside inventory. Kubernetes observability currently supports New Relic and Google Cloud. Observability is optional for inventory and cleanup. It gives [Kubernetes Optimizer](/docs/agent/kubernetes-optimizer) more evidence about workload utilization, restarts, and runtime behavior. ## Before You Start You need: - A [registered Kubernetes cluster](/docs/kubernetes/add-cluster) with Horizon connected. - A New Relic or Google Cloud organization integration in Hyphen. - Permission to manage organization integrations and cluster settings. - Kubernetes telemetry available in the selected provider. ## Connect an Observability Source 1. Open **Kubernetes** and select the cluster. 2. Open **Settings**. 3. In **Observability**, click **Setup connection**. 4. Select one observability integration. 5. Enter the provider-specific cluster identifier. 6. Click **Connect**. ![Connect a Kubernetes cluster to an observability integration](/changelog/kubernetes-observability-connection-setup.png) Hyphen validates the identifier and shows the connection while it is being prepared. A ready connection can supply metrics and logs to supported Agent runs. ### New Relic Enter the cluster name configured when the New Relic Kubernetes integration was installed. Hyphen verifies that the connected New Relic account contains a Kubernetes cluster sample with that name. If Horizon detects one New Relic cluster name and the organization has exactly one New Relic integration, Hyphen can create the connection automatically. A newly installed New Relic agent may take time to send its first cluster sample; Hyphen retries retryable connection failures while telemetry becomes available. See [New Relic](/docs/integrations/new-relic#kubernetes-observability) for integration requirements. ### Google Cloud Enter the full GKE cluster resource name: ```text projects/PROJECT_ID/locations/LOCATION/clusters/CLUSTER_NAME ``` The Hyphen service account needs these roles for the selected cluster and its telemetry: - Logs Viewer (`roles/logging.viewer`) - Monitoring Viewer (`roles/monitoring.viewer`) - Kubernetes Engine Cluster Viewer (`roles/container.clusterViewer`) Hyphen can discover the resource name automatically when Horizon detects Google Cloud observability, the organization has exactly one Google Cloud integration, and Cloud Asset Inventory can resolve the cluster. See [Google Cloud](/docs/integrations/google-cloud-integration#kubernetes-observability) for integration requirements. ## Connection States and Errors - **Pending** - Hyphen is validating the provider and cluster identifier. - **Ready** - Metrics and logs are available to supported Agent analysis. - **Error** - Hyphen could not validate the cluster or query the provider. Open the connection to review the error and retry when available. A missing New Relic cluster sample may be temporary while telemetry is first ingested. A Google Cloud not-found error can mean the resource name is incorrect or the Hyphen service account is missing the required viewer roles. ## Remove a Connection Open the cluster's **Settings** tab, find the provider under **Observability**, and remove its connection. Removing the connection does not uninstall an observability agent or delete provider telemetry. Agent continues to use Kubernetes inventory, but no longer queries that provider for the cluster. ## Things to Know - Metrics and logs are supporting evidence; missing or partial telemetry does not prevent inventory from working. - Hyphen limits telemetry queries by time, workload, and pod context. Provider query errors are reported as capability gaps instead of being treated as healthy evidence. - Connect the provider account that receives telemetry for the registered cluster. - Hyphen does not request Kubernetes Secret contents for optimizer analysis. ### Cleanup Policies URL: https://hyphen.ai/docs/kubernetes/cleanup-policies/ Description: Learn how Kubernetes cleanup policies in Hyphen Agent control the scanning of stale Kubernetes resources, including organization-wide settings and cluster-specific overrides. Kubernetes cleanup policies control how Hyphen Agent scans registered clusters for stale Kubernetes resources. The policy decides whether scheduled cleanup scans run, how often they run, what age threshold Agent uses, and which namespaces or resource UIDs Agent should ignore. For the run behavior, candidate categories, and approval options, see [Kubernetes Resource Cleanup in the Agent section](/docs/agent/kubernetes-resource-cleanup). ## Organization Policy The organization policy is the default Kubernetes cleanup policy for registered clusters. To manage it: 1. Open **Organization Settings**. 2. Go to **Policies**. 3. Find **Kubernetes cleanup**. 4. Use the switch to enable or disable scheduled Kubernetes cleanup. 5. Click **Settings** to edit schedule, threshold, ignored namespaces, and ignored UIDs. ![Organization Kubernetes cleanup policy settings](/kubernetes/org-cleanup-policy.png) The organization policy can configure: - **Enable Kubernetes cleanup** - turns Kubernetes cleanup task creation on or off. When disabled, Hyphen does not create scheduled cleanup scans and manual Agent cleanup requests are blocked for that policy scope. - **Schedule** - controls how often Agent runs cleanup scans. The default is a daily recurring schedule. Choose manual-only mode to disable scheduled scans while still allowing one-off manual requests. Available options are: - Manual only - Every hour - Every 6 hours - Every 12 hours - Every day - Every week - Every month - Every quarter - **Cleanup Threshold** - sets the number of stale days used when deciding whether a resource should be flagged. - **Ignored namespaces** - namespaces Agent should skip. - **Ignored UIDs** - individual Kubernetes resource UIDs Agent should skip. ## Cluster Overrides Each Kubernetes cluster can inherit the organization policy or define its own override. To manage a cluster override: 1. Open **Kubernetes**. 2. Select a cluster. 3. Open the **Settings** tab. 4. In **Policies**, find **Cleanup Policy**. 5. Turn on **Override organization policy**. 6. Edit the schedule, cleanup threshold, ignored namespaces, and ignored UIDs for that cluster. 7. Click **Save override**. ![Cluster Kubernetes cleanup policy override](/kubernetes/cluster-cleanup-policy.png) Cluster overrides apply only to the selected cluster. Removing the override returns the cluster to the organization policy. ## Policy Precedence Hyphen resolves Kubernetes cleanup policy in this order: 1. Use the cluster override when one exists. 2. Otherwise, use the organization policy. This lets most clusters share the organization default while individual clusters use stricter or looser rules when needed. ## Things to Know - Policies affect scheduled Kubernetes cleanup scans and whether manual Agent cleanup requests are allowed. Use manual-only mode, not disabled cleanup, when you want one-off cleanup scans without recurring schedules. - Ignored namespaces and ignored UIDs prevent matching resources from being flagged as cleanup candidates. - Cleanup scans are read-only until a cleanup candidate is explicitly approved in the Agent run. - Cleanup decisions include **Clean up**, **Do nothing**, **Always ignore**, and **Ignore namespace always** when the candidate is namespaced. ### Optimizer Policies URL: https://hyphen.ai/docs/kubernetes/optimizer-policies/ Description: Learn how to configure and manage Kubernetes workload optimizer policies to control the scheduling of optimization runs for Deployments and StatefulSets. Kubernetes workload optimizer policies control which Deployments and StatefulSets Hyphen Agent optimizes on a recurring schedule. Policies are configured per workload, from the cluster's **Settings** tab. For what an optimizer run does and how recommendations are approved, see [Kubernetes Optimizer in the Agent section](/docs/agent/kubernetes-optimizer). ## Configure a Workload To add a policy for a workload: 1. Open **Kubernetes**. 2. Select a cluster. 3. Open the **Settings** tab. 4. In **Policies**, find **Workload Optimization**. 5. Click **Configure workload**. 6. Choose the workload, set whether optimization is enabled, and choose a schedule. 7. Click **Save**. ![Configure workload optimization modal with a workload picker, enable switch, and schedule dropdown](/kubernetes/optimizer-policies-configure.png) Only Deployments and StatefulSets from the cluster's latest inventory can be selected. A workload that already has a policy does not appear again in the picker — each workload can have at most one policy. Available schedules are: - Manual only - Every hour - Every 6 hours - Every 12 hours - Every day - Every week - Every month - Every quarter ## Managing Existing Policies Each configured workload appears as a row showing the workload's kind and namespace, its schedule, an enable/disable switch, and a remove action. - Use the schedule control to change how often Agent runs the Kubernetes optimizer for that workload. - Turn the switch off to pause scheduled runs for a workload without deleting its policy. The schedule control is hidden while a policy is disabled. - Click the remove action to delete the policy entirely. The workload becomes available again in the **Configure workload** picker. ![Cluster Settings page showing the Workload Optimization card with three policies: two enabled on different schedules and one disabled](/kubernetes/optimizer-policies.png) If a workload configured with a policy no longer appears in the cluster's latest inventory, its row is marked **Unavailable in latest inventory**. ## Manual Runs Are Always Available Workload optimizer policies only control scheduled runs. Whether or not a workload has a policy, you can still ask Hyphen Agent to run the optimizer for it from chat, or start a run on demand from the **Optimize now** action on the workload's details panel in the cluster diagram. ## Things to Know - Policies are scoped to a single Deployment or StatefulSet in one cluster. - Managing policies requires permission to manage Agent task policies for the cluster. - Disabling or removing a policy does not cancel a run that is already in progress. - Scheduled runs use the same approval and guardrail behavior as manual optimizer runs. ### Remove a Cluster URL: https://hyphen.ai/docs/kubernetes/remove-cluster/ Description: Learn how to remove a Kubernetes cluster from Hyphen management and understand the implications and necessary cleanup steps. Remove a cluster when Hyphen should stop managing it. Removal starts a workflow that removes Hyphen management for the cluster. ## Remove From Hyphen To remove a cluster: 1. Open **Kubernetes**. 2. Select the cluster. 3. Open the **Settings** tab. 4. Find **Remove Cluster**. 5. Click **Remove**. 6. Type the cluster name to confirm. 7. Click **Remove** in the confirmation modal. ![Remove Kubernetes cluster confirmation](/kubernetes/remove-cluster.png) After removal starts, Hyphen returns you to the Kubernetes cluster list. ## Cleanup Needed If Horizon is still connected, the cluster can enter a **Cleanup needed** state. In that case, remove Horizon from the cluster, for example by running `kubectl delete namespace hyphen-horizon`, or wait for it to disconnect, then remove the cluster again from Hyphen. ## Things to Know - Removing a cluster stops Hyphen from managing that cluster. - Removal does not delete your application workloads. - You need permission to manage Kubernetes clusters in the organization. - If you remove the wrong cluster, reinstall Horizon to register it again. ### ENV Quick Start URL: https://hyphen.ai/docs/env-secrets-management/env-secrets-management/ Description: A quick start guide to 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: Learn how to securely pull and manage application secrets using the Hyphen CLI, including prerequisites, commands, and verification steps. ## 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: Learn how Hyphen's version control system securely manages and tracks changes to your secrets with end-to-end encryption. ## 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: Learn how to view and understand the ENV Access Log in the Hyphen App to trace and audit secret management actions. 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: A guide to managing environment variables and secrets when deploying applications with Docker using Hyphen. 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 deploying applications using ENV for secret management with GitHub Actions, specifically detailing integration with 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 securely rotate encryption keys using the Hyphen CLI to mitigate threats, meet compliance, and strengthen your security posture. > 🚀 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 ENV provides end-to-end encryption to protect your secret keys, ensuring they are never accessible by 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: A GitHub Action to manage environment secrets and variables for your projects, with options to output them as .env files or export them as environment variables. 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 setting up and using Hyphen Toggle for feature flag management with OpenFeature. [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 behind feature toggles, including context, targeting, segments, and telemetry. ## 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. The organization [dashboard](/docs/introduction/dashboard#toggle-usage) shows recent Toggle usage over the last 30 days and links to individual flags. Project and flag views provide more detailed evaluation and usage charts. When usage telemetry is disabled or no usage is reported, those views have less data to display. ### Segments URL: https://hyphen.ai/docs/feature-flags/segments/ Description: Learn how to use Segments in Hyphen to define reusable targeting rules for feature flags, ensuring consistency and efficiency across your projects. Covers creation, usage, JSON logic, and best practices. ## 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 Hyphen Project Public Key for client-side API authentication and accessing read-only features. > ℹ️ 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 Software Development Kits (SDKs) for seamless integration of feature flags into your applications. Supports native Node.js, JavaScript, and React, with Open Feature providers for Go, Python, and Swift. 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 with the OpenFeature SDK in your Go applications using the Hyphen Toggle Provider. Learn about installation, setup, usage, and configuration options. **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/sdk for Node.js, covering both the native server-side SDK and the OpenFeature provider for seamless feature flag management in backend applications. # 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: Comprehensive documentation for integrating Hyphen's feature flag solutions into React applications using both the native @hyphen/react-sdk and the @hyphen/openfeature-web-provider. # 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 the Hyphen Browser SDK and OpenFeature Provider, detailing installation, setup, usage, and configuration for client-side JavaScript feature flag management. # 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 to installing, setting up, and using the Hyphen Provider with the OpenFeature Python SDK for dynamic 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 with .NET applications using the OpenFeature SDK and the Hyphen Toggle provider. 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 with the OpenFeature SDK for Swift applications on 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() } } } ``` ### Overview URL: https://hyphen.ai/docs/sdks/overview/ Description: An overview of Hyphen's native SDKs for integrating with feature flags, geolocation, and other Hyphen services directly from your application code. Hyphen publishes native SDKs so you can work with the Hyphen platform — including [Toggle](https://hyphen.ai/toggle) feature flags and [Net.Info](../net-info/netinfo-quickstart) geolocation — directly from your application code. Every SDK is open source and maintained on [GitHub](https://github.com/orgs/Hyphen/repositories). Pick your language below to get started. ## Available SDKs | Language | Package | Install | Getting started | | -------- | ------- | ------- | --------------- | | Node.js (server) | `@hyphen/sdk` | `npm install @hyphen/sdk` | [Node.js](nodejs) | | JavaScript (browser) | `@hyphen/browser-sdk` | `npm install @hyphen/browser-sdk` | [JavaScript (Browser)](browser) | | React | `@hyphen/react-sdk` | `npm install @hyphen/react-sdk` | [React](react) | | Python | `hyphen` | `pip install hyphen` | [Python](python) | | Go | `github.com/Hyphen/go-sdk` | `go get github.com/Hyphen/go-sdk` | [Go](go) | | .NET (C#) | `Hyphen.Sdk` | `dotnet add package Hyphen.Sdk` | [.NET](dotnet) | ## Authentication All native SDKs authenticate with a project **public key** (it starts with `public_`) and an **application id**. See [Get a Project's Public Key](../feature-flags/project-public-key) for where to find your public key in the Hyphen dashboard. ## Prefer OpenFeature? If you'd rather use the vendor-agnostic [OpenFeature](https://openfeature.dev) API for feature flags, Hyphen also ships OpenFeature providers for Go, JavaScript, Python, React, .NET, and Swift. See [Feature Flags → SDKs](../feature-flags/toggle-sdks) for the full list and setup guides. ### Node.js URL: https://hyphen.ai/docs/sdks/nodejs/ Description: Integrate Hyphen services like Toggle feature flags and Net.Info into your Node.js backend applications with the official Hyphen Node.js SDK. The **[@hyphen/sdk](https://github.com/Hyphen/nodejs-sdk)** is Hyphen's native server-side Node.js SDK. It provides a single client for working with Hyphen services — including [Toggle](https://hyphen.ai/toggle) feature flags and [Net.Info](../net-info/netinfo-quickstart) — from backend services, APIs, and server-rendered applications. ## Installation ```shell npm install @hyphen/sdk ``` ## Authentication The SDK authenticates with your project **public key** (it starts with `public_`) and your **application id**. See [Get a Project's Public Key](../feature-flags/project-public-key) for where to find these in the Hyphen dashboard. You can pass them directly or provide them via environment variables: ```shell HYPHEN_PUBLIC_API_KEY=public_your_api_key HYPHEN_APPLICATION_ID=your_application_id ``` ## Initialization ```javascript import { Hyphen } from '@hyphen/sdk'; const hyphen = new Hyphen({ publicApiKey: 'public_your_api_key', applicationId: 'your_application_id', }); ``` ## Usage Evaluate a boolean feature flag, falling back to a default value if it can't be resolved: ```javascript const enabled = await hyphen.toggle.getBoolean('hyphen-sdk-boolean', false); if (enabled) { // Execute new feature code } ``` ## See also - [GitHub: Hyphen/nodejs-sdk](https://github.com/Hyphen/nodejs-sdk) - Prefer [OpenFeature](https://openfeature.dev)? Use the [JavaScript (Node) provider](../feature-flags/provider-javascript-node). ### JavaScript (Browser) URL: https://hyphen.ai/docs/sdks/browser/ Description: The official Hyphen Browser SDK for JavaScript, enabling efficient feature flag evaluation in web browsers. The **[@hyphen/browser-sdk](https://github.com/Hyphen/browser-sdk)** is Hyphen's native client-side JavaScript SDK for web browsers. It's optimized for evaluating [Toggle](https://hyphen.ai/toggle) feature flags in the browser with a minimal bundle size. ## Installation ```shell npm install @hyphen/browser-sdk ``` ## Authentication The SDK authenticates with your project **public key** (it starts with `public_`) and your **application id**. See [Get a Project's Public Key](../feature-flags/project-public-key) for where to find these in the Hyphen dashboard. ## Initialization Provide a `defaultContext` describing the current user so flags can be targeted correctly: ```javascript import { Toggle } from '@hyphen/browser-sdk'; const toggle = new Toggle({ publicApiKey: 'public_your-api-key-here', applicationId: 'your-app-id', environment: 'production', defaultContext: { targetingKey: 'user-123', user: { id: 'user-123', email: 'user@example.com', name: 'John Doe', }, }, }); ``` ## Usage ```javascript const isEnabled = await toggle.getBoolean('feature-flag', false); if (isEnabled) { console.log('Feature is enabled!'); } ``` ## See also - [GitHub: Hyphen/browser-sdk](https://github.com/Hyphen/browser-sdk) - Prefer [OpenFeature](https://openfeature.dev)? Use the [JavaScript (Web) provider](../feature-flags/provider-javascript-web). ### React URL: https://hyphen.ai/docs/sdks/react/ Description: Documentation for the Hyphen React SDK, enabling feature flag evaluation in React applications. The **[@hyphen/react-sdk](https://github.com/Hyphen/react-sdk)** is Hyphen's native React SDK. It provides a provider component and hooks for evaluating [Toggle](https://hyphen.ai/toggle) feature flags in React applications. ## Installation ```shell npm install @hyphen/react-sdk ``` ## Authentication The SDK authenticates with your project **public key** (it starts with `public_`) and your **application id**. See [Get a Project's Public Key](../feature-flags/project-public-key) for where to find these in the Hyphen dashboard. ## Initialization Wrap your application in the `ToggleProvider`: ```tsx import { ToggleProvider } from '@hyphen/react-sdk'; import App from './App'; function Root() { return ( ); } ``` ## Usage Read flags anywhere inside the provider with the `useToggle` hook: ```tsx import { useToggle } from '@hyphen/react-sdk'; function MyComponent() { const toggle = useToggle(); const isNewFeatureEnabled = toggle.getBoolean('new-feature', false); return
{isNewFeatureEnabled && }
; } ``` ## See also - [GitHub: Hyphen/react-sdk](https://github.com/Hyphen/react-sdk) - Prefer [OpenFeature](https://openfeature.dev)? Use the [React provider](../feature-flags/provider-react). ### Python URL: https://hyphen.ai/docs/sdks/python/ Description: Official documentation for the Hyphen Python SDK, covering installation, authentication, initialization, and usage for evaluating feature flags. The **[hyphen](https://github.com/Hyphen/python-sdk)** package is Hyphen's native Python SDK for evaluating [Toggle](https://hyphen.ai/toggle) feature flags in Python applications and services. ## Installation ```shell pip install hyphen ``` ## Authentication The SDK requires an **application id** and an **api key**. See [Get a Project's Public Key](../feature-flags/project-public-key) for where to find these in the Hyphen dashboard. You can pass them directly or provide them via environment variables: ```shell export HYPHEN_API_KEY="your_api_key" export HYPHEN_APPLICATION_ID="your_application_id" ``` ## Initialization ```python from hyphen import FeatureToggle toggle = FeatureToggle( application_id='your_application_id', api_key='your_api_key', ) ``` ## Usage Retrieve a boolean feature flag with a fallback default value: ```python enabled = toggle.get_boolean('my-feature', default=False) print('Feature enabled:', enabled) ``` ## See also - [GitHub: Hyphen/python-sdk](https://github.com/Hyphen/python-sdk) - Prefer [OpenFeature](https://openfeature.dev)? Use the [Python provider](../feature-flags/provider-python). ### Go URL: https://hyphen.ai/docs/sdks/go/ Description: Integrate Hyphen's feature flag service into your Go applications with the official Go SDK. Learn how to install, authenticate, initialize, and use the SDK to manage feature flags. The **[go-sdk](https://github.com/Hyphen/go-sdk)** is Hyphen's native Go SDK for evaluating [Toggle](https://hyphen.ai/toggle) feature flags in Go applications and services. ## Installation ```shell go get github.com/Hyphen/go-sdk ``` ## Authentication The SDK requires a project **public key** (it starts with `public_`) and an **application id**. See [Get a Project's Public Key](../feature-flags/project-public-key) for where to find these in the Hyphen dashboard. These can be provided as options during initialization or via environment variables: ```shell HYPHEN_PUBLIC_API_KEY=public_your_api_key HYPHEN_APPLICATION_ID=your_application_id ``` ## Initialization The SDK uses functional options to configure the client: ```go client, err := hyphen.New( hyphen.WithPublicAPIKey("public_your_api_key"), hyphen.WithApplicationID("your_application_id"), ) if err != nil { log.Fatal(err) } ``` ## Usage Retrieve a boolean feature flag with a default fallback: ```go result := client.Toggle.GetBoolean( context.Background(), "hyphen-sdk-boolean", false, nil, ) fmt.Printf("Boolean toggle value: %v\n", result) ``` ## See also - [GitHub: Hyphen/go-sdk](https://github.com/Hyphen/go-sdk) - Prefer [OpenFeature](https://openfeature.dev)? Use the [Go provider](../feature-flags/provider-go). ### .NET URL: https://hyphen.ai/docs/sdks/dotnet/ Description: Integrate Hyphen's feature flag services into your .NET applications using the native Hyphen.Sdk. The **[Hyphen.Sdk](https://github.com/Hyphen/dotnet-sdk)** is Hyphen's native .NET SDK. It integrates with the standard .NET host builder and dependency injection so you can use Hyphen services — including [Toggle](https://hyphen.ai/toggle) feature flags — across your application. ## Installation ```shell dotnet add package Hyphen.Sdk ``` ## Authentication The SDK authenticates with your project **public key** and **application id**. See [Get a Project's Public Key](../feature-flags/project-public-key) for where to find these in the Hyphen dashboard. ## Initialization Register the Toggle service with the host builder and configure your credentials: ```csharp builder.Services.AddToggle(); builder.Services.Configure(options => { options.ProjectPublicKey = "public_your_public_key"; options.ApplicationId = "your_application_id"; options.Environment = "production"; }); ``` ## Usage Inject the `IToggle` service and evaluate a flag: ```csharp public class MyService { private readonly IToggle _toggle; public MyService(IToggle toggle) { _toggle = toggle; } public async Task IsEnabledAsync() { var result = await _toggle.Evaluate("your-toggle-key"); return result.Value ?? false; // fall back to a default when null } } ``` ## See also - [GitHub: Hyphen/dotnet-sdk](https://github.com/Hyphen/dotnet-sdk) - Prefer [OpenFeature](https://openfeature.dev)? Use the [.NET provider](../feature-flags/provider-dotnet). ### Create a Short Link URL: https://hyphen.ai/docs/url-shortening/create-short-link/ Description: Learn how to create custom short URLs, generate QR codes, and track link performance using Hyphen's URL-shortening service. 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 customized QR codes with your own logo and brand colors for effective marketing and easy link sharing. 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 the metrics available on your short URL analytics dashboard, with insights on how to interpret user engagement data. 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 for using net.info, a service providing cost-effective and scalable IP address to location geo-location services. Learn how to create an API key, make single and bulk lookups, and monitor usage. [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) ## Monitor Usage When your organization has net.info traffic, the Hyphen organization dashboard shows total requests and a daily trend for the last 30 days. Select the card to open the net.info request view. See [Dashboard Overview](/docs/introduction/dashboard#netinfo-usage). # 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 Hyphen integration with AWS, covering prerequisites, stack creation, resource provisioning, 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. ## Object Storage Object Storage connections link to existing S3 buckets in AWS or create a new one if none is provided. Object Storage requires a Cloud Workspace connection for the target project environment. When creating a new bucket, the name is derived from the Hyphen project and environment alternate IDs (e.g. `{projectAlternateId}-{envAlternateId}`). ### Configuration | **Field** | **Type** | **Description** | | ------------ | -------- | ------------------------------------------------------ | | `bucketName` | `string` | S3 bucket name. | | `bucketArn` | `string` | ARN of the S3 bucket. | | `region` | `string` | AWS region where the bucket is located (e.g. `us-east-1`). | | `username` | `string` | IAM user name created for bucket access. | ### Connection Input Provide the S3 bucket name to connect to an existing bucket. ### Access Hyphen creates a dedicated IAM user with a scoped bucket policy and generates access credentials (access key ID and secret) that are injected into the application at runtime. *** ## 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 Hyphen with Microsoft Azure, covering setup, required permissions, OAuth scopes, and connection configurations for various Azure resources. ## 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. *** ## Object Storage Object Storage connections link to existing Blob Storage containers in Azure or create a new one if none is provided. Object Storage requires a Cloud Workspace connection for the target project environment. When creating a new container, both the storage account name and container name are derived from the Hyphen project and environment alternate IDs. ### Configuration | **Field** | **Type** | **Description** | | --------------------- | -------- | ------------------------------------------------------------ | | `storageAccountName` | `string` | Azure Storage Account name. | | `storageAccountId` | `string` | Unique resource ID of the storage account. | | `containerName` | `string` | Blob container name within the storage account. | | `resourceGroupName` | `string` | Resource group containing the storage account. | | `tenantId` | `string` | Azure tenant ID. | ### Connection Input Provide the Blob container name to connect to an existing container. ### Access Hyphen creates a dedicated service principal (Microsoft Entra ID) with a scoped RBAC role assignment on the container and generates a client secret that is injected into the application at runtime. ### Docker Hub URL: https://hyphen.ai/docs/integrations/docker-hub/ Description: A guide on how to set up Docker Hub integration by creating necessary access tokens and configuring the connection. # 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 comprehensive guide to setting up your Google Cloud environment for Hyphen integration, including account creation, organization connection, required permissions, OAuth scopes, and various connection types like Google Workspace, Folders, Projects, and GCS buckets. # 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: * Artifact Registry Administrator (`roles/artifactregistry.admin`) * Billing Account User (`roles/billing.user`) * Cloud Run Admin (`roles/run.admin`) * Compute Network Admin (`roles/compute.networkAdmin`) * Folder Admin (`roles/resourcemanager.folderAdmin`) * Organization Administrator (`roles/resourcemanager.organizationAdmin`) * Project Creator (`roles/resourcemanager.projectCreator`) * Secret Manager Admin (`roles/secretmanager.admin`) * Secret Manager Secret Version Manager (`roles/secretmanager.secretVersionManager`) * Service Account Admin (`roles/iam.serviceAccountAdmin`) * Service Account Key Admin (`roles/iam.serviceAccountKeyAdmin`) * Service Usage Admin (`roles/serviceusage.serviceUsageAdmin`) * Tag Viewer (`roles/resourcemanager.tagViewer`) * Tag User (`roles/resourcemanager.tagUser`) * Compute Load Balancer Admin (`roles/compute.loadBalancerAdmin`) * Cloud Asset Viewer (`roles/cloudasset.viewer`) * Kubernetes Engine Viewer (`roles/container.viewer`) * DNS Administrator (`roles/dns.admin`) * Certificate Manager Owner (`roles/certificatemanager.owner`) * Storage Admin (`roles/storage.admin`) * Logs Viewer (`roles/logging.viewer`) * Monitoring Viewer (`roles/monitoring.viewer`) * Kubernetes Engine Cluster Viewer (`roles/container.clusterViewer`) 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. *** ## Object Storage Object Storage connections link to existing GCS buckets in Google Cloud or create a new one if none is provided. Object Storage requires a Cloud Workspace connection for the target project environment. When creating a new bucket, the name is derived from the Hyphen project and environment alternate IDs (e.g. `{projectAlternateId}-{envAlternateId}`). ### Configuration | **Field** | **Type** | **Description** | | ------------ | -------- | ------------------------------------------------------ | | `bucketName` | `string` | GCS bucket name. | | `bucketPath` | `string` | Full bucket path in `gs://{bucketName}` format. | | `projectId` | `string` | GCP project ID where the bucket resides. | ### Connection Input Provide the GCS bucket name to connect to an existing bucket. ### Access Hyphen creates a dedicated service account with the Storage Admin role scoped to the bucket and generates a service account key (JSON) that is injected into the application at runtime. *** ## Kubernetes Observability Kubernetes Observability connections let Hyphen Agent query Google Cloud Monitoring metrics and Cloud Logging entries for a registered GKE cluster. ### Connection Input Provide the full GKE cluster resource name: ```text projects/PROJECT_ID/locations/LOCATION/clusters/CLUSTER_NAME ``` Hyphen validates that the cluster exists and stores its project, location, and cluster name with the connection. ### Required Access The Hyphen service account needs: - Logs Viewer (`roles/logging.viewer`) - Monitoring Viewer (`roles/monitoring.viewer`) - Kubernetes Engine Cluster Viewer (`roles/container.clusterViewer`) The Google Cloud one-click setup assigns these roles. If the connection reports that the cluster cannot be found, verify the resource name and confirm the roles are present. Hyphen may create the connection automatically when Horizon detects Google Cloud observability, the organization has one Google Cloud integration, and Cloud Asset Inventory can resolve the GKE cluster. Otherwise, connect it from the cluster's **Settings** tab. For complete setup instructions, see [Kubernetes Observability](/docs/kubernetes/observability). [Test](#) [Connect](#) ### Google Workspace URL: https://hyphen.ai/docs/integrations/google-workspace-integration/ Description: A guide on how to set up and configure Google Workspace for integration with Hyphen, including service account authorization and connection management. # 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: A comprehensive guide to setting up and configuring the Hyphen integration with GitHub, covering user, team, repository, and project board connections. # 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 details for various catalog types. # 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 on setting up and configuring Jira integrations, including API token generation, obtaining necessary IDs, and managing various connection types like 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: Guide to setting up and configuring Microsoft Office 365 integration with Hyphen, including required 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 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, detailing required permissions and connection types. # 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 integrating your New Relic account with Hyphen, covering API key generation, configuration, and connection setup for various New Relic features including Kubernetes observability. # 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: - Access and query your data [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: - Resolving the New Relic account connected to Hyphen - Querying the account's entities, metrics, and logs [Go to API Keys UI to generate your key](https://one.newrelic.com/launcher/api-keys-ui.api-keys-launcher) The New Relic user that owns the key must be able to access the account and query the telemetry Hyphen will use. Hyphen does not require user-management, authentication-domain-management, or group-management permissions for observability queries. #### Security Recommendations: - Keep your API keys secure and treat them like passwords - Rotate the User API key according to your organization's credential policy - Remove or rotate keys when the owning user's access changes ### 3. Connect New Relic Account Enter your User API key below to complete the integration. This key will be used to: - Authenticate your account - Resolve the New Relic account available to the key - Query telemetry for connected apps and Kubernetes clusters --- # 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. --- ## Kubernetes Observability Kubernetes Observability connections let Hyphen Agent query New Relic metrics and logs for a registered cluster. ### Before You Connect - Install and configure the New Relic Kubernetes integration for the cluster. - Wait for New Relic to receive its first Kubernetes cluster sample. - Connect the New Relic account that receives the cluster's telemetry to the Hyphen organization. ### Connection Input Provide the cluster name configured when the New Relic Kubernetes integration was installed. Hyphen searches the connected account for a Kubernetes cluster sample with that name. If the cluster sample has not arrived yet, the connection can remain in a retryable error state while New Relic begins ingesting telemetry. An incorrect cluster name produces a not-found error. Hyphen may create the connection automatically when Horizon detects exactly one New Relic cluster name and the organization has exactly one New Relic integration. Otherwise, connect it from the registered cluster's **Settings** tab. For complete setup instructions, see [Kubernetes Observability](/docs/kubernetes/observability). ### NPM URL: https://hyphen.ai/docs/integrations/npm/ Description: A comprehensive guide to setting up and configuring NPM integration, including generating access tokens, managing organizations, and connecting 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: Guide to setting up and configuring Slack integration, including workspace and channel/user connections, authentication, and access requirements. # 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: A comprehensive overview of Hyphen AI's security policies, practices, and governance, covering access management, business continuity, data protection, incident response, and more. 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 ### Clearer Kubernetes Health and Agent Decisions URL: https://hyphen.ai/docs/changelog/2026-08-07-clearer-kubernetes-health-agent-decisions Date: August 7, 2026 Tag: added The new dashboard makes Agent work that needs your attention easier to find, with tasks awaiting decision and recent activity in one place. Project- and cluster-level links open Agent work in context, while Kubernetes fleet health now distinguishes current problems from retained warning history. Clearer Optimizer evidence helps you verify recommendations before approving changes. --- ## Trust Current Fleet Health Without Losing History Cluster health now reflects what is happening in the latest inventory instead of treating every retained Kubernetes warning as a live failure. When a pod recovers, stale container issue data and older warning events no longer leave the cluster marked unhealthy. Hyphen still preserves warning events as diagnostic history, including their occurrence counts and timestamps. This keeps useful evidence available for an investigation while current pod readiness determines whether the fleet needs attention. Historical inventory snapshots continue to show the state captured at that point in time. Regional and zonal GKE clusters also follow the same discovery and connection flow, making registered cluster coverage more consistent. See how Hyphen collects and compares state in [Kubernetes inventory snapshots](/docs/kubernetes/inventory-snapshots). --- ## Move from Resource Context to the Right Agent Work Project and Kubernetes cluster overviews now include a compact **View agent tasks** button. It opens the Agent panel with tasks already filtered to that project environment or cluster, so you can move from deployment or inventory context to the relevant work without rebuilding filters. ![Hyphen cluster inventory showing the View agent tasks button for the Payments cluster](/changelog/kubernetes-cluster-view-agent-tasks.png) Kubernetes inventory controls also stay usable when the Agent panel narrows the diagram. Snapshot navigation remains grouped, view controls adapt to the available width, and secondary filter details move out of the way on smaller canvases. --- ## See Decisions and Evidence More Clearly The organization dashboard now summarizes recent Agent activity and highlights tasks waiting for your input. Direct links open the task inbox or the specific work that needs attention, reducing the time spent searching across chat sessions and task lists. ![Hyphen dashboard showing Optimize payments-api availability and Review stale Kubernetes resources under Tasks awaiting decision](/changelog/agent-dashboard-tasks-awaiting-decision.png) Deployment Optimizer runs now use the same compact scope, evidence, results, and recommendation structure as Kubernetes Optimizer. You can review scanned resources, connected telemetry samples, CPU and memory utilization, request rates, connection status, and collection notes beside the resulting recommendations. When evidence comes from multiple container connections, Hyphen aligns samples by timestamp before summarizing them. ![Agent Chat showing Kubernetes Optimizer evidence, one recommendation pending review, one informational finding, and Approve and Reject controls](/changelog/kubernetes-optimizer-evidence-and-recommendations.png) New chat sessions also receive a concise title from the initial request and its attached resources, making entity-specific conversations easier to recognize later. Read more about review-first changes in [Agent safety and approvals](/docs/agent/safety-and-approvals) and about deployment evidence in [Deployment Optimizer](/docs/agent/optimizer). --- ## Things to Know - **Warning history is not current health.** Retained warning events remain available for diagnosis, while readiness in the latest snapshot determines live fleet status. ### Scheduled Kubernetes Optimization and More Reliable Deployments URL: https://hyphen.ai/docs/changelog/2026-07-31-scheduled-kubernetes-optimization-reliable-deployments Date: July 31, 2026 Tag: added Hyphen now makes Kubernetes optimization easier to automate, understand, and verify with workload-level Optimizer policies, clearer evidence and results, and more resilient deployment networking. Hyphen CLI v0.29.0 also adds safer environment key handling and links that take you directly to the correct deployment run.
--- ## Automate Optimization for Each Workload Teams can now manage Kubernetes Optimizer policies for individual Deployments and StatefulSets. From a cluster's settings, you can: - Run optimization on a recurring schedule that fits each workload. - Disable optimization for workloads that need to stay fixed. - Start an eligible workload analysis immediately with **Optimize now**. - Keep policies visible when a workload is absent from the latest inventory, so stale configuration can be repaired or removed. ![Kubernetes cluster settings with daily, six-hour, and disabled workload optimization policies](/changelog/kubernetes-workload-optimizer-policies.png) This gives platform teams a repeatable right-sizing rhythm without applying the same schedule to every workload in a cluster. Workloads without a policy remain available for on-demand analysis, while a disabled policy prevents both scheduled and manual runs. Hyphen also prevents overlapping Optimizer runs for the same workload and scopes prior recommendations and outcomes to that exact workload. Agent can use the right history without mixing together similarly named resources from different clusters or namespaces. Learn how Agent evaluates workloads and protects scale changes in [Kubernetes Optimizer](/docs/agent/kubernetes-optimizer). --- ## Understand and Verify Every Recommendation Optimizer runs make it easier to see why Agent reached a recommendation and what happened after you acted on it: - CPU, memory, restart, and log evidence from the connected provider is organized around the analysis window, making recent workload behavior easier to review. - Recommendations that Agent cannot safely apply include the rejection reason, so you know what needs attention instead of seeing an unexplained skip. - Live run activity and newly arriving results make progress visible during longer analyses. - After an approved change, Hyphen refreshes cluster inventory and waits for an applied snapshot, helping you verify the updated workload state in the same flow. ![Agent Chat showing payments-api Kubernetes Optimizer evidence, one recommendation pending review, one informational finding, and Approve and Reject controls](/changelog/kubernetes-optimizer-evidence-and-recommendations.png) Horizon discovers the cluster's telemetry source automatically. When Hyphen finds one unambiguous matching provider integration, it can validate the cluster, create the observability connection, and make the data ready for Agent. You do not need to enter a cluster identifier manually. Agent combines the inventory reported by Horizon with workload telemetry from the connected source: - **New Relic** — Kubernetes metrics and logs from the [New Relic Kubernetes integration](/docs/integrations/new-relic#kubernetes-observability). - **AWS** — EKS workload metrics from CloudWatch Container Insights and application logs from CloudWatch Logs. The [AWS integration](/docs/integrations/aws-integration) identifies the cluster by its EKS cluster ARN. - **Azure** — AKS metrics from Azure Monitor managed Prometheus and container logs from `ContainerLogV2`. The [Azure integration](/docs/integrations/azure-integration-setup-guide) identifies the cluster by its AKS resource ID. - **Google Cloud** — GKE metrics from Cloud Monitoring and workload logs from Cloud Logging. The [Google Cloud integration](/docs/integrations/google-cloud-integration#kubernetes-observability) identifies the cluster by its full GKE resource name. If Hyphen cannot determine the source automatically, you can connect it manually. Open the registered cluster's **Settings** tab, find **Observability**, select **Setup connection**, choose the integration receiving that cluster's telemetry, and enter its provider-specific cluster identifier. Learn more about managing the connection in [Kubernetes Observability](/docs/kubernetes/observability), or compare the before-and-after cluster state with [Kubernetes inventory snapshots](/docs/kubernetes/inventory-snapshots). Recommendations still require review and approval before Hyphen changes a workload. --- ## More Resilient Deployments and Provisioning Hyphen now uses a more resilient nfabric provisioning path to create and reconcile deployment networking. Routing configuration carries through to backend endpoints more consistently, and AWS load balancer listener rules, certificates, and path priorities are synchronized more reliably. Preview hostnames also account for their DNS zone, including multi-label apex domains, while custom-domain updates better handle hostname changes and missing region data. Additional cloud provisioning retries give resources such as networks and load balancers time to become ready before a deployment is treated as failed. Together, these changes reduce failed or partially configured deployments and make repeated deploys more likely to converge on the intended routing state across AWS, Azure, and Google Cloud. See how runs started from GitHub, the CLI, the API, or the dashboard fit into the same workflow in [Deployment run methods](/docs/deploy/deployment-run-methods). --- ## Safer CLI Workflows and a Clearer Deployment Trail [Hyphen CLI](/docs/introduction/cli) v0.29.0 is available now. Deployment commands return links that open the exact project environment run, so you can move from terminal output to logs and status without searching in the dashboard. The CLI also creates a new environment encryption key only when Hyphen explicitly reports that no key exists. Authentication failures, temporary service errors, and network failures are surfaced instead of being mistaken for a missing key. This protects the existing key from being orphaned and makes secret pull, push, and deployment workflows more reliable. Deployments started by Agent also link the deployment run back to the Agent run that triggered it. That gives teams a clearer audit trail from the original recommendation and approval through deployment execution. --- ## Things to Know - **Workload policies support Deployments and StatefulSets.** Each workload can have its own schedule or be disabled independently. - **A disabled policy blocks manual and scheduled optimization.** Removing the policy restores on-demand runs for that workload. - **Scale changes still require approval.** Scheduling automates analysis, not permission to change your cluster. - **CLI v0.29.0 is available now.** Run `hx update` to install the latest version. ### Manage Hyphen from Your AI Tools with the Hyphen MCP Server URL: https://hyphen.ai/docs/changelog/2026-07-21-hyphen-mcp-server Date: July 21, 2026 Tag: added Hyphen now speaks [MCP](https://modelcontextprotocol.io). Connect Claude, Cursor, VS Code, or any MCP client to `https://mcp.hyphen.ai/`, sign in, and your assistant can manage your Hyphen organization directly — with the same permissions you have in the app. --- ## What You Can Do - **Deploy from a conversation** — the `deploy_app` workflow analyzes the repo your coding agent has open, sets up the project, app, and Docker packaging, ships preview-first, watches the run and logs, and promotes to production only after you confirm. - **Manage feature flags end to end** — create toggles and segments, adjust targeting, and verify with live edge evaluations. Telemetry-backed tools find stale flags, and a guided cleanup removes them from your code before retiring them in Hyphen. - **Investigate incidents** — search the audit log and correlate it with deployment runs, logs, and metrics to answer "what changed right before things broke?" - **Operate Agent, links, and more** — schedule [Hyphen Agent](/docs/agent/agent-overview) tasks, respond to runs waiting on input, create short links and QR codes, and query live documentation. ## Built-In Safeguards Every tool call runs as you, destructive operations prompt for confirmation in your client, production deployments are gated behind an explicit acknowledgment, and ENV secret values never pass through the server — they stay [end-to-end encrypted](/docs/env-secrets-management/end-to-end-encryption). Get connected in the [MCP docs](/docs/mcp/mcp-overview), or grab the server from the [MCP registry](https://registry.modelcontextprotocol.io) as `ai.hyphen/mcp`. The server is open source at [github.com/Hyphen/mcp](https://github.com/Hyphen/mcp). ### Faster Kubernetes Troubleshooting with Observability URL: https://hyphen.ai/docs/changelog/2026-07-15-kubernetes-observability-inventory-navigation-deploy-reliability Date: July 15, 2026 Tag: added ![Kubernetes observability setup modal connecting New Relic telemetry](/changelog/kubernetes-observability-connection-setup.png) This week's update makes it easier to troubleshoot Kubernetes workloads in Hyphen. Teams can connect runtime observability data like New Relic, jump directly to the resource they are investigating, see clearer warning context, and review more complete deployment run history after a deploy. --- ## Connect Cluster Telemetry to Agent Analysis Kubernetes clusters can now be connected to observability data more directly. For integrations such as [New Relic](/docs/integrations/new-relic), Hyphen now has a clearer setup path for bringing workload telemetry into cluster inventory and Agent analysis. That gives [Kubernetes Optimizer](/docs/agent/kubernetes-optimizer) more runtime context when it reviews a workload: - Metrics and logs can help Agent understand how a workload is behaving in production. - Kubernetes-specific connection fields are easier to configure. - Retryable integration errors are handled more gracefully during setup. - Observability data is normalized before it is used in analysis. When a pod or workload needs attention, Hyphen can connect what is deployed in the cluster with what is happening at runtime, which means less manual context gathering. --- ## See the Cluster Issues and Warnings in Context Kubernetes resource detail panels now show more of the ownership and issue context around a selected resource: ![Kubernetes inventory showing an issue-bearing pod with warning details](/changelog/kubernetes-cluster-issues-warning-context.png) - Deployment, ReplicaSet, and Pod hierarchy is shown in the inventory diagram. - Resource details include creation timestamps and a clearer hierarchy of metadata, labels, and related state. - Label filtering helps narrow large cluster diagrams to the resources that matter for an investigation. - Container startup issues are preserved in inventory and surfaced in the cluster experience. - Warning and issue styling is more consistent across light and dark modes. During debugging, teams can move from a warning or not-ready pod to the owning workload, labels, timestamps, and startup issue context without leaving the cluster view. That cuts down on tab switching and makes it clearer whether a problem is isolated to one pod or connected to a broader workload change. Learn more in [Kubernetes inventory snapshots](/docs/kubernetes/inventory-snapshots). --- ## Get Back to the Exact Resource Inventory diagrams now make it easier to open, share, and return to the exact resource you are investigating: - Kubernetes flow resources can be deep linked and navigated with browser history. - Agent chat references can point to specific Kubernetes inventory objects. - The Kubernetes cluster create flow is available from the global create menu. - Kubernetes management is available without feature-flag setup. This means teammates can share the same view during an incident, Agent can reference the resource it is discussing, and you can move backward and forward through an investigation without rebuilding the diagram state by hand. --- ## More Complete Deployment Run History Deployment run status updates and run-log writes are now handled more reliably when a deployment run is created, updated, or reported back to Hyphen. For customers reviewing what happened after a deploy, this helps preserve run log data during execution and keeps deployment history more complete. The result is a clearer audit trail when a deployment succeeds, fails, or needs follow-up investigation. ### Kubernetes Inventory Controls and Agent Task Filters URL: https://hyphen.ai/docs/changelog/2026-07-08-kubernetes-inventory-agent-task-filters Date: July 8, 2026 Tag: added ![Kubernetes inventory summary rail showing workload and pod readiness status](/changelog/kubernetes-inventory-workloads-rail.png) This week extends the Kubernetes management release with clearer inventory navigation, richer node and workload detail, and easier Agent task filtering. It also includes backend reliability work for deployment networking and policy resolution across target-scoped Agent tasks. --- ## Kubernetes Inventory Review Improvements Kubernetes inventory views now make it easier to understand what changed in a cluster and where attention is needed: - Inventory diffs now highlight replica readiness changes, so teams can quickly see when desired or ready replica counts changed between snapshots. - Diff highlights animate in the inventory diagram, making added, removed, and changed resources easier to spot during review. - Cluster nodes now render as a dedicated top band in the inventory diagram, giving the cluster itself a clearer place in the resource map. - Cluster summary information now calls out exposure and warning signals more directly. - Inventory headers and snapshot labels better communicate the scope of the snapshot being inspected. These updates build on [Kubernetes inventory snapshots](/docs/kubernetes/inventory-snapshots), where teams can compare cluster state over time and inspect the impact of manual or Agent-driven changes. --- ## Better Node, Pod, and Workload Detail Kubernetes detail panels now surface more operational context without forcing teams to jump between views: ![Kubernetes warnings strip centered on a warning-bearing pod](/changelog/kubernetes-inventory-pods-warnings.png) - Node details include warning strips, clearer badging, and a divided warnings list for faster scanning. - Pod summaries show ready and not-ready counts, plus pod-card readiness state. - Workloads can now be reviewed by app, with per-app dropdowns and clearer workload counts across namespaces. - Clicking the Nodes summary item centers the node group in the inventory diagram. - Node details now include a collapsible raw manifest code viewer for teams who need to inspect the underlying Kubernetes resource definition. The inventory controls also wrap more cleanly on constrained screens, and node card text no longer clips during hover states. --- ## Agent Task Filtering and Policy Reliability Agent task views now support task type filters. This makes it easier to narrow Agent work to specific task categories such as Kubernetes cleanup, Optimizer, or Log Analysis. Target-scoped Agent task policies also resolve environment type more reliably. That keeps policy behavior aligned with the selected project environment when a task is scoped to a specific deployment target. --- ## Deploy Networking Reliability Hyphen moves more deployment networking orchestration onto its newer provisioning layer, including SSL, backend pools, and load balancer creation. This continues the infrastructure reliability work behind Deploy so cloud networking resources can be created, adopted, and reconciled more consistently across environments. This release also includes an AWS artifact registry secret fix and improved Agent tool selection on the backend, reducing ambiguity when Agent decides which tool should handle a request. ### Kubernetes Management for Registered Clusters URL: https://hyphen.ai/docs/changelog/2026-06-30-kubernetes-management Date: June 30, 2026 Tag: added ![Optimizer run showing an approved payments-api scale recommendation and successful result](/changelog/kubernetes-management-optimizer-run.png) Hyphen now gives teams a complete Kubernetes management loop: register clusters with your organization by installing Horizon, inspect inventory changes over time, prompt Agent for workload optimization recommendations, approve scale changes, and safely review automated or manually initiated cleanup of stale resources. This release brings Kubernetes into Hyphen as a top-level experience, connecting cluster registration, inventory snapshots, workload optimization, cleanup policies, Agent run review, and activity timelines into one operational workflow. --- ## Register and Manage Kubernetes Clusters Kubernetes is now a top-level area in Hyphen. From the cluster list, you can register clusters in private clouds, AWS, Google Cloud, and Azure. ![Kubernetes cluster list showing connected clusters by provider and status](/changelog/kubernetes-management-clusters.png) Registering a cluster uses a generated `kubectl apply` command that installs Horizon in the `hyphen-horizon` namespace. The command includes an API key that allows Horizon to connect the cluster and report inventory back to your Hyphen organization. Learn more: - [Kubernetes Overview](/docs/kubernetes/overview) - [Add a Kubernetes Cluster](/docs/kubernetes/add-cluster) - [Remove a Cluster](/docs/kubernetes/remove-cluster) --- ## Inspect Inventory Changes Over Time Cluster details now include a dedicated inventory view with refresh controls, snapshot history, previous and next navigation, and diffs that highlight added, removed, and changed resources between snapshots. The inventory graph includes namespace filtering, resource details, minimap navigation, and direct links to loaded snapshots. With **Diff with Previous** enabled, the Kubernetes cluster flow diagram also helps teams review the impact of Agent or manual work over time. Cluster changes show up in the graph as highlighted workload, resource, or removal changes between snapshots. When replica readiness or desired replicas change, Hyphen highlights the affected workload and shows the previous and current values so teams can quickly understand what changed. ![Inventory diff showing a scaled workload alongside added and removed Kubernetes resources](/changelog/kubernetes-management-inventory-diff.png) Learn more in [Inventory Snapshots](/docs/kubernetes/inventory-snapshots). --- ## Review Workload Scaling Recommendations Teams can now prompt Hyphen Agent to run Kubernetes Optimizer for a registered cluster workload. When asked, Agent uses the latest Kubernetes inventory to review the workload state and suggest replica changes that better match expected demand. Optimizer task and run views now show the Kubernetes cluster and workload in context, including recommendations, analysis notes, approval status, and scale outcomes such as succeeded, skipped, or failed changes. Applied Kubernetes scale changes also appear in Agent run summaries alongside other approved recommendations. Optimizer is user-initiated and scale recommendations require explicit approval before anything changes. Before applying an approved recommendation, Hyphen rechecks the workload against the replica count that was reviewed. If the workload changed, cannot be found, or appears to be managed by autoscaling, Agent skips the change and reports why. After an approved scale change, Hyphen waits for the rollout and refreshes inventory so teams can verify the updated cluster state. Learn more in [Kubernetes Optimizer](/docs/agent/kubernetes-optimizer). --- ## Cleanup Policies and Agent Review This gives teams the same review-before-action workflow for cleanup that Optimizer uses for workload scaling recommendations: scan, review candidates, approve the action, apply the change, and review the result. Kubernetes resource cleanup is automated by default through the organization cleanup policy. Admins can adjust the schedule, set the stale-resource threshold, and maintain ignored namespaces or resource UIDs. Clusters inherit the organization policy by default, but teams can use a cluster-level override when a specific cluster needs a different review rhythm. For example, one cluster can scan weekly with a longer stale-resource threshold and its own ignored namespaces or UIDs while the rest of the organization keeps the default policy. ![Cluster settings showing a cleanup policy override for a specific Kubernetes cluster](/changelog/kubernetes-management-cleanup-policy-override.png) Hyphen Agent runs cleanup scans automatically from policy and can also start a manual cleanup scan when requested. Agent collects inventory, identifies stale or unused resources, and asks for an explicit decision before deleting anything. New run views show cleanup candidates, approval requests, decisions, and a results summary for each scan. ![Cleanup review showing Kubernetes candidates, decisions, and scan results before action is taken](/changelog/kubernetes-management-cleanup-review.png) Learn more: - [Cleanup Policies](/docs/kubernetes/cleanup-policies) - [Kubernetes Resource Cleanup](/docs/agent/kubernetes-resource-cleanup) --- ## Other Platform Improvements This release also includes broader platform polish outside Kubernetes: - Custom domain and deployment networking provisioning is more consistent across AWS, Azure, Google Cloud, and Cloudflare, including DNS zones, records, and backend endpoints. - Agent task views have clearer scheduled and recurring task cards, plus shared summary metrics for run results such as Log Analysis. - Chat message copy actions now copy trimmed message text more reliably, and object storage connection descriptions are clearer during deployment setup. --- ## Things to Know - Horizon must be installed and connected before Hyphen can show inventory, recommend workload scaling changes, or run Kubernetes cleanup scans. - Kubernetes cleanup scans run automatically from the organization policy by default and can also be started manually. Scans are read-only until an explicit cleanup decision is approved. - Kubernetes Optimizer runs start when a user prompts Agent for a workload recommendation. Recommendations require explicit approval and are rechecked before Hyphen applies a scale change. - Cluster cleanup policy overrides apply only to the selected cluster. Removing an override returns the cluster to the organization policy. - Removing a cluster stops Hyphen from managing that cluster, but it does not delete your application workloads. ### Organization Agent Task Policies for Log Analysis and Optimizer URL: https://hyphen.ai/docs/changelog/2026-06-17-agent-task-policies-optimizer-overrides-and-deploy-ux Date: June 17, 2026 Tag: added Hyphen organization policies can now control two additional recurring [Agent tasks](/docs/agent/agent-overview): [Log Analysis](/docs/agent/log-analysis) and [Optimizer](/docs/agent/optimizer). These new policy controls sit alongside [stale feature flag cleanup](/docs/agent/stale-feature-flag-cleanup), giving teams a more complete organization-level way to decide which recurring Agent work runs automatically and where it should apply.
--- ## Organization-Level Agent Task Policies Organization policies now cover three recurring Agent task categories: - [Stale feature flag cleanup](/docs/agent/stale-feature-flag-cleanup) - [Log Analysis](/docs/agent/log-analysis) - [Optimizer](/docs/agent/optimizer) This gives teams one organization-level place to define the default behavior for recurring Agent work, while still allowing lower-level policy refinement for specific projects, environments, or deployment targets that need different handling. Policies can be set to `manual only` or scheduled to run on recurring intervals such as daily, weekly, monthly, or quarterly, depending on the task. ![Screenshot of the Hyphen App showing project settings](/changelog/project-agent-policies.png) Agent policies can be set at the project environment level --- ## New: Log Analysis Policy Controls Log Analysis tasks let [Hyphen Agent](/docs/agent/capabilities) inspect deployment logs or connected APM data, identify likely issues, summarize what is going wrong, and connect findings to follow-up work. For teams, that means less time manually digging through raw operational data and a faster path from incident symptoms to a concrete explanation and next step. With organization-level policy controls, Log Analysis can now be managed as recurring operational work instead of only as an ad hoc task. By default, Log Analysis recurring policies follow this production-first baseline: | Environment type | Default setting | | ---------------- | --------------- | | `production` | Enabled | | `development` | Disabled | | `custom` | Disabled | --- ## New: Optimizer Policy Controls Optimizer tasks let [Hyphen Agent](/docs/agent/capabilities) analyze runtime signals and current deployment settings, then recommend configuration changes such as resource sizing or scale adjustments for a project environment. That gives customers a more practical way to reduce waste, improve reliability, and keep deployment settings aligned with how an environment is actually being used. This release also adds more flexible environment-layer overrides, so teams can tune recurring optimization behavior closer to each environment they manage while still starting from an organization-level policy baseline. By default, Optimizer recurring policies follow this production-first baseline: | Environment type | Default setting | | ---------------- | --------------- | | `production` | Enabled | | `development` | Disabled | | `custom` | Disabled | This gives teams a sensible production-first baseline while still allowing lower-level overrides when a non-production environment needs recurring optimization work. --- ## Deployment and App UX Follow-Ups This release also ships several reliability and navigation improvements across deploy and app surfaces: - Deployment run detail links now route through [project environments](/docs/introduction/project), which keeps deployment investigation aligned with the environment that owns the run. - Deployment and dashboard date handling is more stable, especially for queued states and relative time displays. - Clipboard failures now surface as actual errors instead of always reporting a successful copy. - Team access, link stats, toggle targets, charts, and related app views have more stable rendering behavior. --- ## Things to Know - [Log Analysis](/docs/agent/log-analysis) recurring behavior still follows the effective Agent task policy for the relevant deployment target. - [Optimizer](/docs/agent/optimizer) recommendations remain scoped to a project environment and still require approval for scale-related changes. - Deployment investigation now flows more consistently through [project environments](/docs/introduction/project) views instead of splitting navigation across separate surfaces. ### Object Storage, Agent Deployments, and Policy Automation URL: https://hyphen.ai/docs/changelog/2026-06-08-object-storage-agent-deployments-policy-automation Date: June 8, 2026 Tag: added Deployments now support object storage across cloud providers, Hyphen Agent can inspect and run project environment deployments from chat, and organizations can control stale feature flag cleanup with recurring Agent task policies.
--- ## Object Storage for Deployments You can now add [object storage](/docs/deploy/storage) to the [deployment settings](/docs/deploy/deploy-quickstart) of your project environments. During deployment setup, choose an object storage provider, optionally provide an existing bucket or container name, and Hyphen will include object storage as part of the deployment resource model.
Easily switch providers by modifying the project environment deployment settings Object storage support includes: - **AWS, Azure, and Google Cloud targets** - Configure object storage against connected [AWS](/docs/integrations/aws-integration), [Azure](/docs/integrations/azure-integration-setup-guide), or [Google Cloud](/docs/integrations/google-cloud-integration) integrations. - **Easy provider switching** - Change the object storage provider or bucket in deployment settings, and Hyphen will queue the new storage target on the next deployment. - **Optional bucket naming** - Use an existing bucket or container name, or let Hyphen derive one from the project and environment. - **Deployment resource visibility** - Object storage now appears in the project environment resource diagram alongside apps, targets, and ingress resources. - **Automatic credential injection** - When object storage is configured for a deployment, Hyphen creates the necessary cloud resources and injects credentials into your application, with no manual bucket creation or credential management required. - **Automatic cleanup** - Buckets and storage resources that are no longer used by deployment settings are marked for cleanup automatically. - **Drift detection** - Deployment settings drift alerts now include object storage differences between current settings and the latest deployment run. Learn more in the [Object Storage in Deploy documentation](/docs/deploy/storage). --- ## Agent Deployment Controls
Tell Hyphen Agent to deploy your project environment from Slack [Hyphen Agent](/docs/agent/capabilities) can now answer deployment readiness questions and help run deployments from chat. Ask what is configured for a project environment, whether it is ready to deploy, which apps and cloud targets are included, or what the latest non-preview run looked like. You can also ask the agent to run a configured deployment. The agent checks readiness first, prepares the deployment or [preview deployment](/docs/deploy/deployment-previews), and asks for [confirmation](/docs/agent/safety-and-approvals) before creating the [deployment run](/docs/deploy/deployment-run-methods). If you do not specify builds, Hyphen defaults to the latest build for normal deployments and the latest preview build for preview deployments. Follow-up deployment requests now preserve the prior deployment target, including preview deployments, so requests like "deploy again" can use the last confirmed context without restating the project and environment. --- ## Stale Feature Flag Cleanup Policies
Set your organization's stale feature flag policy from the organization settings [Stale feature flag cleanup](/docs/agent/capabilities) is now managed through organization Agent task policies. Admins can enable or disable the cleanup policy and choose how often it runs: - Manual only - Every day - Every week - Every month - Every quarter Teams can still manually ask Hyphen Agent to clean up stale feature flags at any time, including when the organization policy is set to manual only. Hyphen distributes scheduled run times across the hour so recurring cleanup work does not pile up at the same minute for every organization. --- ## Deployment UX Improvements - **Live deployment run updates** - Deployment run socket events now refresh project environment deployment views as runs change. - **Queued run display** - Queued deployment runs now show `queued...` instead of rendering an invalid date before the run has a start time. - **Object storage form polish** - Object storage provider dropdowns and deployment-resource flows now handle changing target selections more reliably. --- ## Things to Know - **Agent-run deployments still require confirmation.** The agent will not create a deployment run until the [confirmation step](/docs/agent/safety-and-approvals) is approved. - **Readiness blockers still apply.** If the configured deployment is missing required settings or cloud resources, the agent reports the blockers instead of starting the run. - **Object storage requires a connected cloud provider.** The deployment form only enables object storage when a compatible cloud integration is available for the environment. - **Provider changes are handled as deployment changes.** Switching object storage providers takes effect through the next deployment run, and the old storage target is cleaned up when it is no longer used. - **Policy controls require policy permissions.** Users without policy management access can view the current stale feature flag cleanup policy but cannot change it. Create feature flags from the [Toggle quickstart](/docs/feature-flags/toggle-quickstart) before using stale feature flag cleanup policies. --- ## Under the Hood - **nfabric orchestration** is the provisioning layer Hyphen uses to create, adopt, and ensure resources across cloud providers. This release wires object storage provisioning through nfabric-backed connection workflows. - **Object storage credentials** are packaged into a Hyphen-managed `HYPHEN_OBJECT_STORAGE_CONFIG` environment variable for deployed cloud-native containers. - **Unused storage cleanup** is scheduled through the deployment cleanup step when storage settings archive a bucket or provider target. - **Deployment Agent tools** now read project environment deployment settings and prepare confirmed deployment runs through managed chat input requests. - **Agent task policies** reconcile recurring stale feature flag cleanup schedules through Temporal. ### Agent Answers, Remembers, and Works in Slack URL: https://hyphen.ai/docs/changelog/2026-06-03-agent-activity-answers-rich-chat-context Date: June 3, 2026 Tag: added Hyphen Agent can now answer organization activity questions directly from chat, remember durable member preferences, and show up in Slack with the same organization chat functionality available in the Hyphen App. Ask what happened to a project, who created a resource, what an actor changed, or what recent deployment activity looks like, and the agent will search Hyphen events and return a grounded answer with linked resources.
--- ## Agent Chat in Slack ![Hyphen Bot in Slack](/changelog/slack-hyphen-bot.png) The Hyphen Slack bot now connects Slack conversations to the same organization chat sessions used by the Hyphen App. You can DM the bot or mention it in a channel thread, and Hyphen Agent will respond as the resolved Hyphen member with the same chat tools and context handling available in the app. Slack Agent chat supports: - **DMs and app mentions** - Direct messages reply in Slack DMs, while channel mentions reply in-thread. - **Session continuity** - Slack threads reuse the same Hyphen chat session, and daily DM sessions can carry over recent conversation context from the previous day. - **Hyphen links and Slack mentions** - Agent responses keep structured Hyphen entity links, render them as Slack links, and round-trip member references back into Slack mentions when possible. - **Input requests** - Agent confirmations, options, free-text prompts, and options-with-text requests render as Slack buttons or modals, so sensitive actions can still ask for approval without leaving Slack. ![Session continuity from a conversation in Slack](/changelog/session-continuity.png) --- ## Activity Answers in Chat The agent now supports event-backed activity questions across projects, apps, environments, deployments, teams, members, feature flags, segments, links, domains, ENV, and Agent tasks. ![Summary of recent activity for a project environment](/changelog/agent-summarize-recent-activity.png) You can now ask: - **List activity** - "What happened in this project today?" - **Count events** - "How many deployments failed this week?" - **Find the latest event** - "What was the last change to this app?" - **Find who created something** - "Who created this environment?" - **Review actor activity** - "What has Jordan changed recently?" - **Summarize activity** - "Summarize the last 24 hours of production events." The agent uses attached chat context first, so questions asked from a project, app, or environment view are automatically scoped to the work already on screen. If a name matches multiple resources, the agent asks for clarification instead of guessing. --- ## Member Memory Organization chat sessions now support member memory. When you explicitly ask Hyphen Agent to remember, forget, or update a durable preference or fact, it can save that memory to your member profile and reuse it when it is relevant to a future organization chat. For example, you can ask the agent to remember that you prefer concise deployment summaries, that your production environment is usually the one you care about, or that you want follow-up answers in a particular format. The agent can also read the current memory back or clear it when you ask. Member memory is treated as contextual data, not as an instruction source, so it cannot override system rules, tool rules, or higher-priority behavior. --- ## Preview Deployment and Resource Context Deployment event answers are now preview-aware. The agent can distinguish between preview deployments and regular deployment runs, and the app now labels preview deployment runs directly in event output. Agent answers also render resource references as live links, including projects, apps, environments, deployment runs, preview deployments, teams, members, links, domains, feature flags, segments, and Agent tasks. Dates and times now render as structured chat content too, making event answers easier to scan and reuse in follow-up questions. --- ## Chat UX Improvements - **Copy user prompts** - User chat bubbles now include copy-to-clipboard support, so prompts can be reused without selecting text manually. --- ## Things to Know - **Activity answers are based on recorded Hyphen events.** The agent can only answer from events available to your organization and permissions. - **Ambiguous resource names require selection.** When a selector matches more than one project, app, environment, or other resource, the agent will ask you to choose the intended target. - **Preview deployment wording matters.** You can ask for preview-only activity, regular deployment activity, or all deployment events depending on the scope you need. - **Member memory is explicit.** The agent only updates durable member memory when you ask it to remember, forget, or change something. - **Do not store secrets in memory.** Member memory is for preferences and durable working context, not credentials, tokens, private keys, or sensitive personal data. - **Slack requires an installed workspace mapping.** If Hyphen cannot resolve the Slack user or workspace, the bot returns a blocker message instead of starting an Agent chat. - **Slack input requests are scoped to the requester.** Only the Slack user who started the Agent turn can answer that turn's buttons or modal prompts. ### Agent Log Analysis Pull Requests and Project/Link Tools URL: https://hyphen.ai/docs/changelog/2026-05-26-agent-github-automation-and-link-qr-tools Date: May 26, 2026 Tag: added ![Hyphen Agent can automatically open a pull request for issues it finds from Log Analysis](/changelog/agent-github-automation.png) Hyphen Agent can now turn Log Analysis findings into code review. After Agent analyzes deployment logs and identifies an underlying issue, it can use a connected GitHub repository to open a pull request with a proposed fix. This release also adds project, short link, and QR code tools, safer structured action prompts, and live link updates in Hyphen. --- ## Pull Requests from Log Analysis Log Analysis no longer stops at surfacing findings. When Hyphen Agent finds an actionable issue in deployment logs, it can connect that finding to the relevant GitHub repository and open a pull request to fix the underlying cause. Results appear in Agent task and run views with: - The Log Analysis context that led to the proposed fix - The repository and base branch Agent used - Completed workflow steps with timing - Pull request cards with open, closed, and merged states - Links back to the repository, issue, and pull request --- ## Project, Link, and QR Tools You can now ask Hyphen Agent to work with projects, short links, and QR codes directly from chat. - **List projects** — Show the projects in your organization or find the right project for follow-up work. - **Create projects** — Create a new project after collecting the required details and confirmation. - **Read short links** — Find or describe an existing short link. - **Create short links** — Create a short link after collecting the required details and confirmation. - **Delete short links** — Delete a short link after confirmation. - **Work with QR codes** — Help with QR code creation, deletion, or retrieval for existing short links. Short link and QR code changes emit live events, so the app reflects updates without requiring a manual refresh. Project references in Agent messages also link back to the right place in Hyphen. --- ## Safer Agent Decisions and Navigation Agent actions that need approval or more information now use structured input requests. Instead of replying in freeform chat, you can approve, reject, choose an option, or provide a specific text response in a focused prompt. Agent messages also include better links back into Hyphen. Project references can now take you directly to project access settings, and deleted teams or short links show clearer alerts when you land on a resource that no longer exists. --- ## Things to Know - **Log Analysis pull requests require GitHub.** The affected app needs a connected GitHub repository before Agent can open a pull request. - **Agent opens reviewable changes.** Fixes are proposed as pull requests, not applied directly to production code. - **Project creation requires project permissions.** Agent follows the same organization access rules as the rest of Hyphen. - **Short link actions require a configured domain.** You need the right organization permissions and a configured link domain. - **Mutations still require confirmation.** Agent will not create, delete, or change resources without a confirmation step. - **Live updates require an active event connection.** If the app loses its connection, refresh to pull the latest link or QR code state. --- ## Under the Hood - **Log Analysis-to-PR context** carries finding details into the GitHub automation run so reviewers can follow the path from detected issue to proposed fix. - **Structured input requests** now power Agent confirmations and targeted follow-up questions. - **Project tools** let Agent list existing projects and create new ones from chat. - **Link and QR lifecycle events** keep short link state current in the app. - **Project access links** now support direct navigation to project settings. ### Team Management via Chat and Smarter Agent Navigation URL: https://hyphen.ai/docs/changelog/team-management-via-chat-smarter-agent-navigation Date: May 13, 2026 Tag: improved You can now manage your organization's teams directly from the Hyphen chat interface, with real-time updates reflected everywhere instantly. Agent messages also now contain live links to every entity they reference, so navigating from chat to the work the agent created is easy. --- ## Team Management via Chat
You can now manage your organization's teams entirely from the Hyphen chat interface. The agent supports: - **Add a member** — "Add Nathan to the support team." The agent resolves the member and team, presents a confirmation step, and executes on approval. - **Remove a member** — "Remove Kyle from the infra team." Same confirmation flow, same instant feedback. - **Create a team** — "Create the design team" or "Create the design team and add Jordan." Requires confirmation before creating. - **Delete a team** — "Delete the support team." Case-sensitive name matching with confirmation before any data is mutated. - **Team Info** - "Tell me about the Support team." The agent will tell you how many members the team has, and what they have been given explicit access to. Team changes emit real-time socket events so membership is reflected in the UI immediately after the agent acts. --- ## Chat Navigation Improvements **Task and run cards** — When the agent creates a task in chat, it now renders as a card with links to both the task detail page and the latest run directly. Previously you had to navigate to the task first, then select the run. **Log analysis summaries in the task list** — The agent thread list now shows a compact issue-action summary for each log analysis run inline — for example `3 created, 1 commented, 1 skipped` — so you can see outcomes without opening the run. **Log analysis warning display** — Warnings from log analysis are now styled distinctly and grouped in their own section, separated from critical findings. --- ## Things to Know - **Team management only works for static teams.** Dynamic teams do not support direct membership changes via chat. - **All team mutations require confirmation.** The agent will never create, delete, or modify team membership without presenting a confirmation step first. --- ## Under the Hood - **AWS Load Balancer listener rules** now support multiple hostname and path patterns per rule, enabling more complex routing configurations. ### Log Analysis, App Detail Overhaul, and New Relic Integration URL: https://hyphen.ai/docs/changelog/log-analysis-app-detail-overhaul-new-relic Date: May 4, 2026 Tag: added ![Animated preview of log analysis, app detail updates, and New Relic integration in the Hyphen App](/changelog/agent-log-analysis.gif) Hyphen Agent can now analyze deployment logs or New Relic APM, surface issues, and link findings directly to GitHub. App detail pages have been rebuilt around environment and preview context. --- ## Agent Log Analysis and New Relic APM Connection ![Log Analysis Agent Task in the Hyphen App](/changelog/log-analysis-agent-task.png) Hyphen Agent now supports a log analysis task type. By default, Hyphen Agent analyzes your cloud provider’s container logs. If the app is connected to New Relic APM, it uses APM data instead. Hyphen Agent scans for anomalies and surfaces findings by severity. Each finding is linked to a GitHub issue by creating a new issue or commenting on an existing one when a match is found. Results appear in the run conversation view with: - Coverage metrics showing how much of the log was analyzed - Collapsible findings grouped by category - An issue action summary showing how many issues were created, commented on, or skipped Two modes are supported for New Relic APM Connections: - **Shared by environment attribute** — one New Relic APM app with an environment attribute filter to separate environments - **Per environment** — a distinct New Relic APM app name for each Hyphen project environment --- ## App Detail Overhaul The app detail experience has been rebuilt from the ground up to be environment- and preview-aware throughout. ![Animated preview the of the App detaiol UX overhaul](/changelog/app-detail-overhaul.gif) **App overview** - A page-level environment and preview selector drives all app detail views, including deployment state, resources, and instance details - The deployment resource diagram is embedded in the app overview with the current app's subtree persistently highlighted - Instance-level build traceability now shows deployed location, min/max instance counts, status, URL, commit SHA, and tag inline **App secrets** - A new `/secrets` tab consolidates ENV secrets, firewall rules, and access map in one place - The previous app events tab has been removed - The firewall grid now includes `Secrets`, `Version`, and `Size` columns alongside ENV summary data - Restricted users only see placeholders instead of secret values, preserving read permissions --- ## Smarter Chat Context When you open a new chat session from an app detail page, Hyphen now automatically attaches the current Project, App, and Environment as separate removable context badges. The agent uses these to scope its answers and actions without you having to describe where you are. If the selected environment in the URL is stale, it falls back to the default environment automatically. --- ## Things to Know - **Log analysis uses available data sources.** The Agent analyzes container logs by default and uses New Relic APM when connected. - **Issue creation during log analysis is additive.** The agent will not close or modify the body of existing issues, only comment on them when it finds a match. - **The app events tab is gone.** That content has been removed; secrets and firewall rules are now located under `/secrets`. - **Chat context badges are removable.** If you don't want the agent scoped to the current environment or app, you can remove any badge before sending. - **Project Access** settings have moved under the Project Settings tab with a redirect from the old URL May the force be with you! ### Deployment Drift Alerts and Smarter Optimizer Controls URL: https://hyphen.ai/docs/changelog/deployment-drift-warning-smarter-optimizer-controls Date: April 27, 2026 Tag: improved Hyphen now tells you when your deployment settings have drifted from what's actually running, before you waste a run. The optimizer also gets smarter guardrails: it can now recommend scaling above your SLA floor and adjust your instance bucket, while still protecting you from going below it. --- ## Deployment Settings Drift Detection
When you or one of your teammates changes your deployment configuration after the last deployment run, Hyphen now surfaces a drift alert directly on the project overview, above the resource diagram for the selected environment. The alert shows exactly which apps changed and exactly what changed, the value from the last run snapshot alongside your current setting for every editable dimension: targets, availability, scale, traffic regions, hostname, domain, and path. A link to the latest scoped run is included so you can review or re-run immediately. If everything is already in sync, the alert stays out of your way. --- ## Optimizer: Scale Above Your SLA Floor The Agent optimizer tool can now recommend scaling your traffic regions above your SLA floor and adjust your instance bucket when the data warrants it. Previously the optimizer was bound to your original SLA envelope. Now it has a single source of truth for min/max region bounds and instance bucket constraints. The optimizer still cannot go _below_ your SLA floor — that boundary is enforced in the tool layer and cannot be overridden. Any recommendation that touches `scale` is automatically flagged for your approval before anything changes. --- ## AWS Integration Without SSO Connecting an AWS account no longer requires SSO to be configured. The integration flow now accepts non-SSO credentials and handles misconfigurations with clear, specific error messages rather than generic failures. --- ## Things to Know - **Drift alerts are informational.** Seeing a drift alert doesn't mean something is broken — it means your current settings differ from the last run snapshot. You decide whether to re-run the optimizer or leave the configuration as-is. - **Availability is user-owned.** The optimizer cannot change your SLA availability tier. That boundary remains exclusively yours to set. - **Scaling above the SLA floor requires your approval.** Any optimizer recommendation that touches `scale` is automatically held for review before anything is applied. It will never self-approve. - **Existing SSO-based AWS connections are unaffected.** Removing the SSO requirement only changes what's needed to create a new connection — existing integrations continue to work as before. ### Smarter Optimization Recommendations and Build Traceability URL: https://hyphen.ai/docs/changelog/smarter-optimization-and-build-traceability Date: April 21, 2026 Tag: added
Hyphen now delivers more accurate optimization guidance by incorporating additional deployment context before recommending infrastructure changes. Agent's Optimizer skill now considers current deployment settings, recent deployment activity, and recent optimizer outcomes so recommendations better reflect how an environment is actually configured and what the system has already attempted. This release also improves build traceability by attaching commit and tag metadata to build records and generating links back to your source control provider when available. Now you can trace commits and tags from deployed instances in your project environment resource diagrams. --- ### What’s new - Optimizer recommendations now: - Account for current deployment settings - Consider the most recent successful deployment run - Incorporate recent optimizer run history - Added support for collecting deployment logs from New Relic if configured, alongside cloud provider log sources when performing analysis - Recommendation generation now uses versioned analysis prompts for improved consistency and auditability - View deployed app's build metadata by clicking on an instance node in a project environment's resource diagram - Build records now include: - Commit SHA metadata when available - Tag metadata when available - Source links to commits and tags in GitHub, GitLab, Bitbucket, and Azure DevOps when available
--- ### How it works The Optimizer continues to evaluate workload behavior such as CPU, memory, and traffic signals, but now includes additional deployment context before generating recommendations. That context includes: - Current deployment settings - Recent deployment activity - Recent optimizer actions for the environment This helps prevent recommendations that conflict with intended configuration or repeat recent changes (flapping). Build records now store richer source control metadata so you can trace deployments back to the exact revision or release tag that produced them, with direct links to commits and tags in GitHub, GitLab, Bitbucket, and Azure DevOps when available. --- ### Why this matters Optimization recommendations are more useful when they reflect how an environment is configured and what has already changed. - Reduce unnecessary or repeated recommendations - Align optimization decisions more closely with deployment intent - Improve confidence in automated and approval-based optimization flows - Make builds easier to trace back to source control history --- ### Things to know - These improvements enhance the existing project environment optimization workflow - Recent optimizer history is now part of recommendation context, but will not be retroactively generated for previous deployment runs - Analysis prompt versions are tracked for consistency and auditability - Commit and tag metadata appear on builds when source information is available - Links are generated automatically for GitHub, GitLab, Bitbucket, and Azure DevOps repositories when detected ### Chat Sessions, Smarter Optimization, and Deployment Controls URL: https://hyphen.ai/docs/changelog/chat-sessions Date: April 15, 2026 Tag: added You can now keep ongoing conversations with the **Hyphen Agent** in dedicated chat sessions, give the Optimizer more application context from connected GitHub repositories, and fine tune deployments with more granular container resource controls. This release also adds support for selecting the **latest preview build** when triggering preview deployment runs. --- ### What’s new - Start and continue chat sessions with the Agent - View session history with titles, message previews, statuses, and attached references - Close chat sessions when work is complete - Let the Agent create tasks from a chat and attach created references back to the session - Use connected GitHub repositories to provide additional application context for Optimizer analysis - Detect likely language, framework, build system, and workload type for deployed apps - Trigger preview deployment runs using the **latest preview build** option --- ### How it works Chat sessions create a persistent conversation thread that stores message history, references, and created entities. Sessions are scoped to the requesting member, but any tasks created by the Agent during a session are visible to all members of the organization. When the Optimizer runs, Hyphen inspects connected GitHub repositories for the apps in a deployment and builds a lightweight application profile from repository manifests and directory structure. That profile is used alongside deployment metrics and recent activity to improve recommendation quality. Advanced deployment scaling now supports provider-aware CPU and memory overrides at the container level. For preview runs, selecting **latest preview** automatically resolves the newest preview build for the targeted app. --- ### Why this matters Agent conversations are easier to continue and easier to turn into tracked work. Optimization recommendations become more context aware, and container sizing can be tuned more precisely for performance and cost. - Keep ongoing Agent work organized in a single session - Share resulting Agent-created tasks across the organization - Improve optimization recommendations with repository context - Tune container resources more precisely - Deploy the newest preview artifact without manually selecting a build --- ### Things to know - Chat sessions are scoped to the requesting member within the organization - Tasks created from chat sessions are visible to all organization members - Optimizer repository profiling requires a connected GitHub repository for the app - Repository signals support recommendation quality but do not independently trigger changes - AWS advanced overrides currently support CPU and memory but not per-region min/max instance counts - The **latest preview build** option applies to preview deployment runs and requires a matching preview context ### 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