Common Workflows

This guide shows common workflows for using the tensor9 CLI to manage your apps, stacks, and appliances.

Prerequisites

Before starting, ensure you have:

Installed the tensor9 CLI
Downloaded your Tensor9 API key
Configured AWS credentials for your Tensor9 BYOC AWS account

Initial setup workflow

Set up Tensor9 BYOC in your AWS account for the first time.

Set up your control plane

Export your API key and run setup:

export T9_API_KEY=<your API key>
tensor9 vendor setup -awsProfile my-tensor9-profile

This creates your control plane in your AWS account in several minutes and makes its controller profile your CLI default, so later commands need no API key or profile options. See Set up your control plane.

Verify setup

Check that your control plane is ready:

tensor9 report

You should see your vendor information displayed.

Create your first app

tensor9 app create \
  -name my-app \
  -displayName "My Application"

Your app is now created and ready to have a stack bound to it.

Publish and bind your origin stack

Publish an origin stack and bind it to your app.

For Terraform stacks

Publish and bind your Terraform stack

From your Terraform workspace directory:

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

This uploads your Terraform files through your control plane and binds the stack to your app as my-app-stack. It needs no AWS credentials. To upload to S3 with your own AWS credentials and bind separately instead, see stack publish.

For Docker container stacks

Push your container image to ECR

First, authenticate to your Tensor9 BYOC AWS account’s ECR:

aws ecr get-login-password --region us-west-2 --profile my-tensor9-profile | \
  docker login --username AWS --password-stdin <account-id>.dkr.ecr.us-west-2.amazonaws.com

Tag and push your image:

docker tag my-app:latest <account-id>.dkr.ecr.us-west-2.amazonaws.com/my-app:latest
docker push <account-id>.dkr.ecr.us-west-2.amazonaws.com/my-app:latest

The native stack ID is the image URI:

<account-id>.dkr.ecr.us-west-2.amazonaws.com/my-app:latest

Bind the container to your app

tensor9 stack bind \
  -appName my-app \
  -stackType DockerContainer \
  -nativeStackId "<account-id>.dkr.ecr.us-west-2.amazonaws.com/my-app:latest"

Your container is now bound to your app.

For Docker Compose stacks

Before publishing your Docker Compose file, ensure all container images referenced in your compose file are pushed to their registries (ECR, Docker Hub, etc.). These images must be available when you create a release.

Publish and bind your Docker Compose file

tensor9 stack publish-direct \
  -appName my-app \
  -stackType DockerCompose \
  -stackName my-app-compose \
  -file docker-compose.yml

This publishes the Compose file through your control plane and binds it to your app as my-app-compose.

For CloudFormation stacks

Deploy your CloudFormation stack

Deploy your CloudFormation stack using the AWS CLI:

aws cloudformation create-stack \
  --stack-name my-app-stack \
  --template-body file://template.yaml \
  --region us-west-2 \
  --profile my-tensor9-profile

Get the stack ARN

aws cloudformation describe-stacks \
  --stack-name my-app-stack \
  --region us-west-2 \
  --query 'Stacks[0].StackId' \
  --output text

This returns an ARN like:

arn:aws:cloudformation:us-west-2:123456789012:stack/my-app-stack/a1b2c3d4

Bind the CloudFormation stack

tensor9 stack bind \
  -appName my-app \
  -stackType CloudFormation \
  -nativeStackId "arn:aws:cloudformation:us-west-2:123456789012:stack/my-app-stack/a1b2c3d4"

Prepare a test appliance

Use an existing, ready test appliance for your app. Test-appliance creation is not available through the public CLI; contact Tensor9 if you need one. To test a release yourself without a test appliance, onboard a second AWS account of your own as a customer with tensor9 app setup and release to it with -customerName, as the Terraform quick start shows. Use tensor9 report to check its status before creating a release.

Deploy to a test appliance

Deploy your stack to a test appliance to verify it works before releasing to customers.

Create a release

Create a release for your test appliance:

tensor9 stack release create \
  -appName my-app \
  -testApplianceName my-test-appliance \
  -vendorVersion "1.0.0" \
  -description "Initial release" \
  -notes "First production release"

After a few minutes, the deployment stack downloads to a directory named my-test-appliance, alongside a companion my-test-appliance.audit directory containing the audit stack for pre-deployment review.

Review the audit stack (optional)

Before deploying, you can scan the audit stack with your standard IaC security and policy tooling. The audit stack is a Tensor9 BYOC-free copy of the deployment stack - same application infrastructure, without any Tensor9 BYOC providers or runtime plumbing - so scanners can plan and inspect it standalone:

cd my-test-appliance.audit
tofu init
tofu plan

# Security / policy scans
tfsec .
checkov -d .

The audit stack is for review only. Do not apply it. Only the deployment stack (in my-test-appliance) provisions a working install.

Deploy the release

Change into the deployment stack directory, then run tofu init and tofu apply:

cd my-test-appliance

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
Zsh

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

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. 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.Your application is now deployed in the test appliance.

Verify the deployment

Check the deployed resources:

kubectl get deployments
kubectl get services
kubectl get pods

For services with external ports, get the load balancer endpoint:

kubectl get service <service-name> -o jsonpath='{.status.loadBalancer.ingress[0].hostname}'

Access your application through the load balancer URL.

Create a customer appliance

Enable your customer to create an appliance for your app in their environment.

Generate signup link

Generate a setup link for your customer. Your app needs at least one form factor first:

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

Send the generated URL to your customer. They’ll use it to create their appliance.

Customer creates appliance

The customer uses the signup link to:

Sign up and create their organization (if they haven’t already)
Select their cloud provider and region
Complete the setup to create their appliance

Their appliance will be provisioned automatically in their cloud account.

Monitor appliance creation

Check when the customer’s appliance is ready:

tensor9 report

Wait until their appliance status shows “Live”.

Create a release for the customer

Once their appliance is ready:

tensor9 stack release create \
  -appName my-app \
  -customerName acme-corp \
  -vendorVersion "1.0.0" \
  -description "Initial deployment for Acme Corp" \
  -notes "Configured for production use"

The deployment stack downloads to a directory named after their appliance.

Deploy to the customer's appliance

Deploy the release to the customer’s appliance. Change into the deployment stack directory, then run tofu init and tofu apply with your API key in T9_API_KEY for this step only, as in Deploy the release:

cd acme-corp-appliance

This deploys your application into the customer’s appliance.

Release to a customer appliance

Release infrastructure or code changes to your customer appliances.

Update your origin stack

Make changes to your Terraform files, docker-compose.yml, or CloudFormation template.

Republish the stack

For Terraform:

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

For Docker Compose:

tensor9 stack publish-direct \
  -appName my-app \
  -stackType DockerCompose \
  -stackName my-app-compose \
  -file docker-compose.yml

For CloudFormation:

aws cloudformation update-stack \
  --stack-name my-app-stack \
  --template-body file://template.yaml

Use the same -stackName as the first publish. You don’t need to re-bind the stack. Tensor9 BYOC will use the updated version for new releases.

Test in test appliance

Create a release to your test appliance:

tensor9 stack release create \
  -appName my-app \
  -testApplianceName my-test-appliance \
  -vendorVersion "1.1.0" \
  -description "Added new features" \
  -notes "Added caching layer and API improvements"

Deploy and verify

Change into my-test-appliance and run tofu apply, with your API key in T9_API_KEY for this step only, as in Deploy the release.Verify the changes work as expected.

Release to customers

After testing, release to your customers:

# Release to specific customer
tensor9 stack release create \
  -appName my-app \
  -customerName acme-corp \
  -vendorVersion "1.1.0" \
  -description "Feature update" \
  -notes "New caching layer and performance improvements"

# Or release to all customers
tensor9 stack release create \
  -appName my-app \
  -all \
  -vendorVersion "1.1.0" \
  -description "Feature update" \
  -notes "New caching layer and performance improvements"

Manage multiple form factors

Deploy your app to different cloud providers or connectivity modes.

Create form factors

Create form factors for different environments:

# AWS connected
tensor9 form-factor create \
  -appName my-app \
  -formFactorName aws-connected \
  -description "AWS with internet connectivity" \
  -env Aws \
  -connectivity Connected

# GCP connected
tensor9 form-factor create \
  -appName my-app \
  -formFactorName gcp-connected \
  -description "Google Cloud with internet connectivity" \
  -env Gcp \
  -connectivity Connected

Test each form factor

Use a ready test appliance for each form factor you want to test. The release examples below use my-aws-test and my-gcp-test; replace them with your appliance names.

Release to each test appliance

tensor9 stack release create \
  -appName my-app \
  -testApplianceName my-aws-test \
  -vendorVersion "1.0.0" \
  -description "AWS test" \
  -notes "Testing AWS deployment"

tensor9 stack release create \
  -appName my-app \
  -testApplianceName my-gcp-test \
  -vendorVersion "1.0.0" \
  -description "GCP test" \
  -notes "Testing GCP deployment"

Onboard your vendor controller to Tailscale

By default, the listeners your CLI and Terraform use to reach the vendor controller are exposed on a public network load balancer with mTLS protection. If you operate a Tailscale tailnet for your engineering team, you can have the vendor controller join that tailnet and (optionally) remove the public path entirely. See Connectivity for the broader picture. This workflow rolls out in two phases: first attach the controller to your tailnet and verify operator access, then optionally enforce tunnel-only by removing the public listeners.

Phase 1: attach the vendor controller to your tailnet

Ensure your tailnet ACL has the required tags and rules

This step is idempotent. It adds the tag:tensor9-vctrl (vendor controller) and tag:tensor9-customer-ctrl (appliance controller) tags, the group:tensor9-operators group, and the rules that allow operators and customer appliances to reach the vendor controller. Existing ACL entries are preserved.

export TAILSCALE_API_KEY=tskey-api-...

tensor9 tailscale acl setup

If you maintain ACLs in HuJSON via the dashboard, the command prints a copy-pasteable snippet you can apply by hand. Otherwise answer y at the confirmation prompt to have the CLI POST the change for you (a local backup is written under ~/.tensor9/tailscale-acl-backups/).See tensor9 tailscale acl setup for full options.

Generate a pre-auth key for the vendor controller

The key is tagged so the ACL applies the right rules to the resulting node. Keep it single-use (the default) for production:

tensor9 tailscale key generate -tag VCtrl

Save the printed tskey-auth-... value; you will pass it to the next command. See tensor9 tailscale key generate for full options.Add operators to the group:operators group in the Tailscale dashboard so they can reach the controller’s listeners over the tailnet.

Attach the vendor controller to the tailnet

tensor9 vendor tailscale onboard \
  -vctrlKey tskey-auth-XXXXXXXXXXXX

The command installs the Tailscale daemon on the vendor controller, joins it to the tailnet, and stamps the resulting tailnet hostname onto the controller’s configuration. The controller’s existing public listeners stay in place.See tensor9 vendor tailscale onboard for full options.

Verify operator access over the tailnet

With your operator account in group:operators and connected to the tailnet, run a read-only command:

tensor9 report

Your CLI should be able to reach the vendor controller over the tailnet without any extra flags. The controller is still reachable over the public path too, so this step proves the tailnet route is working while leaving you a fallback.The endpoint used with Terraform/OpenTofu plan and apply operations is defined in the tensor9 provider block of the compiled deployment stack. Compilation emits the publicly available listener to this block when it is available, even if you have a tunnel configured, to be compatible with CI deployments. For testing, you can manually modify the compiled stack to change the endpoint address to be the vendor controller’s address on the tailnet and try a plan. Follow phase 2, below, to remove the TF endpoint from the public load balancer and re-compile your deployment stacks to enforce using the Tailscale for communication between your local Terraform/OpenTofu CLI and the vendor controller.

Phase 2: remove the public listeners

Once you are satisfied that operators and Terraform-driven deploys work over the tailnet, you can enforce tunnel-only and tear the public listeners down. Roll this out per listener group rather than all at once so you can pause if something is missed.

Mark the operator listeners as tunnel-only

The tunnel enforce command mutates the controller’s configuration; the listener teardown happens on the next infrastructure upgrade.

# CLI listeners first
tensor9 vendor tunnel enforce -add CLI

# After a soak period, the Terraform reactor too (make sure CI works!)
tensor9 vendor tunnel enforce -add Terraform

See tensor9 vendor tunnel enforce for full options. If you also want to remove the appliance-facing public listener, the command checks first that no customer appliance still depends on it; see the pre-flight notes in the reference.

Apply the change

Run an infrastructure upgrade to remove the now-redundant listeners from your network load balancer:

tensor9 vendor upgrade \
  -kind Infrastructure \
  -reason "remove public CLI and Terraform listeners after Tailscale cutover"

After this completes, the only way to reach the enforced listeners is over the tailnet.

Make sure every operator and every CI runner that drives tensor9 or terraform against the vendor controller is on the tailnet before you run tunnel enforce -add CLI / Terraform. After the next infrastructure upgrade, anything off the tailnet will be locked out.

To roll back, run tensor9 vendor tunnel enforce -remove CLI,Terraform followed by tensor9 vendor upgrade -kind Infrastructure. The public listeners are recreated.

Use stack tuning documents

Customize resource allocations per customer or environment.

Create a tuning document

Create a JSON file with resource overrides:

{
  "version": "V1",
  "composeServices": {
    "web": {
      "replicas": 4,
      "resources": {
        "cpu": "2",
        "memory": "4Gi"
      }
    },
    "api": {
      "replicas": 3,
      "resources": {
        "cpu": "1",
        "memory": "2Gi"
      }
    }
  }
}

Save as enterprise-tuning.json.

Release with tuning document

tensor9 stack release create \
  -appName my-app \
  -customerName enterprise-customer \
  -vendorVersion "1.0.0" \
  -description "Enterprise deployment" \
  -notes "High-performance configuration" \
  -tuningDoc enterprise-tuning.json

The deployment stack will use the tuned resource specifications.

Monitor appliances

Check the status of your apps, appliances, and releases.

View comprehensive report

tensor9 report

This shows:

All your apps and their stacks
All test appliances and their status
All customer appliances and their status
Active releases

View detailed report

tensor9 report -detailed

List all appliances

tensor9 appliance list

Use the web portal

Start a local web interface:

tensor9 portal

This opens a browser with a visual dashboard of your apps and appliances.

Retire a test appliance

Test-appliance retirement is not available through the public CLI. Contact Tensor9 to arrange retirement, including data retention and ongoing infrastructure costs.

Manage your vendor team

Tensor9 BYOC distinguishes two kinds of vendor accounts:

The root account is created automatically when you run vendor setup. It is the singleton account for your vendor and the only one that can invite, list, or revoke other accounts. If you lose your root cert, you can re-issue it from your control plane’s seed bundle in your AWS account (iam account recover).
Operator accounts are everyone else: teammates the root account invites by email. They get a long-lived mTLS cert pinned by your control plane after redeeming a one-time enrollment bundle. They can run ordinary vendor commands but cannot manage other accounts. If an operator loses their cert, the root account re-invites them.

See IAM Commands in the reference for the full surface and authorization details.

Invite a teammate

Mint an enrollment bundle

From your laptop (root account), invite by email:

tensor9 iam user invite -email [email protected]

This writes a single-use bundle to ./[email protected]. The bundle is valid for 48 hours by default. Use -ttl PT24H (or any ISO-8601 duration) to set a different window.

Send the bundle out-of-band

Send the file to your teammate via Slack, encrypted email, or a similar channel. The bundle contains a one-time secret, so treat it as sensitive until redeemed.

Have your teammate redeem it

On their machine, your teammate runs:

tensor9 configure -enrollmentBundle ./[email protected]

This trades the bundle for a long-lived mTLS cert pinned by your control plane, persists it locally, and writes a CLI profile so subsequent tensor9 commands authenticate automatically.

List your team

tensor9 iam user list

Shows the root account plus every invited operator with their enrollment status (Enrolled, Invited, or Revoked).

Revoke access

To remove an operator’s access, find their account ID and revoke:

tensor9 iam user list
tensor9 iam user revoke -accountId 00000000000000000000000000000003

Revocation is two-stage on the server: any in-flight enrollment bundles are killed, and the leaf-fingerprint pin is dropped so the user’s cached cert stops authenticating on its next handshake.

The root account cannot revoke itself. Use tensor9 iam account recover to rotate the root cert.

Recover the root account

If you lose your laptop or wipe ~/.tensor9/, recover by re-issuing the root cert from your control plane’s seed bundle:

tensor9 iam account recover -vendorId <your-vendor-id>

The command reads your control plane’s seed bundle directly from your AWS Secrets Manager / Parameter Store. Access to that secret-store path is the actual gate, so make sure the IAM policy on it is scoped tightly. For non-root operator account recovery, ask your root account to re-invite you with iam user invite. Operator tokens are single-use, so there’s no equivalent self-service recovery path on the operator side.

Troubleshoot common issues

Release deployment fails

Problem: tofu apply fails when deploying a release.Solution:

Check the Terraform error messages
Verify your origin stack is valid: tofu validate in your workspace
Check appliance status: tensor9 report
Review deployment stack variables and configuration
Check AWS credentials and permissions

Test appliance stuck in Creating status

Problem: Test appliance remains in “Creating” status for a long time.Solution:

Wait 15-20 minutes (appliance creation can take time)
Check tensor9 report -detailed for error messages
Verify AWS quotas are sufficient for EKS, VPCs, etc.
Check CloudFormation console in AWS for stack creation issues
Contact support if stuck for more than 30 minutes

Stack publish fails

Problem: tensor9 stack publish fails with upload errors.Solution:

Verify AWS credentials: aws sts get-caller-identity --profile <profile>
Check that no .terraform directories are in your workspace
Ensure you have write permissions to the control plane S3 bucket
For large stacks, check your network connection

Customer can't access their appliance

Problem: Customer reports they can’t reach their deployed application.Solution:

Verify deployment completed: Check with customer that tofu apply succeeded
Check load balancer: kubectl get service shows external IP/hostname
Verify DNS configuration if using custom domains
Check security groups/firewall rules in customer’s cloud
Review application logs: kubectl logs <pod-name>

Release not downloading

Problem: After creating a release, the deployment stack doesn’t download.Solution:

Wait a few minutes (compilation takes time)
Check release status: tensor9 report
Verify appliance is in “Live” status
Check for stack validation errors in the report
Review control plane CloudWatch logs for compilation errors

Best practices

Version your releases semantically

Use semantic versioning for your releases:

1.0.0 - Initial release
1.0.1 - Patch (bug fixes)
1.1.0 - Minor (new features, backward compatible)
2.0.0 - Major (breaking changes)

This helps customers understand the impact of updates.

Test every release

Always create a release to a test appliance before releasing to customers:

Create release to test appliance
Deploy and verify functionality
Test upgrade path from previous version
Only then release to customers

Use descriptive release notes

Write clear, customer-facing release notes:

tensor9 stack release create \
  -appName my-app \
  -customerName acme-corp \
  -vendorVersion "1.2.0" \
  -description "Bug fixes and performance improvements" \
  -notes "Fixed authentication timeout issue. Improved API response time by 40%. Added support for batch operations."

Your customers see these notes when deploying.

Organize your origin stacks

Keep your origin stacks in version control and use consistent naming:

Use Git to track changes to origin stacks
Tag releases in Git: git tag v1.0.0
Use the same version in Git and Tensor9 BYOC releases
Document infrastructure changes in commit messages

Monitor appliance health

Regularly check appliance status:

# Weekly check
tensor9 report

# Monthly detailed review
tensor9 report -detailed

Set up alerts for customer appliance issues.

Next steps

CLI Reference: Complete command reference
Quick Start Guides: Step-by-step tutorials
Deployments: Learn more about the deployment process
Testing: Best practices for testing releases

​Prerequisites

​Initial setup workflow

​Publish and bind your origin stack

​For Terraform stacks

​For Docker container stacks

​For Docker Compose stacks

​For CloudFormation stacks

​Prepare a test appliance

​Deploy to a test appliance

​Create a customer appliance

​Release to a customer appliance

​Manage multiple form factors

​Onboard your vendor controller to Tailscale

​Phase 1: attach the vendor controller to your tailnet

​Phase 2: remove the public listeners

​Use stack tuning documents

​Monitor appliances

​View comprehensive report

​View detailed report

​List all appliances

​Use the web portal

​Retire a test appliance

​Manage your vendor team

​Invite a teammate

​List your team

​Revoke access

​Recover the root account

​Troubleshoot common issues

​Best practices

​Next steps

Prerequisites

Initial setup workflow

Publish and bind your origin stack

For Terraform stacks

For Docker container stacks

For Docker Compose stacks

For CloudFormation stacks

Prepare a test appliance

Deploy to a test appliance

Create a customer appliance

Release to a customer appliance

Manage multiple form factors

Onboard your vendor controller to Tailscale

Phase 1: attach the vendor controller to your tailnet

Phase 2: remove the public listeners

Use stack tuning documents

Monitor appliances

View comprehensive report

View detailed report

List all appliances

Use the web portal

Retire a test appliance

Manage your vendor team

Invite a teammate

List your team

Revoke access

Recover the root account

Troubleshoot common issues

Best practices

Next steps