Crystal Agents - User Documentation

Introduction

Crystal Agents is a workflow-driven agent stack designed for structured business automation on a single VPS. It provides specialized AI agents with controlled tool access, approval gates for risky actions, run artifacts/logs, and a local dashboard for managing workflows.

Getting Started

Installation

# Create virtual environment
python -m venv .venv

# Activate (Windows)
.venv\Scripts\activate

# Activate (Linux/Mac)
source .venv/bin/activate

# Install dependencies
python -m pip install --upgrade pip
pip install -e .

Configuration

All runtime settings are configured in config/config.json. The key configuration sections are:

• telegram: Enable/disable Telegram bot notifications
• model: Configure the AI model (provider, name, temperature, etc.)
• scheduler: Configure scheduled jobs and allowed script roots
• git: Configure Git workspace and repository settings
• agent_models: Configure individual models per agent type

Environment Variables

For secrets, use environment variables rather than hardcoding in config:

• CRYSTAL_AGENTS_BOT_TOKEN - Telegram bot token
• GOOGLE_API_KEY or GEMINI_API_KEY - Google/Gemini API key
• OPENAI_API_KEY - OpenAI API key
• GITHUB_TOKEN - GitHub token for PR creation

Running Workflows

CLI Commands

# Run a workflow task
python -m orchestrator.cli run --task content --prompt "Draft a launch post."

# Available task types:
# - content
# - feature-spec
# - content-review
# - lead_followup
# - campaign_creation
# - bug_triage
# - release_preparation
# - customer_reporting
# - proposal_generation

# Start the dashboard
python -m orchestrator.cli dashboard --host 0.0.0.0 --port 8000

# Generate summary reports
python -m orchestrator.cli reports

# Manage scheduler
python -m orchestrator.cli scheduler list
python -m orchestrator.cli scheduler run-due
python -m orchestrator.cli scheduler loop --interval 60

Dashboard

The dashboard provides a web interface at http://127.0.0.1:8000/ with the following features:

• Home (/) - View recent runs and trigger new workflows
• Approvals (/approvals) - Review and approve/deny pending actions
• Daily Summary (/reports/daily) - View daily activity report
• Weekly Summary (/reports/weekly) - View weekly activity report
• Scheduler (/scheduler) - Monitor and trigger scheduled jobs
• Run Details (/runs/{run_id}) - View individual run artifacts

Telegram Bot

Start the Telegram bot for natural language workflow triggering:

python -m orchestrator.cli telegram

You can send prompts like “Write a LinkedIn post about AI automation” and the CEO router will map it to the appropriate workflow.

Understanding Workflows

Available Workflows

Agent Types

Each workflow uses specialized agents with specific tool permissions:

• CEO - Routes tasks to appropriate workflows
• Developer - Code writing and repo operations
• Tester - Test execution and validation
• Research - Web search and information gathering
• Content - Content creation and writing
• Reviewer - Code and content review
• DevOps - Deployment and infrastructure tasks
• Ads Manager - Advertising campaign management
• Sales Assistant - Sales-related tasks
• SEO - Search engine optimization
• Analytics - Data analysis and reporting

Working with Approvals

Approval Requirements

Certain tools require approval before execution:

• repo_writer - Writing files to the filesystem
• git_ops - Git operations (commit, push, PR creation)

Managing Approvals

1. When an agent requests an approval-required action, it’s logged in logs/approvals.jsonl
2. Approve or deny through the dashboard at /approvals
3. Approved actions are recorded with the decision maker and timestamp

Scheduler

Configuration

Add jobs to config/config.json under scheduler.jobs:

{
  "name": "daily_report",
  "schedule": "0 9 * * *",
  "script": "scripts/daily_report.sh",
  "cwd": "scripts",
  "enabled": true,
  "requires_approval": false,
  "description": "Generate daily business report"
}

Security

• Scripts must be under allowed script roots (configured in allowed_script_roots)
• Jobs can optionally require approval before execution
• All executions are logged to logs/scheduler_history.jsonl

Output Locations

• runs/ - Workflow execution results and artifacts
• logs/ - Runtime logs, summaries, and approval records
• logs/scheduler_runs/ - Scheduler execution manifests
• generated/ - Approved workflow outputs

Docker Deployment

# Build and run
docker compose up --build

# Run a one-off workflow
docker compose run --rm crystal-agents run --task content --prompt "Draft a post."

Testing

# Run all tests
python -m unittest discover -s tests

# Run specific test file
python -m unittest tests.test_workflows

Troubleshooting

Common Issues

1. API key not set: Ensure environment variables are properly configured
2. Dashboard not accessible: Check if port 8000 is available
3. Scheduler jobs not running: Verify cron syntax and script paths
4. Approval not working: Check logs/approvals.jsonl for details

Logs

• Check logs/ for runtime logs
• Check logs/scheduler_history.jsonl for scheduler activity
• Check runs/{run_id}/ for workflow-specific artifacts