Security

Security considerations and best practices for Calliope CLI.

API Key Security

Storage Options

Recommended: Environment Variables

export ANTHROPIC_API_KEY="sk-ant-..."

Environment variables are:

• Not persisted to disk (unless in shell config)
• Not accessible to other processes easily
• Easy to rotate

Alternative: Config File

Keys entered during setup are stored in ~/.config/calliope/config.json.

To secure the config file:

chmod 600 ~/.config/calliope/config.json

Key Rotation

If you suspect a key is compromised:

1. Revoke the key at your provider’s dashboard
2. Generate a new key
3. Update your configuration:

   # If using environment variable
   export ANTHROPIC_API_KEY="new-key-here"
   
   # If using config file
   calliope --setup

Don’t Commit Keys

Add to .gitignore:

# Calliope config
.env
.env.local

Use .env.example for documentation:

# .env.example (safe to commit)
ANTHROPIC_API_KEY=
OPENAI_API_KEY=

Execution Security

Path Traversal Protection

File operations are restricted to safe directories:

Allowed:

• Current working directory and subdirectories
• Home directory (~) and subdirectories

Blocked:

• System directories (/etc, /usr, /var)
• Other users’ directories
• Path traversal attempts (../../../etc/passwd)

Example:

User: Read /etc/passwd
Calliope: Error: Access denied - /etc/passwd is outside allowed directories

File Size Limits

To prevent memory issues:

• Read limit: 1 MB per file
• Write: No hard limit, but monitored

Command Execution

Shell commands:

• Run in a subprocess with timeout
• Use your shell environment
• Limited to 60 seconds by default

Permission Modes

Normal Mode (Default)

In normal mode, you’ll be prompted before tool execution:

[shell] $ npm install
Execute? (y/n)

This allows you to:

• Review commands before execution
• Block suspicious operations
• Maintain control

God Mode

Enabled with -g or --god-mode:

calliope -g

In god mode:

• All tool calls execute without confirmation
• Suitable for trusted, automated tasks
• Shows a warning on startup

Sandboxing

Current Limitations

Calliope CLI runs with your user permissions. Commands can:

• Access files you can access
• Run programs you can run
• Use network resources

Recommendations

For sensitive environments:

1. Run in a container:

   docker run -it -v $(pwd):/workspace node:20 bash
   npm install -g @calliopelabs/cli
   calliope

2. Use a dedicated user:

   sudo useradd -m calliope-user
   sudo su - calliope-user
   npm install -g @calliopelabs/cli

3. Virtual environments: Run in a VM or cloud development environment for isolation.

Network Security

API Communications

All API calls use HTTPS:

• Anthropic: api.anthropic.com
• OpenAI: api.openai.com
• Google: generativelanguage.googleapis.com
• etc.

Proxy Support

If you need to route through a proxy:

export HTTPS_PROXY=http://proxy.example.com:8080
calliope

Local Models

For air-gapped or high-security environments, use Ollama:

# No external network calls
export OLLAMA_BASE_URL=http://localhost:11434
calliope
/provider ollama

Audit Trail

Conversation History

With autoSaveHistory: true, conversations are persisted. This provides:

• Record of what was requested
• Record of what was executed
• Debugging and compliance support

Logging

Calliope logs:

• Tool calls and their parameters
• Tool results (truncated)
• Errors and exceptions

For enterprise audit requirements, consider using AGTerm which provides comprehensive audit logging.

Best Practices

Development Environments

1. Use separate API keys for development and production
2. Set spending limits at your provider’s dashboard
3. Use lower-cost models for testing

Production Usage

1. Review all commands before execution (use normal mode)
2. Start with read-only tasks before enabling writes
3. Use version control so changes can be reverted
4. Test autonomous loops with low iteration counts first

Team Environments

1. Use environment variables rather than shared config files
2. Each team member should have their own API keys
3. Document expected variables in .env.example

Responsible AI Use

Content Guidelines

Calliope inherits the safety features of the underlying AI provider:

• Anthropic Claude has Constitutional AI
• OpenAI GPT has content policies
• etc.

However, as a tool executor, Calliope will attempt to run commands you request.

Recommendations

1. Review generated code before deployment
2. Test in staging before production
3. Don’t blindly trust AI-generated security code
4. Have humans review critical changes

Reporting Issues

Found a security issue?

1. Do not open a public GitHub issue
2. Email security@calliope.ai
3. Include:
   • Description of the vulnerability
   • Steps to reproduce
   • Potential impact

We take security seriously and will respond promptly.