Security

Supyagent provides multiple layers of security for protecting credentials, isolating workspaces, and sandboxing tool execution.

Credential Encryption

Global API Keys (Fernet Encryption)

Global configuration (API keys for LLM providers) is encrypted at rest using Fernet symmetric encryption and stored in ~/.supyagent/config/. Fernet provides authenticated encryption -- data cannot be read or tampered with without the key.

The encryption key is stored at ~/.supyagent/config/key.key and is generated automatically on first use. The encrypted data is stored alongside it.

# Set an API key (encrypted and stored)
supyagent config set ANTHROPIC_API_KEY

# List stored keys (shows names only, not values)
supyagent config list

# Delete a stored key
supyagent config delete ANTHROPIC_API_KEY

# Import from .env file (encrypted on import)
supyagent config import .env

# Export to .env file (with 0600 permissions)
supyagent config export backup.env

At startup, load_config() decrypts stored keys and injects them into the environment so LiteLLM can find them.

Per-Agent Credentials (Fernet Encryption)

Each agent can have credentials stored separately in .supyagent/credentials/{agent_name}.enc. These are also Fernet-encrypted and are loaded only when that agent runs.

Agents can request credentials at runtime via the built-in request_credential tool, which prompts the user and optionally persists the value encrypted.

credentials:
  - name: GITHUB_TOKEN
    description: "GitHub personal access token for API calls"
    required: true
  - name: SLACK_WEBHOOK
    description: "Slack incoming webhook URL"
    required: false

Environment Variable Fallback

API keys can also be provided via standard environment variables. The lookup order is:

1. Encrypted global config (~/.supyagent/config/)
2. Encrypted per-agent credentials (.supyagent/credentials/)
3. Environment variables
4. Runtime credential prompting (via request_credential tool)

Workspace Isolation

Each supyagent project operates within its own workspace directory. The workspace boundary is established by the location of the agents/ and powers/ directories.

• Sessions are stored in .supyagent/sessions/ relative to the workspace
• Credentials are stored in .supyagent/credentials/ relative to the workspace
• Registry state is stored in .supyagent/registry.json
• Telemetry is stored in .supyagent/telemetry/

You can explicitly set the workspace for an agent:

workspace: /path/to/project   # Tools execute relative to this directory

This isolates file system access so that the agent's tools operate within a controlled directory.

Sandbox Configuration

For maximum isolation, you can run tool execution inside a container (Docker or Podman). This prevents tools from accessing the host filesystem, network, or other resources outside the container.

name: sandboxed-agent
model:
  provider: anthropic/claude-sonnet-4-5-20250929

sandbox:
  enabled: true
  image: python:3.12-slim       # Container image
  runtime: auto                  # auto | podman | docker
  network: bridge                # none | host | bridge
  memory_limit: 2g              # Container memory limit
  allow_shell: true              # Allow shell/exec tool execution

  # Additional file mounts
  extra_mounts:
    - host_path: /home/user/data
      container_path: /mnt/data
      readonly: true

  # Extra environment variables inside the container
  env:
    PYTHONDONTWRITEBYTECODE: "1"

  # Commands to run after container creation
  setup_commands:
    - "pip install pandas numpy"
    - "apt-get update && apt-get install -y git"

system_prompt: |
  You are a sandboxed coding assistant. Your tools run inside a
  container for security isolation.

Sandbox Configuration Fields

Mount Configuration

Each mount in extra_mounts has:

Network Modes

Runtime Detection

When runtime is set to auto, supyagent checks for podman first, then falls back to docker. You can force a specific runtime if both are installed.

Best Practices

Credential Management

• Use supyagent config set to store API keys encrypted rather than putting them in .env files
• If using .env files, add them to .gitignore immediately
• Use per-agent credentials when agents need different access levels
• The request_credential tool lets agents prompt for credentials at runtime instead of storing them permanently

Workspace Security

• Keep each project in its own directory with its own agents/ and powers/
• Use the workspace config field to restrict tool execution to a specific directory
• Review tool permissions (tools.allow / tools.deny) to restrict what tools an agent can access

Sandbox Security

• Enable sandboxing for agents that run untrusted code or user-provided scripts
• Use network: none when tools do not need network access
• Mount data directories as readonly: true unless write access is required
• Set appropriate memory_limit to prevent resource exhaustion
• Use setup_commands to install only the dependencies you need

Multi-Agent Security

• Child agents inherit credentials from parent agents only if delegation.share_credentials is true
• The delegation depth limit (enforced by AgentRegistry) prevents infinite delegation chains
• Use subprocess delegation mode for stronger isolation between agents

Related

• Configuration -- Global and per-agent configuration details
• Process Management -- Process lifecycle and isolation
• Building Agents -- Tool permissions and delegation settings