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

# 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 [BYOC management infra](https://docs.nuon.co/concepts/nuon-infrastructure).

```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. The
[configuration reference](https://docs.nuon.co/config-ref.md) covers every file and field.

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

Next, ship your config with an app branch. See [Multiple App Configurations](https://docs.nuon.co/guides/multiple-app-configurations.md).


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