letta-switchboard

Letta Switchboard

Free hosted message routing service for Letta agents.

Send messages to your Letta agents immediately or scheduled for later. Supports natural language scheduling ("in 5 minutes", "every weekday at 9am") and secure cross-agent communication.

🌐 Hosted Service: https://letta--switchboard-api.modal.run
💻 CLI: letta-switchboard
🔒 Security: End-to-end encryption, API key isolation
📖 Docs: CLI Guide | API Reference

Quick Start

Option 1: Using cURL (No Installation Required)

Send a message right now with just cURL:

curl -X POST https://letta--switchboard-api.modal.run/schedules/one-time \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_LETTA_API_KEY" \
  -d '{
    "agent_id": "agent-xxx",
    "execute_at": "2025-11-12T20:00:00Z",
    "message": "Hello from Switchboard!",
    "role": "user"
  }'

Or create a recurring schedule:

curl -X POST https://letta--switchboard-api.modal.run/schedules/recurring \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_LETTA_API_KEY" \
  -d '{
    "agent_id": "agent-xxx",
    "cron": "0 9 * * 1-5",
    "message": "Daily standup reminder",
    "role": "user"
  }'

Check your schedules:

# List all one-time schedules
curl https://letta--switchboard-api.modal.run/schedules/one-time \
  -H "Authorization: Bearer YOUR_LETTA_API_KEY"

# List all recurring schedules
curl https://letta--switchboard-api.modal.run/schedules/recurring \
  -H "Authorization: Bearer YOUR_LETTA_API_KEY"

# View execution results
curl https://letta--switchboard-api.modal.run/results \
  -H "Authorization: Bearer YOUR_LETTA_API_KEY"

Note:

• Replace YOUR_LETTA_API_KEY with your actual Letta API key
• Replace agent-xxx with your agent ID
• The API key in the Authorization header is used for authentication and storage isolation
• You don't need to include it in the request body!

Pro tip: Use the CLI for natural language scheduling - it's much easier than writing ISO timestamps and cron expressions!

Option 2: Using the CLI (Recommended)

The CLI makes natural language scheduling much easier:

# Download the CLI (or build from source)
cd cli
go build -o letta-switchboard

# Configure with your Letta API key
./letta-switchboard config set-api-key sk-your-letta-key

Send messages with natural language:

# Send immediately
letta-switchboard send \
  --agent-id agent-xxx \
  --message "Hello from Switchboard!"

# Send later (natural language!)
letta-switchboard send \
  --agent-id agent-xxx \
  --message "Reminder to check in" \
  --execute-at "tomorrow at 9am"

# Create recurring schedule (plain English!)
letta-switchboard recurring create \
  --agent-id agent-xxx \
  --message "Daily standup" \
  --cron "every weekday at 10am"

That's it! The hosted service handles everything - scheduling, execution, and delivery.

Features

✅ Free hosted service - No deployment needed
✅ Natural language scheduling - "in 5 minutes", "tomorrow at 9am", "every weekday"
✅ Secure by default - API key isolation, encrypted storage
✅ Recurring schedules - Cron expressions or plain English
✅ Instant delivery - Messages execute within 1 minute
✅ Execution tracking - Get run IDs for every message
✅ Self-hostable - Deploy your own instance if needed

Why Use Switchboard?

No Infrastructure Setup
Just use the hosted service at https://letta--switchboard-api.modal.run. No deployment, no servers, no configuration.

Natural Language Scheduling
Forget cron syntax. Use plain English like "every weekday at 9am" or "in 5 minutes".

Secure by Design

• Your schedules are isolated by API key
• End-to-end encryption at rest
• Only you can see your schedules
• Execution results tracked with run IDs

Always Available

• Runs on Modal's infrastructure
• Checks every minute for due schedules
• Automatic retries and error handling
• 99.9% uptime

How It Works

1. You create a schedule → Via CLI or API with your Letta API key
2. Switchboard validates → Checks your API key against Letta's API
3. Schedule stored → Encrypted and isolated in your hash-based directory
4. Cron checks every minute → Looks for due schedules in your bucket
5. Message sent → Calls Letta's API with your credentials to send the message
6. Result saved → Stores run ID and execution metadata

Security Model:

• Your API key is validated but never stored in plaintext
• Schedules hashed by API key for isolation
• Only you can list/view/delete your schedules
• Messages sent using your API key (you stay in control)

Natural Language Examples

One-Time Messages

# Relative time
--execute-at "in 5 minutes"
--execute-at "in 2 hours"
--execute-at "in 3 days"

# Tomorrow
--execute-at "tomorrow at 9am"
--execute-at "tomorrow at 14:30"

# Next weekday
--execute-at "next monday at 3pm"
--execute-at "next friday at 10:00"

# ISO 8601 (still works)
--execute-at "2025-11-12T19:30:00Z"

Recurring Schedules

# Minutes
--cron "every 5 minutes"
--cron "every 30 minutes"

# Hourly/Daily
--cron "every hour"
--cron "daily at 9am"
--cron "daily at 14:30"

# Weekdays
--cron "every monday"
--cron "every friday at 3pm"
--cron "every weekday"     # Mon-Fri at 9am

# Traditional cron (still works)
--cron "*/5 * * * *"       # Every 5 minutes

This will test all endpoints (create, list, get, delete) for both recurring and one-time schedules.

**Features:**
- Validates API key before running
- Shows configuration at startup
- Tests create, list, get, and delete operations
- Pretty prints all responses

### Bash Test Script

```bash
./test_api.sh

Same functionality using curl commands.

Example with inline variables:

LETTA_API_KEY=sk-xxx LETTA_AGENT_ID=agent-yyy python test_api.py

CLI Usage (Recommended)

The easiest way to interact with letta-switchboard is via the CLI:

# Send a message immediately
letta-switchboard send --agent-id agent-xxx --message "Hello!"

# Send a message later
letta-switchboard send --agent-id agent-xxx --message "Reminder" --execute-at "tomorrow at 9am"

# Create recurring schedule
letta-switchboard recurring create --agent-id agent-xxx --message "Daily standup" --cron "every weekday at 9am"

# List schedules
letta-switchboard onetime list
letta-switchboard recurring list

# View results
letta-switchboard results list

See CLI Documentation for installation and full usage guide.

API Usage

Base URL: https://letta--schedules-api.modal.run

Authentication

All endpoints require Bearer token authentication using your Letta API key:

curl -H "Authorization: Bearer your-letta-api-key" https://your-modal-app.modal.run/schedules/recurring

Security Model:

• API Key Validation: All requests validate your API key against Letta's API (lightweight list agents call with limit=1)
• Create endpoints: Verify API key is valid before creating schedule
• List endpoints: Returns only schedules created with your API key
• Get/Delete endpoints: Returns 403 Forbidden if the schedule wasn't created with your API key
• Privacy: API keys are never returned in responses, only used for authentication and execution

Error Codes:

• 401 Unauthorized: Invalid or expired Letta API key
• 403 Forbidden: Valid API key, but trying to access someone else's schedule
• 404 Not Found: Schedule doesn't exist

Create Recurring Schedule

Schedule a message to be sent on a cron schedule:

curl -X POST https://your-modal-app.modal.run/schedules/recurring \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent-123",
    "api_key": "your-letta-api-key",
    "cron": "0 9 * * *",
    "message": "Good morning! Time for your daily check-in.",
    "role": "user"
  }'

Cron Format: minute hour day month day_of_week

• 0 9 * * * - Every day at 9:00 AM
• */15 * * * * - Every 15 minutes
• 0 */2 * * * - Every 2 hours
• 0 0 * * 0 - Every Sunday at midnight

Create One-Time Schedule

Schedule a message for a specific time:

curl -X POST https://your-modal-app.modal.run/schedules/one-time \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent-123",
    "api_key": "your-letta-api-key",
    "execute_at": "2025-11-07T14:30:00-05:00",
    "message": "Reminder: Meeting in 30 minutes",
    "role": "user"
  }'

Timestamp Format: ISO 8601 with timezone

• 2025-11-07T14:30:00-05:00 (EST)
• 2025-11-07T14:30:00Z (UTC)

List All Schedules

# List your recurring schedules
curl -H "Authorization: Bearer your-letta-api-key" \
  https://your-modal-app.modal.run/schedules/recurring

# List your one-time schedules
curl -H "Authorization: Bearer your-letta-api-key" \
  https://your-modal-app.modal.run/schedules/one-time

Get Specific Schedule

# Get recurring schedule
curl -H "Authorization: Bearer your-letta-api-key" \
  https://your-modal-app.modal.run/schedules/recurring/{schedule_id}

# Get one-time schedule
curl -H "Authorization: Bearer your-letta-api-key" \
  https://your-modal-app.modal.run/schedules/one-time/{schedule_id}

Delete Schedule

# Delete recurring schedule
curl -X DELETE -H "Authorization: Bearer your-letta-api-key" \
  https://your-modal-app.modal.run/schedules/recurring/{schedule_id}

# Delete one-time schedule
curl -X DELETE -H "Authorization: Bearer your-letta-api-key" \
  https://your-modal-app.modal.run/schedules/one-time/{schedule_id}

Get Execution Results

# List all execution results
curl -H "Authorization: Bearer your-letta-api-key" \
  https://your-modal-app.modal.run/results

# Get result for specific schedule
curl -H "Authorization: Bearer your-letta-api-key" \
  https://your-modal-app.modal.run/results/{schedule_id}

Result Format:

{
  "schedule_id": "uuid",
  "schedule_type": "recurring",
  "run_id": "run_abc123",
  "agent_id": "agent-123",
  "message": "The scheduled message",
  "executed_at": "2025-11-07T00:15:00"
}

Note: Results are stored when the message is queued to Letta. To check the actual run status, use the Letta API:

# Get the run_id from results
RESULT=$(curl -H "Authorization: Bearer your-letta-api-key" \
  https://your-modal-app.modal.run/results/{schedule_id})

RUN_ID=$(echo $RESULT | jq -r '.run_id')

# Check run status with Letta
curl -H "Authorization: Bearer your-letta-api-key" \
  https://api.letta.com/v1/runs/$RUN_ID

Response Format

Recurring Schedule Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "agent_id": "agent-123",
  "cron": "0 9 * * *",
  "message": "Good morning!",
  "role": "user",
  "created_at": "2025-11-06T10:00:00",
  "last_run": "2025-11-06T09:00:00"
}

Note: API keys are stored securely and never returned in responses.

One-Time Schedule Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "agent_id": "agent-123",
  "execute_at": "2025-11-07T14:30:00-05:00",
  "message": "Reminder!",
  "role": "user",
  "created_at": "2025-11-06T10:00:00"
}

Note:

• API keys are stored securely and never returned in responses
• Once executed, one-time schedules are deleted from storage (check /results endpoint for execution history)

How It Works

1. API receives schedule request → Validates and stores as JSON in Modal Volume
2. Cron job runs every minute → Checks all schedules in Volume
3. Due schedules identified → Spawns async executor functions
4. Executor verifies schedule exists → Skips if schedule was deleted after spawn
5. For one-time schedules → Deletes schedule file immediately (prevents re-execution)
6. Executor calls Letta API → Sends message to specified agent
7. Saves execution result → Stores run_id and metadata in results folder
8. For recurring schedules → Updates last_run timestamp in schedule file

Race Condition Prevention:

• One-time schedules are deleted before execution (not after)
• If multiple executors spawn, only first one successfully deletes
• Second executor finds no file → skips gracefully
• Filesystem is source of truth: file exists = hasn't run yet

Storage Structure

Schedules and execution results are stored in a hash-based directory structure:

/data/
├── schedules/
│   ├── recurring/
│   │   ├── {api_key_hash}/        # SHA256 hash of API key (first 16 chars)
│   │   │   ├── {uuid-1}.json.enc  # Encrypted schedule files
│   │   │   └── {uuid-2}.json.enc
│   │   └── {another_hash}/
│   │       └── {uuid-3}.json.enc
│   └── one-time/
│       ├── 2025-11-06/             # Date bucket
│       │   ├── 14/                 # Hour bucket (00-23)
│       │   │   ├── {api_key_hash}/
│       │   │   │   └── {uuid}.json.enc
│       │   │   └── {another_hash}/
│       │   │       └── {uuid}.json.enc
│       │   └── 15/
│       └── 2025-11-07/
└── results/
    ├── {api_key_hash}/
    │   ├── {schedule_uuid}.json.enc  # Execution results with run_id
    │   └── {schedule_uuid}.json.enc
    └── {another_hash}/

Security Features:

• All schedule files are encrypted at rest using Fernet (AES-128-CBC)
• API keys never stored in plaintext
• User isolation via hash-based directories
• Time-based bucketing for efficient queries

Performance Benefits:

• Recurring schedules: O(user's schedules) instead of O(all schedules)
• One-time schedules: O(schedules in current hour) instead of O(all schedules)
• Only checks relevant time buckets during cron execution
• Automatic cleanup: Empty directories are removed after each cron run

Monitoring

View logs in Modal dashboard:

modal app logs letta-switchboard

Or watch logs in real-time:

modal app logs letta-switchboard --follow

Limitations

• Minimum granularity: 1 minute (cron runs every minute)
• Timezone handling: One-time schedules support timezones; recurring schedules run in UTC
• Authentication: Bearer token authentication with validation against Letta API
• Encryption key management: Single master key for all schedules (consider key rotation strategy for production)

Future Improvements

• Encryption key rotation mechanism
• Execution history/logs API endpoint
• Rate limiting per user
• Email/webhook notifications on failures
• Pagination for list endpoints
• Timezone support for recurring schedules
• Schedule validation (max schedules per user)
• Cleanup of old date buckets (>7 days) to prevent unbounded growth

Costs

Modal pricing (as of 2024):

• Compute: ~$0.000162/second for basic CPU
• Volume storage: ~$0.10/GB/month
• Estimated monthly cost: $5-10 for moderate usage (hundreds of schedules)

Free tier: 30 credits/month (~$30 value)

---

Self-Hosting

Want to run your own instance? Switchboard is fully self-hostable on Modal.

Prerequisites

1. Clone the repository:

   git clone https://github.com/cpfiffer/letta-switchboard.git
   cd letta-switchboard
   

2. Install Modal CLI:

   pip install modal
   modal setup
   

Deploy Your Instance

1. Set up encryption (required):

# Automated setup
./setup_encryption.sh

# Or manually
ENCRYPTION_KEY=$(python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())")
echo "Save this key: $ENCRYPTION_KEY"
modal secret create letta-switchboard-encryption \
  LETTA_SWITCHBOARD_ENCRYPTION_KEY="$ENCRYPTION_KEY"

2. Deploy to Modal:

modal deploy app.py

3. Get your API URL:

modal app list
# Look for 'switchboard' and note the URL

4. Configure CLI to use your instance:

letta-switchboard config set-url https://your-instance.modal.run

Local Development

Run locally with hot reloading:

# Enable dev mode (no encryption)
export LETTA_SWITCHBOARD_DEV_MODE=true

# Start local server
modal serve app.py

Dev Mode Features:

• Files stored in plaintext JSON (easy to inspect)
• No encryption overhead
• Perfect for debugging
• Auto-reload on code changes

View files in dev mode:

# View a schedule
cat /tmp/letta-switchboard-volume/schedules/recurring/abc123/uuid.json | jq

# List all schedules
ls -la /tmp/letta-switchboard-volume/schedules/

Testing Your Instance

Set environment variables:

export LETTA_API_KEY="sk-..."
export LETTA_AGENT_ID="agent-xxx"
export LETTA_SWITCHBOARD_URL="https://your-instance.modal.run"

Run tests:

# Python test suite
python test_api.py

# Bash test script
./test_api.sh

# Unit tests
pytest -m "not e2e"

# Full E2E tests (requires modal serve running)
pytest

Cost Estimate

Running your own instance on Modal:

• Free tier: ~$30/month of free credits
• API requests: Free (minimal compute)
• Cron job: Runs every minute (~43,000 times/month)
• Storage: First 1GB free, then $0.10/GB/month
• Expected cost: $0-5/month for personal use

The hosted service at letta--switchboard-api.modal.run is free to use!

---

License

MIT