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

# Self-Service Onboarding

> Bring your existing Terraform to Tensor9 BYOC yourself - annotate, compile, install.

> [!NOTE]
>
> Preview guidance. Review the decisions and proposed changes before applying them to your product.

You prepare your own Terraform for Tensor9 BYOC. The compiler handles supported installation transforms, while you choose how your application behaves:

* **The Tensor9 compiler** applies supported mechanical transforms, including looking up a pre-created AWS vanity zone when it matches your annotated domain variable.
* **You** identify the domain, secret ownership and other application choices using **annotations**: comments directly above their Terraform blocks. You also review feature configuration and any required source repair separately.

Annotation comments leave your own deployments unchanged. Adding name prefixes with an empty default preserves existing names. Feature settings and source repairs can change behavior, so review their plans separately.

If you prefer, an agent can do the finding and the writing for you. The [Claude Code and Codex skills](https://docs.tensor9.com/byoc/onboarding/agent-skills.md) read your Terraform, ask you each real decision, write the annotations you choose, and check a bundled library of common Terraform mistakes.

## Who does what

| | The Tensor9 compiler | You |
| - | - | - |
| **What** | Supported mechanical installation transforms | Choices that depend on your product or your customers |
| **How** | Automatically, on every compile | Annotations, explicit feature settings and reviewed source edits |
| **Examples** | Translating services to the customer's cloud, mirroring container images and other artifacts into the install, setting each install's region, unique name prefix and domain once you have marked where they go, keeping account-wide settings from colliding with what the customer already runs | Which variable holds the domain an install serves, who supplies each secret, which names must be unique per install, which endpoints must stay public, which parts of your stack only your own environments need |
| **Problems found** | Compiler diagnostics appear in the compile report | The skills check their common-mistakes library and show source findings and proposed repairs separately |

Annotating an existing domain variable is enough for the supported automatic AWS zone lookup; do not add a new hosted-zone switch for that case. See [the exact conditions](https://docs.tensor9.com/byoc/onboarding/annotations.md#vanity_domain_provided).

## Review application configuration and source problems

The Claude Code and Codex skills include the same library of common Terraform mistakes. Its first rule checks optional resources that can be absent through `count` or `for_each` while a consumer still reads `[0]` or a key that may not exist. The skill follows the condition that creates the resource, checks its consumers, and shows the finding and a proposed repair. It does not present these checks as compiler diagnostics.

For example, choosing an empty endpoint service name disables Oumi's ClickHouse PrivateLink endpoint. The original dashboard still reads `aws_vpc_endpoint.clickhouse[0]`. The library identifies this mismatch and describes guarding the ClickHouse widget group when the endpoint is absent. The skill presents the vendor's feature choice separately from the source repair and asks before applying the repair. Declined or unresolved work stays in its report.

Do not assume the compiler detects every source problem. A successful compile does not prove that the resulting configuration can plan, apply or serve traffic. Read the compile report, resolve Blocking issues, then validate the deployment configuration and application behavior.

External billing, identity, telemetry and other services need their own product decisions. Decide whether each function belongs in a customer install, who owns any retained account, and what application changes are required. The [external-services guide](https://docs.tensor9.com/byoc/onboarding/external-services.md) walks through those choices, with dedicated [Stripe](https://docs.tensor9.com/byoc/onboarding/stripe.md) and [Metronome](https://docs.tensor9.com/byoc/onboarding/metronome.md) guidance. The skills load shared consideration data from your VCtrl through the public `tensor9` CLI, with a labelled offline fallback. A match or missing credential never automatically removes a dependency.

## The flow: annotate, compile, install

### Create your vendor account and control plane

Follow [Get a Tensor9 API key](https://docs.tensor9.com/byoc/getting-started/api-key.md) to sign up and install the `tensor9` CLI. Then run `export T9_API_KEY=<your API key>` and `tensor9 vendor setup` to [set up your control plane](https://docs.tensor9.com/byoc/fundamentals/install.md) in your own AWS account, in the `us-west-2` region. Setup makes its controller profile your CLI default, so the commands below need no API key or profile options. See [Your controller profile](https://docs.tensor9.com/byoc/fundamentals/install.md#your-controller-profile).

A sandbox session is separate exploration access and does not replace your account or control plane.

**1. Annotate**

Add an annotation above each block that needs one of your decisions. Most stacks need a handful: one for the install's domain, one for the region, one for a unique name prefix, and one per secret. The [annotation reference](https://docs.tensor9.com/byoc/onboarding/annotations.md) lists every annotation, the decision it records and an example.

You can do this by hand, or [have an agent do it](https://docs.tensor9.com/byoc/onboarding/agent-skills.md):

```text theme={null}
/tensor9-byoc-onboarding ./terraform
```

The agent asks one question at a time and only writes what you approve. It reports annotations separately from namespace edits, feature configuration and source repairs.

**2. Publish and bind**

Create your app if you have not already, then publish your stack and bind it to your app in one step. Later publishes with the same `-stackName` update the stack and keep the binding:

```bash theme={null}
tensor9 app create -name my-app -displayName "My app"

tensor9 stack publish-direct \
  -appName my-app \
  -stackType TerraformWorkspace \
  -stackName my-app-stack \
  -dir ./terraform
```

**3. Onboard a customer**

Create the form factor your customers install, then create a setup link for a customer:

```bash theme={null}
tensor9 form-factor create \
  -appName my-app \
  -formFactorName aws-connected \
  -env Aws \
  -connectivity Connected

tensor9 app setup -appName my-app -customerName acme-corp
```

The setup command creates the customer `acme-corp` if it does not exist yet and prints its setup link. Send the link to your customer. They choose their environment and apply the infrastructure templates in their own account, as the [customer installation guide](https://docs.tensor9.com/byoc/customer/installation/overview.md) describes. `tensor9 report` shows their appliance when it is ready.

**4. Compile and install**

Create a release for the customer. Release creation compiles the stack for that customer's environment and writes the deployment stack locally. This guide does not require a separate standalone compile command.

```bash theme={null}
tensor9 stack release create \
  -appName my-app \
  -customerName acme-corp \
  -vendorVersion "1.0.0" \
  -description "First install" \
  -notes "Annotated for Tensor9 BYOC"
```

Review the compiler report and resolve Blocking issues before continuing. Release creation downloads the compiled workspace into `<appliance-name>/my-app-stack/`. Change into that directory, then run `tofu init` and `tofu apply`, as you would any Terraform workspace, with your API key in `T9_API_KEY` for this step only:

The tensor9 provider in the deployment stack authenticates with your Tensor9 API key, which it reads from the `T9_API_KEY` environment variable. In the workspace directory, enter the key at a hidden prompt, apply the stack, then unset the variable:

**Bash**

```bash theme={null}
set +x
IFS= read -r -s -p 'Tensor9 API key: ' T9_API_KEY
printf '\n'
export T9_API_KEY
tofu init
tofu apply
unset T9_API_KEY
```

**Zsh**

```zsh theme={null}
set +x
IFS= read -r -s 'T9_API_KEY?Tensor9 API key: '
printf '\n'
export T9_API_KEY
tofu init
tofu apply
unset T9_API_KEY
```

Use the API key you downloaded from [sandbox.tensor9.com](https://sandbox.tensor9.com/). Unset `T9_API_KEY` as soon as the apply finishes: while it is set, `tensor9` CLI commands use the key instead of your controller profile. Do not put the key in a command, a shell profile or a source file.

See the [Terraform quick start](https://docs.tensor9.com/byoc/getting-started/quick-start-terraform.md) for a complete first-time walkthrough, and its [Clean up](https://docs.tensor9.com/byoc/getting-started/quick-start-terraform.md#clean-up) section for removing a test install.

## What you keep

* **One stack.** The same Terraform runs your own environments and every customer install.
* **Reviewed source changes.** Namespace prefixes, feature choices and repairs stay explicit in your own code review.
* **A visible record of decisions.** Annotations sit next to their blocks; configuration and repair edits remain visible in your diff and history.

## Next steps

> **[Annotation reference](https://docs.tensor9.com/byoc/onboarding/annotations.md)**
>
> Syntax, the decision each annotation records, and an example of each.

> **[Have an agent do it](https://docs.tensor9.com/byoc/onboarding/agent-skills.md)**
>
> Install the Claude Code or Codex skill and let it find and write your annotations.


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