Security model

Cascade is an agent that writes code and pushes branches. That is a powerful thing to hand to any tool, AI or otherwise. This page is about the boundaries we put around that power, so you know what you are signing up for.

Threat model

The threats Cascade is designed to resist:

1. Accidental data leak. Cascade should not send your code anywhere except to the LLM provider you explicitly chose.
2. Privilege escalation by the agent. A buggy or jailbroken LLM should not be able to modify Cascade’s own configuration, run arbitrary shell commands, or merge a PR without a human.
3. Path traversal. Generated code should only land in files you authorized, never in .github/, .git/, your secrets directory, or anywhere outside the repo root.
4. Credential exposure. Your LLM API key and VCS token should be stored in a way that other users on the same machine cannot read them.

Things Cascade is not designed to resist:

• A malicious developer with shell access. If someone can run cascade as you, they can read your ~/.config/cascade/config.yaml. Use OS-level user separation, not Cascade, to defend against this.
• An untrusted LLM provider. If you point Cascade at a provider you do not trust, that provider sees everything you send it. Pick providers the same way you pick any other vendor.
• A malicious team-memory file. team-memory/ is included verbatim in LLM prompts. If someone with write access to your repo puts prompt-injection instructions there, the LLM could be misled. Treat team-memory/ with the same scrutiny as code review.

Invariants

These are properties of the system that should always hold. If any is violated, that is a security bug; please report it.

Invariant	Why it matters
Cascade never merges PRs	A human always approves the final change. Cascade does not have merge permissions on any repo.
Cascade only writes to paths in paths.allowed	Limits the blast radius if generated code is wrong. Deny rules in paths.disallowed always override.
Cascade never modifies .github/, cascade.yaml, or team-memory/	The agent cannot modify its own configuration or the project’s CI workflows.
Cascade only runs the configured test_command and git	No arbitrary shell access. The agent cannot exfiltrate data or download arbitrary tools.
Source code, transcripts, and recordings never leave your machine and your configured LLM provider	No telemetry, no analytics pings, no third-party uploads.
Credentials at ~/.config/cascade/config.yaml are stored mode 0600	World-readable credentials would be a serious leak.
Cascade never reads files outside the repo root and the explicit transcripts/ directory	The agent’s view of your filesystem is bounded.
Cascade refuses to operate on a dirty working tree	Prevents the agent from overwriting your in-progress work.

Where your data goes

Data type	Destination	Notes
Source code, file contents	Your configured LLM provider only.	Cascade reads relevant files, builds a structured prompt, and sends that prompt to the LLM you chose. Nothing is sent to ThinkNext, the Cascade authors, or any third party.
Meeting audio	Stays local with local-whisper or faster-whisper. Goes to OpenAI’s Whisper API only if you opt into the openai-api backend.	The default backend is local-only. Switch with cascade ingest --backend openai-api.
Transcripts and extracted stories	Local filesystem under transcripts/ and stories/. Sent to your configured LLM provider for downstream stages.	Both directories are gitignored by cascade init so transcripts do not end up in your PRs.
Credentials	Local filesystem only. Never sent over the network except by the SDK you have configured (e.g., the Anthropic SDK sending your API key in its Authorization header).	Stored at ~/.config/cascade/config.yaml with chmod 0600.
Cascade telemetry	None. Cascade does not phone home, does not check for updates, does not collect usage stats.	If we ever add opt-in telemetry, it will be off by default and clearly documented.

Running Cascade in a corporate environment

If your employer prohibits sending source code to SaaS AI providers, you have two fully local options:

1. Claude Code (cascade configure llm claude_code --set-default). Uses your existing Claude Code installation. Code is sent to Anthropic via your existing approved channel; no new vendor relationship.
2. Ollama (cascade configure llm ollama --model llama3.3 --set-default). Runs the model on your own hardware. Code never leaves the machine. Quality depends on the model size; you want at least a 70B-class model for usable code generation.

Either way, source code, transcripts, and credentials all stay inside your network perimeter.

For air-gapped or sensitive environments, also consider:

• Setting up a private PyPI mirror to install Cascade without reaching out to PyPI itself.
• Disabling the cascade ingest command entirely if you do not want OpenAI Whisper as even an opt-in.
• Reviewing the paths.disallowed list in cascade.yaml to make sure sensitive directories (e.g., secrets/, infrastructure/) are excluded.

What Cascade cannot prevent

Honesty about the limits:

• The LLM provider could log, fine-tune on, or store the prompts you send it. That is a property of your LLM provider, not Cascade. Read your provider’s privacy and data-retention terms. Anthropic, OpenAI, and Google all publish them.
• A poorly-written cascade.yaml could allow Cascade to write to sensitive paths. Review your paths.allowed list carefully. The starter cascade.yaml errs on the side of src/** and tests/** only.
• A human approver could merge a bad PR. Cascade generates the change; the human still has to review it. Cascade is not a replacement for code review.
• Generated tests are a starting point, not a proof. A test that passes does not prove the change is correct. Treat AI-generated test coverage the same way you treat any other test coverage: useful, not authoritative.
• An LLM jailbreak could try to escape the sandbox. We constrain what the agent can do (no arbitrary shell, no merge, bounded paths) but novel attacks may find seams. Report them.

Auditing what Cascade did

Every Cascade run is auditable after the fact:

• The branch name encodes the story ID (e.g., cascade/story-prompt-20260925-103045/add-health-endpoint).
• The commit message includes the story ID, the meeting ID (if applicable), and the list of files changed.
• The PR body links back to the story file in stories/ so reviewers can see the original requirement.
• ~/.config/cascade/logs/ contains debug logs if you ran with -v (verbose mode).

If you need stronger audit guarantees (e.g., centralized logs, signed commits), file an issue describing your environment and we will look at adding it.

Reporting a vulnerability

If you find a way to violate any invariant on this page, that is a security issue. Please do not open a public GitHub issue. Instead:

1. Email [email protected] with:
   • A description of the issue
   • Reproduction steps
   • Impact assessment (what an attacker could do)
2. You will get acknowledgment within 2 business days.
3. We will respond with a remediation timeline within 5 business days.
4. After the fix ships, we credit reporters in the release notes (with your permission).

See the SECURITY.md file in the main repo for the full policy.