🤖 Agent Quick Start - Start Here¶

Lost? Start here. It's a 2-minute read.

What You Need to Know in 30 Seconds¶

You can't edit files directly - They're read-only
Use the REST API instead - It's simple and safe
Documentation is your friend - Read the guides below
Still stuck? - Run /opt/charliehub/agent-help

Which Guide Do I Read?¶

🚀 I want to make changes (Create/Update/Delete domains)¶

→ Read: AGENT_API_GUIDE.md - Complete REST API documentation - curl examples for everything - Python client library (ready to copy-paste) - Troubleshooting tips

Quick example:

export DOMAIN_MANAGER_API_KEY="your_key_here"
curl -H "X-API-Key: $API_KEY" http://172.19.0.5:8001/api/domains

❌ I got an error ("Permission denied", "Connection refused", etc.)¶

→ Read: AGENT_TROUBLESHOOTING.md - Explains every error you might encounter - Shows the correct way to do it - Organized by error number for easy lookup

Common errors: - "Permission denied" → Use the API - "Connection refused" → Use the API - "401 Unauthorized" → Set your API key - "422 Unprocessable Entity" → Check JSON syntax

🆘 I'm confused and need quick help¶

→ Run: /opt/charliehub/agent-help - Quick reference - Checks if your API key is set - Tests if the API is responding - Points to the right documentation

Quick File Locations¶

Document	Purpose	Location
AGENT_API_GUIDE.md	How to use REST API	`/opt/charliehub/AGENT_API_GUIDE.md`
AGENT_TROUBLESHOOTING.md	Error explanations	`/opt/charliehub/AGENT_TROUBLESHOOTING.md`
agent-help	Quick help script	`/opt/charliehub/agent-help`
AGENT_START_HERE.md	This file	`/opt/charliehub/AGENT_START_HERE.md`

The Pattern You'll Use¶

You want to make a change

curl -X POST http://172.19.0.5:8001/api/domains \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{...domain config...}'

API validates and applies your change
Checks your API key
Validates all fields
Updates the database
Auto-generates config files

Changes are automatically deployed

curl -X POST http://172.19.0.5:8001/api/deploy-all \
  -H "X-API-Key: $API_KEY"

You verify it worked

curl https://yourdomain.charliehub.net/

Why Files Are Read-Only¶

✅ Prevents accidental corruption - One typo won't break everything ✅ Enforces validation - Invalid configs are caught before applying ✅ Maintains audit trail - Every change is logged ✅ Enables rollback - Easy to revert if needed ✅ Simplifies permissions - One API, consistent access control

This isn't a restriction - it's protection.

Getting Your API Key¶

# Check if it's already set
echo $DOMAIN_MANAGER_API_KEY

# If empty:
# 1. Ask your DevOps engineer
# 2. They'll give you a key like: YOUR_API_KEY_HERE
# 3. Set it:
export DOMAIN_MANAGER_API_KEY="YOUR_API_KEY_HERE"

# ⚠️  IMPORTANT:
# - Never hardcode it in your scripts
# - Never commit it to git
# - Store it in .bashrc or .env (git-ignored)

The Most Common Scenarios¶

Scenario 1: Add a new domain¶

curl -X POST http://172.19.0.5:8001/api/domains \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "myservice.charliehub.net",
    "service_type": "http",
    "environment": "production",
    "backend_host": "10.44.1.100",
    "backend_port": 8080,
    "cors_enabled": false,
    "auth_required": true
  }'

# Then deploy:
curl -X POST http://172.19.0.5:8001/api/deploy-all \
  -H "X-API-Key: $API_KEY"

Scenario 2: Change a domain's backend¶

# First, get the domain ID
DOMAIN_ID=24

# Update it:
curl -X PUT http://172.19.0.5:8001/api/domains/$DOMAIN_ID \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "control.trevarn.com",
    "backend_host": "10.44.1.200",  # New IP
    "backend_port": 8080,
    ...rest of fields...
  }'

# Then deploy:
curl -X POST http://172.19.0.5:8001/api/deploy-all \
  -H "X-API-Key: $API_KEY"

Scenario 3: Make a domain public (no auth required)¶

curl -X PUT http://172.19.0.5:8001/api/domains/24 \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "public.charliehub.net",
    "service_type": "http",
    "environment": "production",
    "backend_host": "10.44.1.100",
    "backend_port": 8080,
    "cors_enabled": false,
    "auth_required": false  # ← This makes it public
  }'

Troubleshooting Decision Tree¶

I got an error
│
├─ "Permission denied" when editing a file
│  → Read AGENT_TROUBLESHOOTING.md - Error 1
│  → Solution: Use the API
│
├─ "Connection refused" when connecting to database
│  → Read AGENT_TROUBLESHOOTING.md - Error 2
│  → Solution: Use the API
│
├─ "401 Unauthorized"
│  → Read AGENT_TROUBLESHOOTING.md - Error 5
│  → Solution: Set your API_KEY
│
├─ "422 Unprocessable Entity"
│  → Read AGENT_TROUBLESHOOTING.md - Error 6
│  → Solution: Check JSON syntax, add Content-Type header
│
├─ "409 Conflict - Domain already exists"
│  → Read AGENT_TROUBLESHOOTING.md - Error 7
│  → Solution: Use PUT to update, not POST to create
│
└─ Something else
   → Read AGENT_TROUBLESHOOTING.md (find your error)
   → Or run: /opt/charliehub/agent-help

Remember¶

The Golden Rule:

API = Safe, Validated, Audited, Simple
Direct file/DB access = Forbidden

Your workflow: 1. Learn API (read AGENT_API_GUIDE.md) - 20 minutes 2. Copy example from guide 3. Replace values with your data 4. Run it 5. Verify it worked

That's it. Every time.

🆘 Need Help?¶

Quick help: /opt/charliehub/agent-help
API Guide: AGENT_API_GUIDE.md
Got an error? AGENT_TROUBLESHOOTING.md
Confused? Ask your DevOps engineer
Found a bug? Report it through your team

Next Step: Open AGENT_API_GUIDE.md and find your use case. It's that simple.

Last updated: 2026-02-08