Security Model

Phoenix Agent is designed with security as a first-class concern. Every action is controlled, logged, and reversible.

Trust Mode

The central security mechanism. Two states:

State	Behavior
`OFF` (default)	All destructive actions are blocked. Commands are shown but not executed. User must explicitly enable trust.
`ON`	Actions execute automatically. All operations are still logged to the audit trail.

Important: Even with trust ON, every action is recorded in the decision journal with reasoning. You can always review what the agent did and why.

Granular Permissions

Permission	Default	Controls
`file_read`	GRANTED	Read files and directories
`file_write`	DENIED	Create/modify/delete files
`shell_execute`	DENIED	Run shell commands
`mouse_control`	DENIED	Control mouse cursor
`keyboard_control`	DENIED	Simulate keyboard input
`screen_capture`	DENIED	Take screenshots
`network_access`	GRANTED	Make HTTP requests
`install_packages`	DENIED	Install system packages

API Key Encryption

All API keys are encrypted at rest using Fernet (AES-128-CBC + HMAC-SHA256):

Key derived via PBKDF2 (480,000 iterations) from machine-specific data
Stored in %LOCALAPPDATA%\phoenix-agent\keys\
Never transmitted anywhere except the provider's API endpoint
Never logged or included in telemetry

Audit Logging

Every security-relevant action is logged with:

{
  "timestamp": "2025-01-15T10:30:00Z",
  "action": "executed_command",
  "details": {
    "command": "mkdir C:\\Users\\...\\test",
    "exit_code": 0
  }
}

Decision Journal

Beyond simple logging, the decision journal records why the agent made each choice:

{
  "decision": "executed_command",
  "reason": "User requested directory creation",
  "alternatives": ["manual creation"],
  "context": {"command": "mkdir test"}
}

Best Practices

Keep trust OFF until you understand what the agent will do
Review /security permissions regularly
Check the audit log after autonomous sessions
Use /trust off immediately if something unexpected happens
Protect your config directory — it contains encrypted keys