Scope & Security

Calliope CLI includes comprehensive security features to protect your system and sensitive files.

Scope Management

Scope controls which directories Calliope can access. This prevents accidental or malicious access to sensitive areas of your filesystem.

Default Scope

By default, Calliope can access:

Path	Description
Current working directory	Where you launched Calliope
`/tmp`	Temporary files
Home directory	Optional, based on configuration

Viewing Current Scope

calliope> /scope
Allowed directories:
  - /home/user/projects/myapp (current)
  - /tmp

For detailed information:

calliope> /scope details
Scope Configuration:
  Allowed directories:
    - /home/user/projects/myapp
    - /tmp
  Blocked patterns:
    - .env, .env.*
    - *.pem, *.key
    - credentials*, secrets*

Adding Directories

Expand access to additional directories:

calliope> /scope add /home/user/shared-libs
Added /home/user/shared-libs to scope

calliope> /add-dir ~/other-project
Added /home/user/other-project to scope

Removing Directories

Restrict access:

calliope> /scope remove /tmp
Removed /tmp from scope

calliope> /remove-dir ~/other-project
Removed /home/user/other-project from scope

Resetting Scope

Return to default scope:

calliope> /scope reset
Scope reset to defaults

File Access Protection

Blocked File Patterns

Calliope automatically blocks access to sensitive files:

Pattern	Type
`.env`, `.env.*`	Environment variables
`.pem`, `.key`	Certificates and keys
`id_rsa`, `id_ed25519`	SSH keys
`credentials`, `secrets`	Credentials files
`.npmrc`, `.pypirc`	Package manager configs
`.p12`, `.pfx`	Certificate bundles

Path Traversal Protection

Attempts to escape the allowed scope are blocked:

User: Read ../../../etc/passwd
Calliope: Error: Access denied - path traversal detected

Example Blocked Access

User: Read .env
Calliope: Error: Access denied - .env matches blocked pattern

User: Read /etc/shadow
Calliope: Error: Access denied - /etc/shadow is outside allowed scope

Risk Assessment System

All tool operations are classified by risk level:

Risk Levels

Level	Color	Description	Action
none	Green	Read-only, no side effects	Execute immediately
low	Blue	Safe information gathering	Execute immediately
medium	Yellow	Modifiable but recoverable	Prompt in normal mode
high	Orange	Potentially destructive	Always prompt
critical	Red	System-level danger	Always prompt with warning

Examples by Risk Level

None (read-only):

list_files
read_file
git status
git log

Low (information gathering):

git diff
npm list
cat package.json

Medium (modifiable):

git add
npm install
write_file (new file)

High (potentially destructive):

rm, rm -r
git push
chmod
write_file (overwrite)

Critical (system danger):

sudo
dd
format
rm -rf /

Permission Prompts

For medium-and-higher risk operations in normal mode:

[high risk] rm -rf node_modules
This will delete the node_modules directory
Execute? (y/n/a)
  y - Yes, execute this command
  n - No, skip this command
  a - Yes to all (enable god mode)

God Mode

Skip all permission prompts for trusted tasks:

calliope -g
calliope --god-mode

Or enable during a session:

calliope> /confirm off
Confirmation prompts disabled (god mode)

God mode executes ALL tool calls without confirmation, including high-risk and critical operations. Only use for well-defined tasks in trusted directories.

When to Use God Mode

Appropriate:

Automated scripts
Well-defined refactoring tasks
Trusted CI/CD environments
Sandboxed containers

Inappropriate:

Exploring unfamiliar codebases
Tasks with unclear scope
Production environments
Shared systems

Sandboxed Code Execution

The execute_code tool runs code in isolated Docker containers when available.

Docker Sandbox Features

Feature	Description
Isolation	Code runs in separate container
Resource limits	Memory and CPU constrained
Timeout	Commands killed after timeout
Network	Optionally isolated
Filesystem	Working directory mounted read-only

Sandbox Status

You’ll see the execution status:

[execute_code] python [sandboxed]
print("Hello, World!")

Or when Docker is unavailable:

[execute_code] python [unsandboxed]
print("Hello, World!")

Fallback Behavior

When Docker is not available:

Code executes locally
Warning shown: [unsandboxed]
Timeout limits still apply
No resource isolation

Best Practices

1. Start with Minimal Scope

Only add directories you need:

calliope> /scope add ~/projects/myapp

2. Use God Mode Sparingly

Enable only for specific tasks:

calliope -g "Refactor all TypeScript files to use strict mode"

3. Review Before Execution

In normal mode, review prompts carefully:

[high risk] git push origin main
Execute? (y/n)

4. Check Scope Before Sensitive Operations

calliope> /scope details

5. Use Docker for Code Execution

Install Docker for safer code execution:

# Verify Docker is available
docker --version

# Calliope will automatically use Docker sandbox
calliope

Audit Trail

Calliope logs all tool executions for review:

calliope> /history
[10:30:15] [shell] git status
[10:30:20] [read_file] src/index.ts
[10:30:45] [write_file] src/index.ts
[10:31:00] [shell] npm test

This helps track what operations were performed during a session.

Tools Configuration