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

# BYOC architecture patterns

> Which BYOC architectures Nuon supports for enterprise customers, and how to build each one.

Use this page to match an enterprise customer's requirement to an architecture you can build with Nuon. Each pattern lists what the customer asks for, how to build it, and a reference app in [`nuonco/example-app-configs`](https://github.com/nuonco/example-app-configs).

Every pattern shares the same base:

* The customer deploys a [stack](https://docs.nuon.co/concepts/stacks.md) with their own credentials. It creates the [runner](https://docs.nuon.co/concepts/runners.md) and the [operation roles](https://docs.nuon.co/concepts/operation-roles.md) it uses.
* The runner connects outbound only, so you need no cross-account access. The customer can [turn it off](https://docs.nuon.co/guides/runner-kill-switch.md) at any time.
* [Secrets](https://docs.nuon.co/concepts/app-secrets.md) stay in the customer's cloud secret manager, and [break glass roles](https://docs.nuon.co/concepts/break-glass.md) cover incidents.
* Customers can [export runner audit logs](https://docs.nuon.co/guides/export-runner-audit-logs.md) to their own logging backend.

For the full security model, see [Security](https://docs.nuon.co/security.md).

## Supported patterns

### Dedicated account (full BYOC)

**The customer asks:** "Run your product in our AWS, Azure, or GCP account, but you operate it."

**Build it:** Use the [stand-alone VPC](https://docs.nuon.co/concepts/stacks/stand-alone-vpc.md) stack, which creates a new VPC for the [install](https://docs.nuon.co/concepts/installs). The [sandbox](https://docs.nuon.co/concepts/sandboxes.md) creates the base infrastructure, such as a Kubernetes cluster. Your [components](https://docs.nuon.co/concepts/components.md) deploy your Helm charts, Terraform modules, Kubernetes manifests, and container images on top.

**Reference apps:** [`eks-simple-auto`](https://github.com/nuonco/example-app-configs/tree/main/eks-simple-auto) (AWS), [`gke-simple`](https://github.com/nuonco/example-app-configs/tree/main/gke-simple) (GCP), [`aks-simple`](https://github.com/nuonco/example-app-configs/tree/main/aks-simple) (Azure). See [platform support](https://docs.nuon.co/platform-support/introduction.md) for what each cloud supports.

### Existing customer VPC

**The customer asks:** "Deploy into our VPC and subnets."

**Build it:** Use the [customer VPC](https://docs.nuon.co/concepts/stacks/customer-vpc.md) stack. On AWS, the Nuon-generated CloudFormation template accepts the customer's VPC and subnet IDs, and the sandbox attaches to those subnets. The default Terraform stack modules always create a new VPC, so Terraform deployments of this pattern need a fork of [`install-stacks`](https://github.com/nuonco/install-stacks). See [customizing Terraform stack templates](https://docs.nuon.co/guides/customizing-terraform-stack-templates.md).

**Reference app:** [`byo-vpc`](https://github.com/nuonco/example-app-configs/tree/main/byo-vpc).

### Existing customer Kubernetes cluster

**The customer asks:** "Install into our shared cluster," or your product is an agent or operator that needs in-cluster access.

**Build it:** Start from the customer VPC pattern, then add [custom nested stacks](https://docs.nuon.co/guides/custom-nested-stacks.md) that give the runner access to the cluster. See [customer cluster](https://docs.nuon.co/concepts/stacks/customer-cluster.md).

**Reference app:** [`byo-eks`](https://github.com/nuonco/example-app-configs/tree/main/byo-eks).

### Agent or worker next to customer data (hybrid data plane)

**The customer asks:** "Keep our data in our network. Your hosted product can still manage the work."

**Build it:** Your hosted product stays the control plane for your users. Package the agent or worker that touches customer data as a [Helm chart](https://docs.nuon.co/guides/helm-chart-components.md), [Kubernetes manifest](https://docs.nuon.co/guides/kubernetes-manifest-components.md), or [container image](https://docs.nuon.co/guides/container-image-components.md) component, and Nuon installs and upgrades it in each customer account. To run it in a cluster the customer already has, use the [existing cluster pattern](#existing-customer-kubernetes-cluster).

**Reference apps:** [`datadog-operator`](https://github.com/nuonco/example-app-configs/tree/main/datadog-operator) (operator in the customer's cluster), [`ecs-simple`](https://github.com/nuonco/example-app-configs/tree/main/ecs-simple) (ECS).

### Self-hosted package you want to operate for the customer

**The customer asks:** "We run your Helm chart today and own the upgrades. We want you to run it, in our account."

**Build it:** Wrap your existing Helm chart as a [Helm chart component](https://docs.nuon.co/guides/helm-chart-components.md). Add [Terraform components](https://docs.nuon.co/guides/terraform-components.md) for what the chart depends on, such as a database or bucket. You then ship changes by pushing to git, and [app branches](https://docs.nuon.co/concepts/app-branches.md) roll them out with plan review and approvals. See [updates and operations](https://docs.nuon.co/concepts/updates-and-operations).

### Single-tenant per customer

**The customer asks:** "We need a dedicated, isolated deployment."

**Build it:** Every install is its own stack, sandbox, and set of components in one cloud account. Install the same [app template](https://docs.nuon.co/concepts/apps) into an account you own for a dedicated hosted tier, or into the customer's account for BYOC. See [creating installs](https://docs.nuon.co/guides/install-configs.md).

### Data residency and region pinning

**The customer asks:** "Our data must stay in a specific region."

**Build it:** Each install is created in one region (`nuon installs create --region <region>` in the [CLI](https://docs.nuon.co/cli)), and its resources are created in the customer's account in that region. To block changes that would create resources elsewhere, add a [policy](https://docs.nuon.co/concepts/policies.md). Policies can check Terraform plans before they deploy. See [configuring policies](https://docs.nuon.co/guides/configuring-policies.md).

**Reference app:** [`policies-demo`](https://github.com/nuonco/example-app-configs/tree/main/policies-demo).

## Patterns you build with components

No dedicated docs page covers these, but standard Nuon building blocks support them. A [Terraform component](https://docs.nuon.co/guides/terraform-components.md) can create any resource Terraform supports in the customer's account, using the operation role's permissions. A [custom nested stack](https://docs.nuon.co/guides/custom-nested-stacks.md) creates resources earlier, when the customer deploys the stack with their own admin credentials. Pass outputs to other components with `{{.nuon.components.<name>.outputs.<key>}}`. See [component dependencies](https://docs.nuon.co/guides/component-dependencies.md) and [using variables](https://docs.nuon.co/guides/using-variables.md).

### Customer-managed encryption key

**The customer asks:** "Encrypt our data with a key we control and can revoke."

**Build it:** Accept the customer's existing key ARN or ID as an [input](https://docs.nuon.co/concepts/app-inputs.md), or create the key in a [Terraform component](https://docs.nuon.co/guides/terraform-components.md). Grant your components' [operation roles](https://docs.nuon.co/guides/operation-roles.md) only the key actions they need.

### Customer-owned storage bucket

**The customer asks:** "Store our data in a bucket in our account."

**Build it:** Create the bucket in a [custom nested stack](https://docs.nuon.co/guides/custom-nested-stacks.md), so it exists before any component runs and is created with the customer's credentials. Or create it in a [Terraform component](https://docs.nuon.co/guides/terraform-components.md).

**Reference apps:** [`gcp-gcs-bucket`](https://github.com/nuonco/example-app-configs/tree/main/gcp-gcs-bucket), [`azure-custom-storage`](https://github.com/nuonco/example-app-configs/tree/main/azure-custom-storage).

### Customer database

**The customer asks:** "Run the database in our account, on our managed service."

**Build it:** Create the managed database (for example RDS or Cloud SQL) in a [Terraform component](https://docs.nuon.co/guides/terraform-components.md). Pass its connection details to your [Helm chart](https://docs.nuon.co/guides/helm-chart-components.md) values with component outputs, as shown in [component dependencies](https://docs.nuon.co/guides/component-dependencies.md).

### Model provider in the customer account

**The customer asks:** "Use our own model provider account, such as Amazon Bedrock, for the AI features."

**Build it:** Create the IAM role or service account for the customer's model provider in a [Terraform component](https://docs.nuon.co/guides/terraform-components.md), and pass the endpoint to your app as a component output or [install input](https://docs.nuon.co/concepts/app-inputs.md).

**Reference app:** [`byo-llm-openui`](https://github.com/nuonco/example-app-configs/tree/main/byo-llm-openui) (experimental).

## Talk to us

### Fully air-gapped installs

Today the runner needs an outbound connection to the Nuon control plane to receive jobs. If your customer requires installs on a network with no outbound access, [contact us](https://nuon.co/contact-sales) to talk through your requirements.

Many air-gap requests mean "no inbound access" or "no standing access." The outbound-only runner, and the customer's ability to [turn it off](https://docs.nuon.co/guides/runner-kill-switch.md) between maintenance windows, often meet those.


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