From 904809dcf1146cd46881a59eff5fa889e4044411 Mon Sep 17 00:00:00 2001 From: cyy Date: Thu, 26 Feb 2026 19:55:44 +0800 Subject: [PATCH 1/2] docs: add ACP setup guide with JetBrains, VS Code, and OpenRouter instructions Add docs/acp.md with step-by-step setup for crust acp-wrap with Goose and Gemini CLI across JetBrains IDEs and VS Code. Move inline JetBrains config from README into the new guide. Fix incorrect agent commands (codex acp does not exist) and remove unverified "tested with" claims. Co-Authored-By: Claude Opus 4.6 --- README.md | 22 +------ docs/acp.md | 150 +++++++++++++++++++++++++++++++++++++++++++ docs/cli.md | 4 +- docs/how-it-works.md | 4 +- 4 files changed, 156 insertions(+), 24 deletions(-) create mode 100644 docs/acp.md diff --git a/README.md b/README.md index bf2668a..c861246 100644 --- a/README.md +++ b/README.md @@ -109,28 +109,10 @@ crust stop # Stop crust For IDEs that use the [Agent Client Protocol](https://agentclientprotocol.com) (ACP), Crust can wrap any ACP agent as a transparent stdio proxy — intercepting file reads, writes, and terminal commands before the IDE executes them. No changes to the agent or IDE required. ```bash -crust acp-wrap -- codex acp +crust acp-wrap -- goose acp ``` -Tested with JetBrains IDEs (PhpStorm 2025.3); other ACP-compatible editors should work but are not yet verified. - -
-JetBrains setup (~/.jetbrains/acp.json) - -```json -{ - "agent_servers": { - "Codex via Crust": { - "command": "crust", - "args": ["acp-wrap", "--", "codex", "acp"] - } - } -} -``` - -Open **Settings → AI Assistant → Agents** or click **Add Custom Agent** in the AI Chat panel. See [JetBrains ACP docs](https://www.jetbrains.com/help/ai-assistant/acp.html) for details. - -
+Supports JetBrains IDEs and other ACP-compatible editors. See the [ACP setup guide](docs/acp.md) for step-by-step instructions including JetBrains config and OpenRouter support. ## Built-in Protection diff --git a/docs/acp.md b/docs/acp.md new file mode 100644 index 0000000..53aa9d5 --- /dev/null +++ b/docs/acp.md @@ -0,0 +1,150 @@ +# ACP Integration + +Crust can wrap any [ACP](https://agentclientprotocol.com)-compatible agent as a transparent stdio proxy — intercepting file reads, writes, and terminal commands before the IDE executes them. No changes to the agent or IDE required. + +```bash +crust acp-wrap -- goose acp +``` + +## Prerequisites + +1. **Crust** installed and on your `PATH` +2. **An ACP-compatible agent** installed and configured with an LLM provider — see [ACP agent list](https://agentclientprotocol.com/get-started/agents) + +## Supported Agents + +| Agent | Install | ACP command | Notes | +|-------|---------|-------------|-------| +| [Goose](https://github.com/block/goose) | `brew install block-goose-cli` | `goose acp` | Run `goose configure` first to set up your LLM provider | +| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | `npm install -g @google/gemini-cli` | `gemini --experimental-acp` | Requires `GEMINI_API_KEY` or Google OAuth | +| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | `npx @zed-industries/claude-agent-acp@latest` | Managed by wrapper | Requires Claude Code installed | + +> **Important:** Each agent must be independently configured with its own LLM provider and API key before use with Crust. Crust wraps the agent for security — it does not provide the LLM backend. Not all agents expose a direct `acp` subcommand; some (like Codex and Claude Code) use wrapper packages. Check each agent's documentation for setup instructions. + +## JetBrains IDEs (PhpStorm, IntelliJ, WebStorm, etc.) + +Requires a JetBrains IDE with AI Assistant plugin (2025.3+). + +> **Note:** If you previously configured Crust as an OpenAI-compatible HTTP endpoint (e.g. `http://localhost:9090/v1`) in **Settings → AI Assistant**, PhpStorm may fail with "Failed to initialize ACP process" when you try to chat. Use the ACP agent setup below instead. + +### Step 1: Install and configure an ACP agent + +```bash +# Goose +brew install block-goose-cli +goose configure # set up your LLM provider interactively + +# Or Gemini CLI +npm install -g @google/gemini-cli +export GEMINI_API_KEY=... +``` + +### Step 2: Create `~/.jetbrains/acp.json` + +**Goose example:** + +```json +{ + "agent_servers": { + "Goose via Crust": { + "command": "crust", + "args": ["acp-wrap", "--", "goose", "acp"] + } + } +} +``` + +**Gemini CLI example:** + +```json +{ + "agent_servers": { + "Gemini via Crust": { + "command": "crust", + "args": ["acp-wrap", "--", "gemini", "--experimental-acp"], + "env": { + "GEMINI_API_KEY": "..." + } + } + } +} +``` + +### Step 3: Connect in the IDE + +Open **AI Chat** → click **Add Custom Agent** → select your agent. + +## VS Code + +Install the [ACP Client](https://marketplace.visualstudio.com/items?itemName=formulahendry.acp-client) extension (v0.1.2+), then configure in `settings.json`: + +```json +{ + "acp.agents": { + "Goose via Crust": { + "enabled": true, + "command": "crust", + "args": ["acp-wrap", "--", "goose", "acp"] + } + } +} +``` + +> The extension ships with default configs for many agents (Gemini, Claude Code, Codex, etc.) — replace the `command` and `args` to route through Crust. + +## Using OpenRouter + +Some agents can route LLM calls through [OpenRouter](https://openrouter.ai) via environment variables. The exact variable names depend on the agent: + +**Goose** uses `OPENAI_HOST` and `GOOSE_PROVIDER`: + +```json +{ + "agent_servers": { + "Goose via Crust (OpenRouter)": { + "command": "crust", + "args": ["acp-wrap", "--", "goose", "acp"], + "env": { + "GOOSE_PROVIDER": "openai", + "OPENAI_HOST": "https://openrouter.ai", + "OPENAI_API_KEY": "sk-or-v1-..." + } + } + } +} +``` + +> **Caveat:** Goose may still require `goose configure` to be run first. Env-var-only provider configuration has not been fully verified. Check [Goose provider docs](https://block.github.io/goose/docs/getting-started/providers/) for the latest instructions. + +### Double-layer security + +For additional protection, run Crust's HTTP proxy in front of OpenRouter and point the agent at it: + +```bash +crust start --endpoint https://openrouter.ai/api +``` + +```json +"env": { + "OPENAI_HOST": "http://localhost:9090", + "OPENAI_API_KEY": "sk-or-v1-..." +} +``` + +This applies Crust's security rules on both the ACP layer (file/terminal access) and the HTTP layer (tool calls in LLM responses). + +## Other Editors + +Any editor that supports ACP (Zed, Neovim via CodeCompanion/avante.nvim) can use `crust acp-wrap`. Consult your editor's ACP documentation for how to configure a custom agent command. + +## Status + +- ACP handshake (initialize/response) passes through correctly for Goose and Gemini CLI +- Security rules block dangerous `fs/read_text_file`, `fs/write_text_file`, and `terminal/create` requests +- Non-security ACP methods pass through unchanged + +Please [open an issue](https://github.com/BakeLens/crust/issues) if you encounter problems with a specific agent or editor. + +## CLI Reference + +See [CLI docs](cli.md#acp-wrap-flags) for all `crust acp-wrap` flags (`--log-level`, `--rules-dir`, `--disable-builtin`, etc.). diff --git a/docs/cli.md b/docs/cli.md index 121785f..6b7c7ac 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -20,7 +20,7 @@ crust remove-rule FILE # Remove user rules crust reload-rules # Force reload all rules crust lint-rules [FILE] # Validate rule syntax -# ACP Proxy +# ACP Proxy (see [ACP setup guide](acp.md)) crust acp-wrap [flags] -- # ACP stdio proxy with security rules # Diagnostics @@ -117,6 +117,6 @@ crust doctor --timeout 3s --retries 0 crust doctor --report # sanitized report for GitHub issues # ACP proxy: wrap Codex for JetBrains/Zed -crust acp-wrap -- codex acp +crust acp-wrap -- goose acp crust acp-wrap --log-level debug -- goose acp ``` diff --git a/docs/how-it-works.md b/docs/how-it-works.md index fb70ffd..27d8788 100644 --- a/docs/how-it-works.md +++ b/docs/how-it-works.md @@ -28,7 +28,7 @@ Layer 1 Rule Evaluation Order: **Layer 1 (Response Rules):** Scans LLM-generated tool_calls in responses. Fast pattern matching with friendly error messages. -**ACP Mode (`crust acp-wrap`):** For IDEs using the [Agent Client Protocol](https://agentclientprotocol.com), Crust wraps the agent as a transparent stdio proxy. Tested with JetBrains IDEs (PhpStorm 2025.3). Security-relevant JSON-RPC messages (`fs/read_text_file`, `fs/write_text_file`, `terminal/create`) are intercepted and evaluated by the same rule engine. Blocked requests never reach the IDE — the agent receives a JSON-RPC error response instead. +**ACP Mode (`crust acp-wrap`):** For IDEs using the [Agent Client Protocol](https://agentclientprotocol.com), Crust wraps the agent as a transparent stdio proxy. Supports JetBrains IDEs and other ACP-compatible editors. Security-relevant JSON-RPC messages (`fs/read_text_file`, `fs/write_text_file`, `terminal/create`) are intercepted and evaluated by the same rule engine. Blocked requests never reach the IDE — the agent receives a JSON-RPC error response instead. See [ACP setup guide](acp.md) for configuration details. ```text IDE (JetBrains / any ACP-compatible editor) @@ -48,7 +48,7 @@ IDE (JetBrains / any ACP-compatible editor) └──────────────────────────────────────┘ │ stdin/stdout ▼ -Real ACP Agent (Codex, Goose, etc.) +Real ACP Agent (Goose, Gemini CLI, etc.) ``` --- From 794ee30b270893128e8ffcecf54b60c1d0710c97 Mon Sep 17 00:00:00 2001 From: cyy Date: Thu, 26 Feb 2026 20:09:34 +0800 Subject: [PATCH 2/2] docs: remove unverified OpenRouter ACP section OpenRouter configuration is the agent's concern, not Crust's. Crust already supports OpenRouter via its HTTP proxy mode. Remove the unverified ACP-specific OpenRouter instructions. Co-Authored-By: Claude Opus 4.6 --- README.md | 8 ++++---- docs/acp.md | 46 ++-------------------------------------------- 2 files changed, 6 insertions(+), 48 deletions(-) diff --git a/README.md b/README.md index c861246..a073b37 100644 --- a/README.md +++ b/README.md @@ -112,7 +112,7 @@ For IDEs that use the [Agent Client Protocol](https://agentclientprotocol.com) ( crust acp-wrap -- goose acp ``` -Supports JetBrains IDEs and other ACP-compatible editors. See the [ACP setup guide](docs/acp.md) for step-by-step instructions including JetBrains config and OpenRouter support. +Supports JetBrains IDEs and other ACP-compatible editors. See the [ACP setup guide](docs/acp.md) for step-by-step instructions. ## Built-in Protection @@ -124,9 +124,9 @@ Crust ships with **14 security rules** and **19 DLP token-detection patterns** o | **System Auth** | `/etc/passwd`, `/etc/shadow`, sudoers | | **Shell History** | `.bash_history`, `.zsh_history`, `.python_history`, and more | | **Browser Data** | Chrome, Firefox, Safari passwords, cookies, local storage | -| **Package Tokens** | npm, pip, Cargo, Composer, NuGet, Gem, Hex auth tokens | -| **Git Credentials** | `.git-credentials`, `.gitconfig` with credentials | -| **Persistence** | Shell RC files, `authorized_keys`, crontabs | +| **Package Tokens** | npm, pip, Cargo, Composer, NuGet, Gem auth tokens | +| **Git Credentials** | `.git-credentials`, `.config/git/credentials` | +| **Persistence** | Shell RC files, `authorized_keys` | | **DLP Token Detection** | Content-based scanning for real API keys and tokens (AWS, GitHub, Stripe, OpenAI, Anthropic, and [14 more](docs/how-it-works.md#dlp-secret-detection)) | | **Key Exfiltration** | Content-based PEM private key detection | | **Self-Protection** | Agents cannot read, modify, or disable Crust itself | diff --git a/docs/acp.md b/docs/acp.md index 53aa9d5..6d655c0 100644 --- a/docs/acp.md +++ b/docs/acp.md @@ -17,9 +17,8 @@ crust acp-wrap -- goose acp |-------|---------|-------------|-------| | [Goose](https://github.com/block/goose) | `brew install block-goose-cli` | `goose acp` | Run `goose configure` first to set up your LLM provider | | [Gemini CLI](https://github.com/google-gemini/gemini-cli) | `npm install -g @google/gemini-cli` | `gemini --experimental-acp` | Requires `GEMINI_API_KEY` or Google OAuth | -| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | `npx @zed-industries/claude-agent-acp@latest` | Managed by wrapper | Requires Claude Code installed | -> **Important:** Each agent must be independently configured with its own LLM provider and API key before use with Crust. Crust wraps the agent for security — it does not provide the LLM backend. Not all agents expose a direct `acp` subcommand; some (like Codex and Claude Code) use wrapper packages. Check each agent's documentation for setup instructions. +> **Important:** Each agent must be independently configured with its own LLM provider and API key before use with Crust. Crust wraps the agent for security — it does not provide the LLM backend. Check each agent's documentation for setup instructions. ## JetBrains IDEs (PhpStorm, IntelliJ, WebStorm, etc.) @@ -90,48 +89,7 @@ Install the [ACP Client](https://marketplace.visualstudio.com/items?itemName=for } ``` -> The extension ships with default configs for many agents (Gemini, Claude Code, Codex, etc.) — replace the `command` and `args` to route through Crust. - -## Using OpenRouter - -Some agents can route LLM calls through [OpenRouter](https://openrouter.ai) via environment variables. The exact variable names depend on the agent: - -**Goose** uses `OPENAI_HOST` and `GOOSE_PROVIDER`: - -```json -{ - "agent_servers": { - "Goose via Crust (OpenRouter)": { - "command": "crust", - "args": ["acp-wrap", "--", "goose", "acp"], - "env": { - "GOOSE_PROVIDER": "openai", - "OPENAI_HOST": "https://openrouter.ai", - "OPENAI_API_KEY": "sk-or-v1-..." - } - } - } -} -``` - -> **Caveat:** Goose may still require `goose configure` to be run first. Env-var-only provider configuration has not been fully verified. Check [Goose provider docs](https://block.github.io/goose/docs/getting-started/providers/) for the latest instructions. - -### Double-layer security - -For additional protection, run Crust's HTTP proxy in front of OpenRouter and point the agent at it: - -```bash -crust start --endpoint https://openrouter.ai/api -``` - -```json -"env": { - "OPENAI_HOST": "http://localhost:9090", - "OPENAI_API_KEY": "sk-or-v1-..." -} -``` - -This applies Crust's security rules on both the ACP layer (file/terminal access) and the HTTP layer (tool calls in LLM responses). +> The extension ships with default configs for many agents — replace the `command` and `args` to route through Crust. ## Other Editors