# 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

```bash
# 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

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

## Configuration Management

### View Current Configuration

```bash
# Show current config in YAML format
stella agent config

# Show as JSON
stella agent config --format json
```

### Detect Configuration Drift

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

### Apply New Configuration

```yaml
# 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
```

```bash
# 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

```bash
# 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

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

### Output Formats

```bash
# 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

```bash
stella agent cert-status
```

### Renew Certificate

```bash
# Renew if nearing expiry
stella agent renew-cert

# Force renewal
stella agent renew-cert --force
```

## Agent Updates

### Check for Updates

```bash
stella agent update --check
```

### Apply Updates

```bash
# 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

```bash
# 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**
```bash
stella agent renew-cert --force
```

**Docker Not Accessible**
```bash
# 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**
```bash
# Clean up Docker resources
docker system prune -af --volumes

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

**Connection Issues**
```bash
# 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:
```bash
stella doctor run --plugin agent-health
```