git.stella-ops.org/docs/guides/agent-operations-quickstart.md

Agent Operations Quick Start

This guide covers deploying, configuring, and maintaining Stella Ops agents at scale.

Zero-Touch Bootstrap

Deploy agents with a single command using bootstrap tokens.

Generate Bootstrap Token

# Generate token and get install command
stella agent bootstrap --name prod-agent-01 --env production

# Output includes platform-specific one-liners:
# Linux:   curl -fsSL https://... | STELLA_TOKEN="..." bash
# Windows: $env:STELLA_TOKEN='...'; iwr -useb https://... | iex
# Docker:  docker run -d -e STELLA_TOKEN="..." stellaops/agent:latest

Custom Capabilities

stella agent bootstrap \
  --name prod-agent-01 \
  --env production \
  --capabilities docker,compose,helm \
  --output install-token.txt

Configuration Management

View Current Configuration

# Show current config in YAML format
stella agent config

# Show as JSON
stella agent config --format json

Detect Configuration Drift

# Check for drift between current and desired state
stella agent config --diff

Apply New Configuration

# agent-config.yaml
identity:
  agentId: agent-abc123
  agentName: prod-agent-01
  environment: production

connection:
  orchestratorUrl: https://orchestrator.example.com
  heartbeatInterval: 30s

capabilities:
  docker: true
  scripts: true
  compose: true

resources:
  maxConcurrentTasks: 10
  workDirectory: /var/lib/stella-agent

security:
  certificate:
    source: AutoProvision

# Validate without applying
stella agent apply -f agent-config.yaml --dry-run

# Apply configuration
stella agent apply -f agent-config.yaml

Agent Health Diagnostics (Doctor)

Run Local Diagnostics

# Run all health checks
stella agent doctor

# Filter by category
stella agent doctor --category security
stella agent doctor --category network
stella agent doctor --category runtime
stella agent doctor --category resources
stella agent doctor --category configuration

Apply Automated Fixes

# Run diagnostics and apply fixes
stella agent doctor --fix

Output Formats

# Table output (default)
stella agent doctor

# JSON output for scripting
stella agent doctor --format json

# YAML output
stella agent doctor --format yaml

Certificate Management

Check Certificate Status

stella agent cert-status

Renew Certificate

# Renew if nearing expiry
stella agent renew-cert

# Force renewal
stella agent renew-cert --force

Agent Updates

Check for Updates

stella agent update --check

Apply Updates

# Update to latest
stella agent update

# Update to specific version
stella agent update --version 1.3.0

# Force update outside maintenance window
stella agent update --force

Rollback

# Rollback to previous version
stella agent rollback

Health Check Categories

Category	Checks
Security	Certificate expiry, certificate validity
Network	Orchestrator connectivity, DNS resolution
Runtime	Docker daemon, task queue depth
Resources	Disk space, memory usage, CPU usage
Configuration	Configuration drift

Troubleshooting

Common Issues

Certificate Expired

stella agent renew-cert --force

Docker Not Accessible

# Check Docker socket
ls -la /var/run/docker.sock

# Add agent to docker group
sudo usermod -aG docker stella-agent
sudo systemctl restart stella-agent

Disk Space Low

# Clean up Docker resources
docker system prune -af --volumes

# Check agent work directory
du -sh /var/lib/stella-agent

Connection Issues

# Check DNS
nslookup orchestrator.example.com

# Check port
telnet orchestrator.example.com 443

# Check firewall
sudo iptables -L -n | grep 443

Fleet Monitoring

The orchestrator Doctor plugin monitors all agents:

• Heartbeat Freshness: Alerts on stale heartbeats
• Certificate Expiry: Warns before fleet certificates expire
• Version Consistency: Detects version skew across agents
• Capacity: Monitors task queue and agent load
• Failed Task Rate: Alerts on high failure rates

Access via:

stella doctor run --plugin agent-health