Cloud Deployment Guide

:::warning Work in Progress

This deployment feature is currently only available in the feature/deploy branch.

GitHub Repository: https://github.com/runwaize/supervaizer/tree/feature/deploy

This documentation covers features that are under active development and may change before the next stable release.

:::

The supervaizer deploy command provides fully automated deployment of Supervaizer agents to cloud platforms with zero-downtime updates, health verification, and automatic rollback capabilities.

Overview

info

The deployment CLI supports three major cloud platforms:

GCP Cloud Run - Serverless container platform
AWS App Runner - Fully managed container service
DigitalOcean App Platform - Container-based app hosting

The supervaizer deploy command automates the entire deployment process:

Test Locally - Validate your agent with Docker before cloud deployment

Plan - Preview changes and validate configuration

Deploy - Build, push, and deploy with health verification

Monitor - Check deployment status and health

Cleanup - Remove deployments when needed

Prerequisites

Cloud Provider Setup

Before using the deployment CLI, ensure you have:

GCP Cloud Run
AWS App Runner
DigitalOcean App Platform

Install and Authenticate

# Install Google Cloud CLI
curl https://sdk.cloud.google.com | bash
exec -l $SHELL

# Authenticate
gcloud auth login
gcloud auth application-default login

# Set project
gcloud config set project YOUR_PROJECT_ID

# Enable required APIs
gcloud services enable run.googleapis.com
gcloud services enable secretmanager.googleapis.com
gcloud services enable artifactregistry.googleapis.com

Required Permissions

Your account needs these IAM roles:

Cloud Run Admin
Secret Manager Admin
Artifact Registry Writer
Service Account User

Install and Authenticate

# Install AWS CLI
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install

# Configure credentials
aws configure
# Enter: Access Key ID, Secret Access Key, Region, Output format

Required Permissions

Your account needs these IAM permissions:

apprunner:*
ecr:*
secretsmanager:*
iam:PassRole

Install and Authenticate

# Install doctl
snap install doctl

# Authenticate
doctl auth init
# Enter your DigitalOcean API token

Required Permissions

Your API token needs these scopes:

read - Read access to resources
write - Write access to resources

Local Requirements

# Docker must be installed and running
docker --version
docker ps

# Git repository (for image tagging)
git status

Commands

Plan Deployment

Preview what will be deployed and validate your configuration:

# Plan deployment to GCP Cloud Run
supervaizer deploy plan --platform cloud-run --name my-agent --env prod

# Plan with custom options
supervaizer deploy plan \
  --platform aws-app-runner \
  --name email-agent \
  --env staging \
  --region us-east-1 \
  --project-id my-aws-account

Output Example:

📋 Deployment Plan: email-agent-staging

Platform: AWS App Runner
Region: us-east-1
Environment: staging

Actions:
  ✅ CREATE: ECR repository (email-agent-staging)
  ✅ CREATE: Secrets Manager secrets (SUPERVAIZER_API_KEY, SV_RSA_PRIVATE_KEY)
  ✅ CREATE: App Runner service (email-agent-staging)
  ✅ UPDATE: Environment variables (SUPERVAIZER_PUBLIC_URL)

Estimated Cost: $0.05/hour

Deploy Application

Deploy your Supervaizer agent to the cloud:

# Deploy to GCP Cloud Run
supervaizer deploy up --platform cloud-run --name my-agent

# Deploy with all options
supervaizer deploy up \
  --platform do-app-platform \
  --name email-agent \
  --env prod \
  --region fra \
  --port 8000 \
  --generate-api-key \
  --generate-rsa \
  --yes

Deployment Process:

Build - Create Docker image from your code
Push - Upload image to cloud registry
Secrets - Create/update API keys and RSA keys
Deploy - Create or update the service
Configure - Set SUPERVAIZER_PUBLIC_URL
Verify - Health check until service is ready
Output - Display service URL and endpoints

Success Output:

🚀 Deployment Complete!

Service URL: https://email-agent-prod-xyz123.run.app
Admin Interface: https://email-agent-prod-xyz123.run.app/admin/
API Documentation: https://email-agent-prod-xyz123.run.app/docs

Health Status: ✅ Healthy
Revision: email-agent-prod-xyz123-001
Image: gcr.io/my-project/email-agent:abc123def

Check Status

Monitor your deployment status and health:

# Check status
supervaizer deploy status --platform cloud-run --name my-agent --env prod

# Verbose status with logs
supervaizer deploy status --platform aws-app-runner --name email-agent --verbose

Status Output:

📊 Deployment Status: email-agent-prod

Service URL: https://email-agent-prod-xyz123.run.app
Health Status: ✅ Healthy
Last Check: 2025-01-15 10:30:45 UTC

Configuration:
  Environment: prod
  Port: 8000
  Image: gcr.io/my-project/email-agent:abc123def
  Revision: email-agent-prod-xyz123-001

Resources:
  CPU: 1 vCPU
  Memory: 512 MiB
  Instances: 1-10 (auto-scaling)

Remove Deployment

Clean up your deployment and associated resources:

# Remove deployment
supervaizer deploy down --platform cloud-run --name my-agent --env prod

# Remove with confirmation
supervaizer deploy down --platform aws-app-runner --name email-agent --yes

Cleanup Process:

Stop - Scale down service to zero instances
Delete - Remove the service
Secrets - Delete tool-managed secrets
Confirm - Verify cleanup completion

warning

The down command only removes tool-managed resources. Images in registries are preserved by default.

Test Locally

Test your Supervaizer agent locally using Docker before deploying to the cloud:

# Test locally with default settings
supervaizer deploy local --name my-agent

# Test with custom options
supervaizer deploy local \
  --name email-agent \
  --env dev \
  --port 8000 \
  --generate-api-key \
  --generate-rsa \
  --timeout 60 \
  --verbose

Local Testing Process:

Docker Check - Verify Docker is running and accessible
Generate Files - Create Dockerfile, docker-compose.yml, and .dockerignore
Generate Secrets - Create API key and RSA private key for testing
Build Image - Build the service image with local-test tag
Start Services - Launch Docker Compose with generated secrets
Health Check - Poll health endpoint until service is ready
Verify Endpoints - Test health, API docs, and admin interface
Display Info - Show service URL, API key, and access information

Success Output:

🧪 Local Testing Complete!

Service URL: http://localhost:8000
Admin Interface: http://localhost:8000/admin/
API Documentation: http://localhost:8000/docs

Health Status: ✅ Healthy
API Key: sv_test_********************
RSA Key: Generated and configured

To stop the service:
docker-compose -f .deployment/docker-compose.yml down

Local Testing Options:

Option	Description	Default
`--name`	Service base name	Current directory name
`--env`	Environment (`dev`, `staging`, `prod`)	`dev`
`--port`	Application port	`8000`
`--generate-api-key`	Create secure API key for testing	`false`
`--generate-rsa`	Generate RSA private key for testing	`false`
`--timeout`	Seconds to wait for service startup	`30`
`--verbose`	Show Docker Compose output	`false`
`--docker-files-only`	Only generate Docker files without running them	`false`
`--source-dir`	Source directory path	`src`
`--controller-file`	Controller file name	`supervaizer_control.py`

Docker Files Only Mode:

Use --docker-files-only to generate Docker configuration files without starting the services:

# Generate Docker files only
supervaizer deploy local --docker-files-only --name my-agent

# Generate files with custom configuration
supervaizer deploy local \
  --docker-files-only \
  --name email-agent \
  --port 8080 \
  --generate-api-key \
  --generate-rsa

This mode is useful for:

CI/CD pipelines - Generate files for external Docker execution
Custom Docker setups - Use generated files with your own Docker workflow
File inspection - Review generated Dockerfile and docker-compose.yml before running
Manual testing - Run Docker commands manually with generated configuration

Generated Files:

.deployment/Dockerfile - Container image definition
.deployment/docker-compose.yml - Service orchestration
.deployment/.dockerignore - Docker build exclusions
.deployment/secrets/ - Generated API keys and RSA keys

Custom Source Directory and Controller File:

Use --source-dir and --controller-file to customize your project structure:

# Default usage (backward compatible)
supervaizer deploy local

# Custom source directory
supervaizer deploy local --source-dir .

# Custom controller file
supervaizer deploy local --controller-file my_controller.py

# Both custom parameters
supervaizer deploy local --source-dir lib --controller-file custom_controller.py

# Combined with docker-files-only
supervaizer deploy local \
  --docker-files-only \
  --source-dir . \
  --controller-file my_controller.py

Use Cases:

Non-standard project layouts - When your source code is not in a src/ directory
Multiple controllers - When you have different controller files for different environments
Monorepo setups - When working with multiple services in a single repository
Legacy projects - When adapting existing projects with different directory structures

Local Environment Variables:

The local testing automatically sets these environment variables:

SUPERVAIZER_ENVIRONMENT=dev
SUPERVAIZER_HOST=0.0.0.0
SUPERVAIZER_PORT={port}
SUPERVAIZER_API_KEY={generated-test-key}
SV_RSA_PRIVATE_KEY={generated-rsa-key}
SV_LOG_LEVEL=INFO

Health Check Endpoints:

Local testing verifies these endpoints:

Basic Health: GET http://localhost:{port}/.well-known/health
API Health: GET http://localhost:{port}/agents/health (with API key header)
API Documentation: GET http://localhost:{port}/docs

Cleanup:

# Stop local services
docker-compose -f .deployment/docker-compose.yml down

# Remove local images
docker rmi $(docker images -q "*local-test*")

# Clean up generated files
rm -rf .deployment/

tip

Use local testing to validate your agent configuration before deploying to cloud platforms. It's faster and doesn't require cloud provider authentication.

Configuration Options

Common Options

Option	Description	Default
`--platform`	Cloud platform (`cloud-run`, `aws-app-runner`, `do-app-platform`)	required
`--name`	Service base name	Current directory name
`--env`	Environment (`dev`, `staging`, `prod`)	`dev`
`--region`	Provider region	Platform default
`--project-id`	GCP project / AWS account / DO project	From CLI config
`--port`	Application port	`8000`
`--image`	Custom image tag	Auto-generated from git SHA
`--generate-api-key`	Create secure API key if missing	`false`
`--generate-rsa`	Generate RSA private key secret	`false`
`--yes`	Non-interactive mode	`false`
`--no-rollback`	Keep failed revision on error	`false`
`--timeout`	Deploy + verify timeout (seconds)	`300`
`--verbose`	Show underlying CLI output	`false`

Platform-Specific Options

GCP Cloud Run
AWS App Runner
DigitalOcean App Platform

# GCP-specific options
supervaizer deploy up \
  --platform cloud-run \
  --project-id my-gcp-project \
  --region europe-west1 \
  --use-cloud-build \
  --min-instances 1 \
  --max-instances 10

GCP Options:

--use-cloud-build - Use Cloud Build instead of local Docker
--min-instances - Minimum running instances (0-1000)
--max-instances - Maximum running instances (1-1000)

# AWS-specific options
supervaizer deploy up \
  --platform aws-app-runner \
  --region us-east-1 \
  --cpu 1 \
  --memory 2 \
  --min-instances 1 \
  --max-instances 10

AWS Options:

--cpu - CPU units (0.25, 0.5, 1, 2, 4)
--memory - Memory in GB (0.5, 1, 2, 3, 4, 6, 8, 10, 12)
--min-instances - Minimum running instances
--max-instances - Maximum running instances

# DigitalOcean-specific options
supervaizer deploy up \
  --platform do-app-platform \
  --region fra \
  --size basic-xxs \
  --instances 1

DO Options:

--size - Instance size (basic-xxs, basic-xs, basic-s, basic-m)
--instances - Number of instances

Environment Variables

The deployment CLI automatically sets these environment variables:

Standard Variables

Variable	Value	Description
`SUPERVAIZER_ENVIRONMENT`	`--env` value	Environment name
`SUPERVAIZER_HOST`	`0.0.0.0`	Bind to all interfaces
`SUPERVAIZER_PORT`	`--port` value	Application port
`SV_LOG_LEVEL`	`INFO`	Logging level
`SUPERVAIZER_PUBLIC_URL`	Service URL	Auto-set after deployment

Secret Variables

Variable	Source	Description
`SUPERVAIZER_API_KEY`	Generated/Secret Manager	API key for admin interface
`SV_RSA_PRIVATE_KEY`	Generated/Secret Manager	RSA key for encryption

Custom Variables

You can add custom environment variables using a .deployment/config.yaml file:

# .deployment/config.yaml
environment:
  CUSTOM_VAR: "custom-value"
  DATABASE_URL: "postgresql://..."

secrets:
  - name: "MY_SECRET"
    value: "secret-value"
    description: "My custom secret"

Generated Files

The deployment CLI creates files under .deployment/ directory:

.deployment/
├── Dockerfile              # Generated Docker image
├── .dockerignore           # Docker ignore rules
├── docker-compose.yml      # Local testing
├── do-app-spec.yaml        # DigitalOcean app spec
├── cloudbuild.yaml         # GCP Cloud Build config
├── config.yaml             # Custom configuration
├── state.json              # Deployment state
├── DEPLOY_AUTOMATION.md     # Usage documentation
└── logs/                   # Deployment logs

info

The entire .deployment/ directory is automatically added to .gitignore to prevent accidental commits of deployment artifacts and secrets.

Health Verification

The deployment CLI verifies service health using the /.well-known/health endpoint:

# Health check endpoint
GET https://your-service-url/.well-known/health

# Expected response
{
  "status": "healthy",
  "timestamp": "2025-01-15T10:30:45Z",
  "version": "0.9.8",
  "uptime": 3600
}

Health Check Process

Deploy - Service is created/updated
Wait - Allow service to start (30-60 seconds)
Poll - Check health endpoint every 5 seconds
Verify - Confirm 200 response with healthy status
Rollback - If health check fails (unless --no-rollback)

Troubleshooting

Common Issues

Authentication Errors

# GCP: Re-authenticate
gcloud auth login
gcloud auth application-default login

# AWS: Check credentials
aws sts get-caller-identity

# DigitalOcean: Re-authenticate
doctl auth init

Permission Errors

Ensure your account has the required permissions for your chosen platform. See Prerequisites for detailed permission requirements.

Docker Build Failures

# Check Docker is running
docker ps

# Test Docker build locally
docker build -t test-image .

# Check Dockerfile syntax
cat .deployment/Dockerfile

Health Check Timeouts

# Check service logs
supervaizer deploy status --platform cloud-run --name my-agent --verbose

# Test health endpoint manually
curl https://your-service-url/.well-known/health

# Increase timeout
supervaizer deploy up --timeout 600

Rollback Issues

# Disable automatic rollback
supervaizer deploy up --no-rollback

# Manual rollback to previous revision
supervaizer deploy up --image previous-image-tag

Debug Mode

Enable verbose logging for detailed troubleshooting:

# Verbose deployment
supervaizer deploy up --platform cloud-run --name my-agent --verbose

# Check deployment logs
cat .deployment/logs/deploy-*.log

# Check state file
cat .deployment/state.json

Best Practices

Security

API Keys - Always use --generate-api-key for production
Secrets - Never commit secrets to version control
Permissions - Use least-privilege IAM roles
Networking - Configure VPC and firewall rules as needed

Performance

Image Size - Optimize Docker images for faster deployment
Dependencies - Use .dockerignore to exclude unnecessary files
Scaling - Configure appropriate min/max instances
Health Checks - Ensure health endpoints respond quickly

Reliability

Rollbacks - Test rollback procedures in staging
Monitoring - Set up cloud provider monitoring
Logging - Configure centralized logging
Backups - Regular state and configuration backups

What's Next?

Monitor your deployment using the Admin Interface
Integrate with CI/CD pipelines for automated deployments
Scale your service based on traffic patterns
Explore advanced features like blue-green deployments

Need Help?

Check the Troubleshooting Guide for common issues
Review the CLI Documentation for command-line options
See the API Reference for detailed endpoint information
Visit the GitHub repository for support

Overview​

Prerequisites​

Cloud Provider Setup​

Install and Authenticate​

Required Permissions​

Install and Authenticate​

Required Permissions​

Install and Authenticate​

Required Permissions​

Local Requirements​

Commands​

Plan Deployment​

Deploy Application​

Check Status​

Remove Deployment​

Test Locally​

Configuration Options​

Common Options​

Platform-Specific Options​

Environment Variables​

Standard Variables​

Secret Variables​

Custom Variables​

Generated Files​

Health Verification​

Health Check Process​

Troubleshooting​

Common Issues​

Authentication Errors​

Permission Errors​

Docker Build Failures​

Health Check Timeouts​

Rollback Issues​

Debug Mode​

Best Practices​

Security​

Performance​

Reliability​

What's Next?​

Need Help?​

Overview

Prerequisites

Cloud Provider Setup

Install and Authenticate

Required Permissions

Install and Authenticate

Required Permissions

Install and Authenticate

Required Permissions

Local Requirements

Commands

Plan Deployment

Deploy Application

Check Status

Remove Deployment

Test Locally

Configuration Options

Common Options

Platform-Specific Options

Environment Variables

Standard Variables

Secret Variables

Custom Variables

Generated Files

Health Verification

Health Check Process

Troubleshooting

Common Issues

Authentication Errors

Permission Errors

Docker Build Failures

Health Check Timeouts

Rollback Issues

Debug Mode

Best Practices

Security

Performance

Reliability

What's Next?

Need Help?