Teabar mascot

Local Execution

Run Teabar operators on your local machine for development, testing, or home lab environments. The local operator runs in a Docker container and connects to the Teabar daemon, allowing you to provision infrastructure on your own hardware.

Overview

The teactl local command group manages local operator instances that run on your machine:

  • Test locally - Test blueprints on your own Proxmox or hardware
  • Save costs - No cloud charges for development environments
  • Air-gapped - Work offline with local infrastructure
  • Fast iteration - Quick feedback during blueprint development

Quick Start

# 1. Configure your local provider
export TEABAR_PROXMOX_URL=https://pve.local:8006
export TEABAR_PROXMOX_TOKEN_ID="root@pam!teabar"
export TEABAR_PROXMOX_SECRET="your-secret"

# 2. Start local operator
teactl local start --provider=proxmox

# 3. Create environment
teactl env create --blueprint ubuntu-vm --name local-test

# 4. Check status
teactl local status

# 5. Stop when done
teactl local stop

teactl local start

Start a local operator container.

teactl local start [flags]

Flags

FlagShortDescription
--providerProvider to use (proxmox, hetzner) [default: proxmox]
--devDevelopment mode (container persists for debugging)
--auto-registerAuto-register with daemon [default: true]

Examples

Start with Proxmox:

teactl local start --provider=proxmox

Start in development mode:

# Container stays running for debugging
teactl local start --dev

# Press Ctrl+C to stop

Start with Hetzner:

export TEABAR_HCLOUD_TOKEN="your-token"
teactl local start --provider=hetzner

What Happens

  1. Pulls/uses the teabar-operator Docker image
  2. Creates a container with your provider credentials
  3. Container connects to Teabar daemon via gRPC/mTLS
  4. Operator polls for jobs and executes them locally
  5. Infrastructure state persisted between restarts

teactl local stop

Stop a running local operator.

teactl local stop [provider] [flags]

Flags

FlagShortDescription
--allStop all local operators
--forceSkip confirmation prompt

Examples

# Stop Proxmox operator (with confirmation)
teactl local stop proxmox

# Stop without confirmation
teactl local stop --force

# Stop all operators
teactl local stop --all

teactl local status

Show status of all local operators.

teactl local status

Example Output

Local Operators:
================

Provider:     proxmox
Cluster ID:   local-proxmox-1678901234
Status:       running
Started:      2024-01-15T09:30:00Z
Infrastructure: 3 resources
                - vm-100 (web-server)
                - vm-101 (database)
                - cluster-dev-k8s

Provider:     hetzner
Cluster ID:   local-hetzner-1678901245
Status:       stopped
Started:      2024-01-15T08:00:00Z
Infrastructure: 0 resources

teactl local logs

View local operator logs.

teactl local logs [provider] [flags]

Flags

FlagShortDescription
--follow-fFollow log output (like tail -f)
--tail-nNumber of lines to show [default: 100]

Examples

# View last 100 lines
teactl local logs

# Follow logs in real-time
teactl local logs -f

# View last 50 lines
teactl local logs --tail=50

# Specific provider
teactl local logs proxmox -f

teactl local restart

Restart a local operator (useful for development).

teactl local restart [provider]

When to Use

  • After updating the operator Docker image
  • When changing provider credentials
  • To clear temporary issues
  • During development with hot-reload

Examples

# Restart Proxmox operator
teactl local restart proxmox

# Restart all operators
teactl local restart

teactl local config

Configure local infrastructure providers.

teactl local config [provider]

Examples

# Configure Proxmox interactively
teactl local config proxmox

# Currently supports environment variables only
# Edit ~/.config/teactl/proxmox.yaml manually for file-based config

Environment Variables

Configure your local providers via environment variables:

Proxmox

# Required
export TEABAR_PROXMOX_URL=https://pve.local:8006
export TEABAR_PROXMOX_TOKEN_ID="root@pam!tokenname"
export TEABAR_PROXMOX_SECRET="token-secret"

# Optional
export TEABAR_PROXMOX_TLS_INSECURE=true  # For self-signed certs

Hetzner

# Required
export TEABAR_HCLOUD_TOKEN="your-hetzner-token"

Daemon Connection

# The URL where teactl should connect
export TEABAR_API_URL=https://daemon.teabar.io

# For local development
export TEABAR_API_URL=http://localhost:8000

Development Mode

Use --dev flag for active development:

teactl local start --provider=proxmox --dev

Features:

  • Container persists when you stop (for debugging)
  • Press Ctrl+C to stop interactively
  • Shows real-time logs
  • Easier troubleshooting

Production Mode (default):

  • Container runs in background
  • Use teactl local stop to stop
  • Better for long-running environments

Architecture

┌─────────────────────────────────────────────────────┐
│  Your Machine                                        │
│                                                      │
│  ┌──────────────┐                                   │
│  │   teactl     │◄────── HTTP/gRPC ─────────┐       │
│  │   (CLI)      │                          │       │
│  └──────┬───────┘                          │       │
│         │                                  │       │
│         │     ┌────────────────────────────┼───┐   │
│         │     │                            │   │   │
│         ▼     ▼                            │   │   │
│  ┌─────────────────────────────────────┐  │   │   │
│  │  Docker Container                   │  │   │   │
│  │  ┌───────────────────────────────┐  │  │   │   │
│  │  │   teabar-operator             │  │  │   │   │
│  │  │   - Polls daemon for jobs     │  │  │   │   │
│  │  │   - Runs Terraform            │──┘   │   │   │
│  │  └───────────────────────────────┘       │   │   │
│  └──────────────┬────────────────────────────┘   │   │
│                 │                                │   │
│                 │ HTTPS/HTTP                     │   │
│                 ▼                                │   │
│  ┌──────────────────────────────┐               │   │
│  │   Proxmox/Docker/K8s         │               │   │
│  │   (Local Infrastructure)     │               │   │
│  └──────────────────────────────┘               │   │
└──────────────────────────────────────────────────┼───┘
                                                   │
                          gRPC/mTLS               │
                                                   ▼
                                          ┌──────────────────┐
                                          │   Teabar Daemon  │
                                          │   (SaaS Backend) │
                                          └──────────────────┘

Best Practices

For Development

  1. Use --dev mode - Easier debugging and log access
  2. Check logs frequently - teactl local logs -f
  3. Clean up resources - Destroy environments before stopping operator
  4. Use environment variables - Don’t commit credentials

For Production

  1. Use cloud operators - Not local operators
  2. Proper TLS - Valid certificates, not --tls-insecure
  3. Credential management - Use OpenBao/Vault for secrets
  4. Monitoring - Set up alerts for operator health

Security

# Good - credentials from environment
export TEABAR_PROXMOX_SECRET="$(cat /run/secrets/proxmox)"
teactl local start

# Bad - credentials in command history
teactl local start --proxmox-secret="secret123"

Troubleshooting

“No local operators running”

Check if the operator is actually running:

teactl local status
docker ps | grep teabar-operator

“Cannot connect to daemon”

Verify daemon URL is configured:

teactl config get api_url
# Should show your daemon URL

# Or set explicitly
export TEABAR_API_URL=https://daemon.teabar.io

“Provider credentials not found”

Check environment variables are set:

env | grep TEABAR_PROXMOX
# Should show your credentials

Operator keeps crashing

Check logs for errors:

teactl local logs --tail=500

# Look for:
# - Connection errors to Proxmox
# - Permission denied errors
# - Network connectivity issues

Cleanup stuck operators

If operators are stuck in a bad state:

# Stop all operators
teactl local stop --all --force

# Clean up Docker containers manually
docker ps -a | grep teabar-operator
docker rm -f <container-id>

# Clear state files
rm -rf ~/.local/share/teabar/local-operator/

Examples

Workshop Setup

# Start operator for workshop
teactl local start --provider=proxmox

# Create 5 identical environments
for i in {1..5}; do
  teactl env create --blueprint workshop 
    --name "workshop-participant-$i" 
    --set participant_id=$i
done

# Share participant links
teactl env participants workshop-participant-1 -o links

CI/CD Testing

# Test blueprint in CI
export TEABAR_PROXMOX_URL=https://pve.ci.local:8006
export TEABAR_PROXMOX_TOKEN_ID="ci@pam!token"
export TEABAR_PROXMOX_SECRET="$PROXMOX_SECRET"

# Start operator
teactl local start

# Test blueprint
teactl env create -f blueprint.yaml --name ci-test-$BUILD_ID

# Run tests
./run-tests.sh

# Cleanup
teactl env destroy ci-test-$BUILD_ID --force
teactl local stop

Development Workflow

# Terminal 1: Start operator in dev mode
teactl local start --dev

# Terminal 2: Edit blueprint and test loop
while true; do
  teactl env create -f my-blueprint.yaml --name dev-test
  # Test changes
  teactl env destroy dev-test --force
  sleep 5
done

See Also

ende