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

# Building Nuon Apps

> Create your first app with the Nuon CLI and get to a valid config.

The [CLI](https://docs.nuon.co/cli) is the primary interface for managing apps. To see all available commands, run `nuon apps --help`.

## Creating an App

Create a directory for your app config files in a GitHub repository, then create the app:

```sh theme={null}
mkdir your-app
cd your-app
nuon apps create --name=your-app
```

The directory can have any name. The app branch's `directory` setting tells Nuon where to find it. `nuon apps create`
also selects the new app.

## Adding the Required Files

A valid app needs these three files. The [sandbox](https://docs.nuon.co/concepts/sandboxes.md) and [runner](https://docs.nuon.co/concepts/runners.md) are part of
Nuon's [install infrastructure](https://docs.nuon.co/concepts/installs).

```toml metadata.toml theme={null}
# App details. Only the config version is required.
version = "v2"
```

```toml sandbox.toml theme={null}
# Base infrastructure for each install, such as a VPC and cluster
terraform_version = "1.11.4"

[public_repo]
directory = "."
repo      = "nuonco/aws-min-sandbox"
branch    = "main"
```

```toml runner.toml theme={null}
# The runner that deploys into each customer's cloud account
runner_type = "aws"
```

Then add a [component](https://docs.nuon.co/concepts/components.md) for each Helm chart, Terraform module, or container image you deploy. You
can point a component at an existing chart or module without rewriting it. The
[configuration reference](https://docs.nuon.co/config-ref.md) covers every file and field.

An app you install into a customer account also defines the provision, deprovision, and maintenance roles in its
permissions config. See [Operation Roles](https://docs.nuon.co/concepts/operation-roles.md#required-roles).

## Validating the Config

Check the directory before you push:

```sh theme={null}
nuon apps validate
```

It looks up the app by the directory's name, so it works when the directory and the app share a name.

## Selecting an App

Select an app to make it the default for all app commands, avoiding the need to pass `-a` each time:

```sh theme={null}
nuon apps select
nuon apps get       # show the selected app
nuon apps deselect  # clear the selection
```

## Common Commands

```sh theme={null}
nuon apps list                    # list all apps
nuon apps get                     # get info about the selected app
nuon apps rename --name=new-name  # rename an app
```

## Shipping the Config

App config ships through an [app branch](https://docs.nuon.co/concepts/app-branches.md). Commit the config to your repo, add a branch file,
and sync it once:

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

After that, each push to the tracked git branch builds what changed and rolls it out to your installs. See
[App Branches](https://docs.nuon.co/guides/app-branches.md) for the branch file, and
[Multiple App Configurations](https://docs.nuon.co/guides/multiple-app-configurations.md) to run more than one.


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