How to Safely Use Windsurf Cascade Agent

To safely use Windsurf's Cascade agent, add SafeClaw action-level gating. Install with npx @authensor/safeclaw and define a deny-by-default policy that controls which files Cascade can edit, which terminal commands it can execute, and which network requests it can make. Cascade is Windsurf's autonomous AI coding agent — it reads your codebase, plans multi-step changes, writes code across multiple files, runs terminal commands, and iterates on errors automatically.

What Windsurf Cascade Can Do (And Why That's Risky)

Cascade operates as a fully autonomous coding agent inside the Windsurf IDE. Its capabilities include:

• Deep codebase awareness — Cascade indexes your entire workspace and maintains context across files. It reads source code, configuration, documentation, and any other files in your project, including files containing secrets.
• Multi-file editing — a single Cascade instruction can modify dozens of files. It refactors imports, updates component hierarchies, changes API signatures, and propagates changes across your project.
• Terminal command execution — Cascade runs commands in Windsurf's integrated terminal: build tools, test runners, package managers, git commands, and arbitrary shell commands. It uses command output to inform its next actions.
• Autonomous iteration — Cascade follows a "flow" pattern: edit code, run tests, observe failures, fix code, run tests again. This loop continues without human checkpoints until the task succeeds or the agent gives up.
• File creation and deletion — Cascade creates new files (components, utilities, configs, tests) and can remove files it determines are no longer needed.
• Package installation — Cascade installs dependencies via npm install, pip install, cargo add, and other package managers, pulling code from public registries.
• Context from web search — Cascade can search the web for documentation and examples, bringing external content into its context window where it can influence subsequent actions.

Step-by-Step Setup

Step 1: Install SafeClaw

npx @authensor/safeclaw

Select MCP Server as the integration type. Windsurf supports MCP tool servers in its configuration.

Step 2: Get Your API Key

Visit safeclaw.onrender.com for a free-tier key. Renewable every 7 days, no credit card required.

Step 3: Add SafeClaw as an MCP Server in Windsurf

Edit your Windsurf MCP configuration file (typically ~/.codeium/windsurf/mcp_config.json or your project-level MCP config):

{
  "mcpServers": {
    "safeclaw": {
      "command": "npx",
      "args": ["@authensor/safeclaw", "serve", "--mode", "mcp"],
      "env": {
        "SAFECLAW_API_KEY": "your-key-here"
      }
    }
  }
}

Step 4: Define Your Policy

Create safeclaw.policy.yaml in your project root:

version: 1
default: deny

rules:
  - action: file_read
    path: "${PROJECT_DIR}/**"
    effect: allow

- action: file_read
    path: "*/.env"
    effect: deny

- action: file_read
    path: "*/credentials"
    effect: deny

- action: file_read
    path: "*/.key"
    effect: deny

- action: file_write
    path: "${PROJECT_DIR}/src/**"
    effect: allow

- action: file_write
    path: "${PROJECT_DIR}/lib/**"
    effect: allow

- action: file_write
    path: "${PROJECT_DIR}/tests/**"
    effect: allow

- action: file_write
    path: "${PROJECT_DIR}/package.json"
    effect: allow

- action: file_write
    path: "${PROJECT_DIR}/.github/**"
    effect: deny

- action: file_write
    path: "${PROJECT_DIR}/Dockerfile"
    effect: deny

- action: file_write
    path: "${PROJECT_DIR}/docker-compose*"
    effect: deny

- action: shell_exec
    command: "npm test*"
    effect: allow

- action: shell_exec
    command: "npm run*"
    effect: allow

- action: shell_exec
    command: "npm install*"
    effect: allow

- action: shell_exec
    command: "git diff*"
    effect: allow

- action: shell_exec
    command: "git status"
    effect: allow

- action: shell_exec
    command: "git add*"
    effect: allow

- action: shell_exec
    command: "git commit*"
    effect: allow

- action: shell_exec
    command: "rm -rf*"
    effect: deny

- action: shell_exec
    command: "git push --force*"
    effect: deny

- action: shell_exec
    command: "chmod*"
    effect: deny

- action: network
    host: "registry.npmjs.org"
    effect: allow

- action: network
    host: "*"
    effect: deny

Step 5: Simulate Before Enforcing

npx @authensor/safeclaw simulate --policy safeclaw.policy.yaml

Run Cascade on a test task. Review every logged verdict. Adjust your rules, then switch to enforcement.

What Gets Blocked, What Gets Through

ALLOWED — Cascade edits a source file:

{ "action": "file_write", "path": "/project/src/components/Dashboard.tsx", "verdict": "ALLOW" }

DENIED — Cascade modifies Docker configuration:

{ "action": "file_write", "path": "/project/docker-compose.yml", "verdict": "DENY", "reason": "path matches docker-compose* deny rule" }

ALLOWED — Cascade runs the build:

{ "action": "shell_exec", "command": "npm run build", "verdict": "ALLOW" }

DENIED — Cascade reads API key file:

{ "action": "file_read", "path": "/project/config/credentials.json", "verdict": "DENY", "reason": "path matches */credentials deny rule" }

DENIED — Cascade changes file permissions:

{ "action": "shell_exec", "command": "chmod 777 deploy.sh", "verdict": "DENY", "reason": "chmod* matches deny rule" }

Without SafeClaw vs With SafeClaw

| Scenario | Without SafeClaw | With SafeClaw |
|---|---|---|
| Cascade rewrites Dockerfile after vague "optimize deployment" prompt | Dockerfile modified, container config changed | Blocked — Dockerfile is denied for writes |
| Cascade reads credentials.json for API context | Credentials loaded into Cascade's context | Blocked — */credentials matched deny rule |
| Cascade runs rm -rf dist/ and misinterprets the path | Deletion executes with your permissions | Blocked — rm -rf* matches deny rule |
| Cascade edits source files in src/ and lib/ | Files edited normally | Allowed — both directories in write allowlist |
| Cascade autonomous loop: edit, test, fix, test again | All actions proceed without review | Each action in the loop is individually evaluated against policy |

SafeClaw evaluates every action in sub-millisecond time with zero third-party dependencies. The tamper-proof audit trail (SHA-256 hash chain) logs every verdict. The control plane sees only action metadata — never your code, credentials, or file contents. The client is 100% open source, MIT licensed, built with TypeScript strict mode, and validated by 446 tests.

Cross-References

• What is SafeClaw? — Deny-by-default action gating architecture
• How to Safely Use Cursor Agent Mode — Similar IDE-based agent safety patterns
• How to Safely Use GitHub Copilot Agent Mode — Another IDE agent with comparable capabilities
• How to Safely Use Claude Code — CLI-based coding agent with MCP integration
• How to Safely Run Autonomous Coding Agents — General patterns for autonomous agent control