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 Set your API key: export T9_API_KEY=<your-key>
Configured AWS credentials for your Tensor9 AWS account
Initial setup workflow Set up Tensor9 in your AWS account for the first time.
Set up your control plane
Run the interactive setup: Or provide all parameters: tensor9 vendor setup \ -cloud aws \ -region us-west-2 \ -awsProfile my-tensor9-profile
This creates your Tensor9 control plane in your AWS account. It takes several minutes to complete.
Verify setup
Check that your control plane is ready: 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.
Publish your Terraform stack
From your Terraform workspace directory: tensor9 stack publish \ -stackType TerraformWorkspace \ -stackS3Key my-app-stack \ -dir .
This uploads your Terraform files and returns a native stack ID like: s3://t9-ctrl-000001/terraform-stacks/origins/my-app-stack.tf.tgz
Bind the stack to your app
tensor9 stack bind \ -appName my-app \ -stackType TerraformWorkspace \ -nativeStackId "s3://t9-ctrl-000001/terraform-stacks/origins/my-app-stack.tf.tgz"
Your stack is now bound to your app. For Docker container stacks
Push your container image to ECR
First, authenticate to your Tensor9 AWS account’s ECR: aws ecr get-login-password --region us-west-2 --profile my-tensor9-profile | \ docker login --username AWS --password-stdin < account-i d > .dkr.ecr.us-west-2.amazonaws.com
Tag and push your image: docker tag my-app:latest < account-i d > .dkr.ecr.us-west-2.amazonaws.com/my-app:latest docker push < account-i d > .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 your Docker Compose file
tensor9 stack publish \ -stackType DockerCompose \ -stackS3Key my-app-compose \ -file docker-compose.yml
Returns a native stack ID like: s3://t9-ctrl-000001/my-app-compose.yml
Bind the stack to your app
tensor9 stack bind \ -appName my-app \ -stackType DockerCompose \ -nativeStackId "s3://t9-ctrl-000001/my-app-compose.yml"
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"
Create a test appliance Create a test appliance for testing your releases before deploying to customers.
Create a test appliance
tensor9 test appliance create \ -appName my-app \ -name my-test-appliance
The test appliance will be created asynchronously.
Monitor appliance creation
Check the status periodically: Wait until the test appliance status shows “Live”. This typically takes 10-15 minutes. 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.
Deploy the release
cd my-test-appliance tofu init tofu apply
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-nam e > -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 signup link for your customer: tensor9 app signup-link -appName my-app
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: 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: cd acme-corp-appliance tofu init tofu apply
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 \ -stackType TerraformWorkspace \ -stackS3Key my-app-stack \ -dir .
For Docker Compose: tensor9 stack publish \ -stackType DockerCompose \ -stackS3Key my-app-compose \ -file docker-compose.yml
For CloudFormation: aws cloudformation update-stack \ --stack-name my-app-stack \ --template-body file://template.yaml
You don’t need to re-bind the stack. Tensor9 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
cd my-test-appliance tofu apply
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"
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 # DigitalOcean connected tensor9 form-factor create \ -appName my-app \ -formFactorName digitalocean-connected \ -description "DigitalOcean with internet connectivity" \ -env DigitalOcean \ -connectivity Connected
Test each form factor
Create test appliances for each form factor: tensor9 test appliance create \ -appName my-app \ -name my-aws-test \ -formFactorName aws-connected tensor9 test appliance create \ -appName my-app \ -name my-gcp-test \ -formFactorName gcp-connected \ -cloudRegion gcp:us-central1
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"
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 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 List all appliances Use the web console Start a local web interface:
This opens a browser with a visual dashboard of your apps and appliances.
Retire a test appliance Remove a test appliance when no longer needed.
tensor9 test appliance retire -testApplianceName my-test-appliance
This permanently deletes the test appliance and all its infrastructure. It may take several minutes to fully deprovision.
Troubleshoot common issues
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
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>
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 release1.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.
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 releases
Document infrastructure changes in commit messages
Regularly check appliance status: # Weekly check tensor9 report # Monthly detailed review tensor9 report -detailed
Set up alerts for customer appliance issues. Next steps 
