Permissions and Security Configuration

The powerful capabilities of AI programming tools also bring security risks. This article will teach you how to configure Opencode's permission system to let AI work efficiently without misoperations or leaking sensitive information.

Why Permission Configuration is Needed?

Production environments fear two things most:

  1. Reading Sensitive Information: .env files, private keys, API tokens
  2. Executing Dangerous Commands: rm -rf, batch replacements, incorrect database operations

Through proper permission configuration, you can:

  • Prevent AI from reading sensitive files
  • Control AI's file modification permissions
  • Limit AI's command execution scope
  • Set different permissions for different Agents

Permission Configuration Basics

Opencode's permission system includes three levels:

  1. read - File read permissions
  2. edit - File modification permissions
  3. bash - Command execution permissions

Each permission can be set to:

  • "allow" - Direct pass, no asking
  • "ask" - Ask for user confirmation each time
  • "deny" - Direct deny

Basic Security Configuration

Suitable for individual developers:

{
  "permission": {
    // File read permissions
    "read": {
      "*": "allow",
      "*.env": "deny",
      "*.env.*": "deny",
      "*.env.example": "allow",
      "*.key": "deny",
      "*.pem": "deny",
      "id_rsa*": "deny"
    },
    
    // File modification permissions
    "edit": "ask",
    
    // Command execution permissions
    "bash": {
      "*": "ask",
      "git status": "allow",
      "git diff": "allow",
      "npm test": "allow",
      "npm run lint": "allow"
    }
  }
}

Strict Security Configuration

Suitable for team collaboration or production environments:

{
  "permission": {
    "read": {
      "*": "allow",
      "*.env": "deny",
      "*.env.*": "deny",
      "*.key": "deny",
      "*.pem": "deny",
      "id_rsa*": "deny",
      ".aws/credentials": "deny",
      "database.yml": "ask",
      "*.example": "allow"
    },
    
    "edit": "ask",
    
    "bash": {
      "*": "ask",
      "git status": "allow",
      "git diff": "allow",
      "npm test": "allow",
      "rm -rf": "deny",
      "sudo": "deny",
      "chmod 777": "deny"
    }
  }
}

File Permissions Explained

Wildcard Rules

Opencode supports glob pattern matching:

{
  "permission": {
    "read": {
      ".env": "deny",              // Exact match
      "*.env": "deny",             // Wildcard match
      "*.env.*": "deny",           // Match .env.local, .env.production
      "secrets/*": "deny",         // Match all files in secrets directory
      "secrets/**": "deny",        // Match secrets directory and subdirectories
      "config/secrets/*.key": "deny"  // Multi-level path
    }
  }
}

Priority Rules

When multiple rules match, more specific rules have higher priority:

{
  "permission": {
    "read": {
      "*": "allow",                 // Priority 1 (lowest)
      "*.env": "deny",              // Priority 2
      "*.env.example": "allow"      // Priority 3 (highest)
    }
  }
}

Common Sensitive Files Checklist

{
  "permission": {
    "read": {
      // Environment variables
      "*.env": "deny",
      "*.env.*": "deny",
      
      // Keys and certificates
      "*.key": "deny",
      "*.pem": "deny",
      "*.p12": "deny",
      
      // SSH keys
      "id_rsa": "deny",
      "id_ed25519": "deny",
      
      // Cloud service credentials
      ".aws/credentials": "deny",
      ".gcloud/**": "deny",
      
      // Database
      "database.yml": "ask",
      
      // Allow examples
      "*.example": "allow",
      "*.sample": "allow"
    }
  }
}

Command Permissions Explained

Safe Command Whitelist

{
  "permission": {
    "bash": {
      "*": "ask",
      
      // Git read-only commands
      "git status": "allow",
      "git diff": "allow",
      "git log": "allow",
      
      // File viewing
      "ls": "allow",
      "cat": "allow",
      "pwd": "allow",
      
      // Testing and checking
      "npm test": "allow",
      "npm run lint": "allow",
      "pytest": "allow"
    }
  }
}

Dangerous Command Blacklist

{
  "permission": {
    "bash": {
      // File deletion
      "rm -rf": "deny",
      "rm -fr": "deny",
      
      // Permission modification
      "chmod 777": "deny",
      
      // System-level operations
      "sudo": "deny",
      "su": "deny",
      
      // Disk operations
      "dd": "deny",
      
      // Database operations
      "DROP DATABASE": "deny",
      "TRUNCATE": "ask",
      "DELETE FROM": "ask"
    }
  }
}

Agent-Level Permissions

Set different permissions for different Agents:

Read-Only Agent

Suitable for code review, documentation generation:

{
  "agent": {
    "code-reviewer": {
      "description": "Code review expert",
      "model": "anthropic/claude-sonnet-4-5",
      "permission": {
        "read": {
          "*": "allow"
        },
        "edit": "deny",
        "bash": "deny"
      }
    }
  }
}

Restricted Agent

Allow read/write, but commands need confirmation:

{
  "agent": {
    "junior-dev": {
      "description": "Junior developer",
      "model": "deepseek/deepseek-coder",
      "permission": {
        "read": {
          "*": "allow",
          "*.env": "deny"
        },
        "edit": "ask",
        "bash": {
          "*": "ask",
          "git status": "allow"
        }
      }
    }
  }
}

Security Best Practices

1. Principle of Least Privilege

Default deny, open as needed:

{
  "permission": {
    "read": {
      "*": "ask",
      "src/**": "allow",
      "docs/**": "allow"
    },
    "edit": "ask",
    "bash": "deny"
  }
}

2. Layered Defense

Global config + Project config + Agent config

3. Regular Audits

Check AI operation logs:

cat ~/.config/opencode/logs/operations.log
cat ~/.config/opencode/logs/bash.log

4. Use .gitignore

Ensure sensitive files are not committed:

.env
.env.*
!.env.example
*.key
*.pem
.aws/
database.yml

Verify Permission Configuration

Test File Permissions

# Test 1: Try to read .env
Please read the .env file content
→ Should be denied

# Test 2: Try to read .env.example
Please read the .env.example file content
→ Should succeed

# Test 3: Try to modify file
Please modify README.md
→ Should ask for confirmation

Common Questions

Q: Do permission configurations affect performance?

No. Permission checks are performed before operations and don't affect AI response speed.

Q: How to temporarily elevate permissions?

You can explicitly state in conversation or temporarily modify the config file.

Q: Do Agent permissions override global permissions?

Yes. Agent-level permissions have the highest priority.

Next Steps

Compiled by the OpenCodex community. Security is no small matter.

Last Updated: