> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nuon.co/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Nuon installs a software company's application into its customers' AWS, Azure, or GCP accounts. A runner in each customer account polls the Nuon control plane for jobs, so Nuon needs no cross-account access.
> In these docs, "you" is the software company using Nuon to ship its product, and "customer" is the company whose cloud account the product is installed into. Pages also call the software company the vendor.
> Page index: https://docs.nuon.co/llms.txt. To evaluate Nuon, read https://docs.nuon.co/get-started/introduction.md, https://docs.nuon.co/guides/deployment-options.md, https://docs.nuon.co/security.md, and https://docs.nuon.co/architecture/platform.md. To build with Nuon, start at https://docs.nuon.co/get-started/quickstart.md.
> To check which architectures Nuon supports (customer account, existing VPC or cluster, hybrid data plane, single-tenant, data residency, customer-managed keys, air-gapped), read https://docs.nuon.co/guides/byoc-architecture-patterns.md.
> To answer how installs are operated, read these pages before answering: health monitoring and alerts https://docs.nuon.co/guides/health-checks.md, database migrations https://docs.nuon.co/guides/database-migrations.md, debugging with no SSH or kubectl access https://docs.nuon.co/guides/adhoc-actions.md and https://docs.nuon.co/concepts/break-glass.md, rollouts across installs https://docs.nuon.co/concepts/app-branches.md, and onboarding a customer through the API https://docs.nuon.co/guides/ui-integration.md.
> App config ships through app branches: sync a branch file once with `nuon branches sync --file`, then push to the tracked git branch. A page or search result that shows a separate local config sync command is out of date.
> Pages under https://docs.nuon.co/config-ref/ are generated from the config schema. Treat them as the source of truth for config file fields.
> Search these docs over MCP at https://docs.nuon.co/mcp.

# Multiple App Configurations

> Manage separate apps for each cloud and customer architecture.

Most teams have one (or both) true of their BYOC customers:

* Customers that span AWS, Azure, GCP etc.
* Customers that need specific configurations like BYO-VPC vs fully managed BYOC

You can handle this with multiple app configs such as `acme-aws` and `acme-azure`. Keep each app in its own directory, and give
each one its own [app branch](https://docs.nuon.co/guides/app-branches.md) that points at that directory. Each branch rolls changes out to its
installs in [install groups](https://docs.nuon.co/concepts/app-branches.md#install-groups):

**acme-aws**

**main**

**big-customer**

**acme-azure**

**main**

## Connecting each app to git

Each app ships through an app branch:

1. Add a branch file, such as `branches/main.toml`, that points at your repository, the app's directory, and a git
   branch.

2. Sync it once. After the first sync, the branch starts its first [run](https://docs.nuon.co/concepts/app-branches.md#what-triggers-an-app-branch-run).

   ```sh theme={null}
   nuon branches sync --file branches/main.toml
   ```

3. Push to that git branch to ship each change after that.

## Splitting an app branch into install groups

Most teams don't ship a change to every customer at once. A common rollout:

1. **Canary:** your internal and test installs get the change first.
2. **Customers:** once the canary looks healthy, the change rolls out to customer installs, often in tiers.

Each step is an [install group](https://docs.nuon.co/concepts/app-branches.md#install-groups) on the app branch. Groups deploy in `order`, and each one waits
for your approval unless it auto-approves when [policies](https://docs.nuon.co/concepts/policies.md) pass.

```toml branches/main.toml (excerpt) theme={null}
[[install_groups]]
name  = "canary"
order = 1
auto_approve_on_policies_passing = true
[install_groups.label_selector]
tier = "canary"

[[install_groups]]
name    = "customers"
order   = 2
default = true
[install_groups.label_selector]
tier = "customer"
```

### Default labels

Install groups pick installs by label. Default labels put a label on every install, so each new install joins the
right group on its own. Set the value from an install input with [templating](https://docs.nuon.co/guides/using-variables.md):

```toml metadata.toml theme={null}
[default_labels]
tier = "{{ .nuon.install.inputs.tier }}"
```

* Change default labels in `metadata.toml`. You can't edit them on a single install.
* The next app branch run updates every install.

### Label colors

Color-code labels in the dashboard by label key:

```toml metadata.toml theme={null}
[label_colors]
env      = "#FF5733"
region   = "#33FF57"
customer = "#3357FF"
```

Colors set in the dashboard are replaced by these on the next app branch run.

## Telling apps apart in the dashboard

Give each app a name and description in `metadata.toml`. Nuon shows them in the dashboard and CLI:

```toml metadata.toml theme={null}
display_name = "Acme (AWS)"
description  = "Acme for customers on AWS."
readme       = "./README.md"
```

`readme` points to a Markdown file shown on each install. See [Using READMEs](https://docs.nuon.co/guides/using-readmes.md).

## Inspecting an app's config

```sh theme={null}
nuon apps select           # pick the app to inspect
nuon apps configs          # list all config versions
nuon apps runner-config    # print runner config
nuon apps sandbox-config   # print sandbox config
nuon apps input-config     # print input config
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.