### sandbox (user only) Sandbox network filtering is currently unstable. If you need this feature, please reach out to your account representative for stability timelines. Configure domain-level network filtering for the sandbox. When `--sandbox` is active and domain filtering is configured, a managed network proxy starts on loopback and the sandbox restricts all child traffic to route through it. For a complete overview of how the sandbox works — including enterprise enforcement and how enterprise and user settings interact — see the [Sandbox documentation](/cli/sandbox). The `--sandbox` flag enforces the active Read and Write permission scopes at the OS level. Writable roots are derived from granted `Write(...)` scopes plus workspace directories; readable roots come from `Read(...)` scopes (with platform defaults always readable). Scopes granted mid-session dynamically expand the sandbox for subsequent commands. If `--sandbox` is passed but sandbox resolution fails (e.g., sandboxing tools are unavailable on the current platform), the CLI will refuse to start rather than running unsandboxed. This fail-closed behavior ensures the security intent of `--sandbox` is never silently bypassed. | Option | Type | Default | Description | | ----------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------- | | `allowed_domains` | string\[] | `[]` | Domain patterns allowed through the proxy. When non-empty, only matching domains are allowed (allowlist mode) | | `denied_domains` | string\[] | `[]` | Domain patterns always blocked. Deny rules take precedence over allow rules | | `network_mode` | string | `"full"` | `"full"` allows all HTTP methods; `"limited"` allows only GET/HEAD/OPTIONS | **Domain pattern syntax:** | Pattern | Matches | | ---------------- | ----------------------------- | | `example.com` | Exact match only | | `*.example.com` | Any subdomain (not the apex) | | `**.example.com` | Apex domain and any subdomain | **Example:** ```json theme={null} { "sandbox": { "allowed_domains": [ "github.com", "**.npmjs.org", "**.crates.io", "**.pypi.org" ], "denied_domains": ["evil.example.com"], "network_mode": "full" } } ``` Domain filtering applies when the sandbox is active (`--sandbox`). Without `--sandbox`, the sandbox section is ignored. For enterprise teams, admins can override domain lists via [Team Settings](/cli/enterprise/team-settings#sandbox-enforcement). Enterprise allowlists are authoritative (they replace your local `allowed_domains`), while enterprise denylists are additive (merged with your local `denied_domains`). *** ## JSON with Comments Config files support JavaScript-style comments: ```json theme={null} { // Line comments "agent": { "model": "sonnet" // Inline comments }, /* Block comments */ "permissions": {} } ``` # Configuration Precedence Source: https://docs.devin.ai/cli/reference/configuration/global-vs-local How global, project, and local settings interact Devin CLI loads configuration from multiple sources and merges them together. Understanding the precedence order helps you set up the right configuration for your team and personal preferences. *** ## Configuration Layers From highest to lowest priority: | Priority | Source | Notes | | ----------- | ------------------------------------------------------------------------------ | -------------------- | | 1 (highest) | Organization / Team Settings | Cannot be overridden | | 2 | Session (interactive approvals) | In-memory only | | 3 | Project Local (`.devin/config.local.json`) | Personal, gitignored | | 4 | Project (`.devin/config.json`) | Shared with team | | 5 (lowest) | User (`~/.config/devin/config.json`; `%APPDATA%\devin\config.json` on Windows) | Your defaults | When the same setting is defined at multiple levels, the higher-priority source wins. *** ## When to Use Each Level **Path:** `~/.config/devin/config.json` (`%APPDATA%\devin\config.json` on Windows) Use for personal preferences that apply everywhere: * Default model preference * Theme preference * Personal MCP servers (e.g., your own API keys) * Global permission grants ```json theme={null} { "agent": { "model": "opus" }, "permissions": { "allow": ["Read(**)", "Exec(git)"] } } ``` **Path:** `.devin/config.json` Use for team standards committed to the repository. Only `permissions`, `mcpServers`, `read_config_from`, and `hooks` are available at this level: * Shared MCP servers (with non-secret config) * Team permission policies * Import settings * Lifecycle hooks ```json theme={null} { "permissions": { "allow": ["Exec(npm run)", "Read(src/**)"], "deny": ["Exec(sudo)"] }, "mcpServers": { "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] } } } ``` **Path:** `.devin/config.local.json` Use for personal overrides that shouldn't be committed: * API keys and secrets * Personal tool preferences for this project * Permission overrides ```json theme={null} { "mcpServers": { "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_TOKEN": "ghp_my_personal_token" } } } } ``` Local config files are automatically excluded from git via `.git/info/exclude`. Managed by your enterprise admin through the team settings dashboard. These settings cannot be overridden by individual users and enforce organization-wide policies like model restrictions and MCP server allowlists. *** ## What's Available at Each Level Project configs (`.devin/config.json` and `.devin/config.local.json`) only support a subset of settings. The table below shows which settings are available at each level: | Setting | User config | Project config | | -------------------------- | :---------: | :------------: | | `permissions` | ✓ | ✓ | | `mcpServers` | ✓ | ✓ | | `read_config_from` | ✓ | ✓ | | `hooks` | ✓ | ✓ | | `agent` (model) | ✓ | ✗ | | `theme_mode` | ✓ | ✗ | | `unicode_mode` | ✓ | ✗ | | `show_path` | ✓ | ✗ | | `show_hints` | ✓ | ✗ | | `include_gitignored_files` | ✓ | ✗ | | `sandbox` | ✓ | ✗ | Settings marked as user-config only can only be set in the user config (`~/.config/devin/config.json`; `%APPDATA%\devin\config.json` on Windows) and do not participate in the precedence hierarchy above. *** ## How Merging Works The precedence table above only applies to settings that support multiple levels (`permissions`, `mcpServers`, `read_config_from`, `hooks`). ### Permissions Permission lists are **merged** (combined) across levels. A denial at a higher level cannot be overridden by an allow at a lower level. For example, if your organization denies `Exec(sudo)`, adding `Exec(sudo)` to your user allow list has no effect — the organization denial always wins. However, other permissions like `Read(**)` at the project level are applied normally. ### MCP Servers MCP server configs are **merged by name**. A server defined at a higher level overrides the same-named server at a lower level. For example, if both your user config and project config define a "github" server, the project config version wins because it has higher priority than user config. ### Hooks Hooks are **collected** from all sources and all run. A hook defined in the user config runs alongside hooks defined in the project config — they do not override each other. *** ## Project Root Detection Devin CLI finds your project root by looking for a `.git` or `.jj` directory, walking up from your current working directory. Project config (`.devin/`) is loaded from the project root. If you have nested `.devin/` directories (e.g., in a monorepo), subdirectory configs take precedence over ancestor configs. *** ## File Discovery Summary | File | Found by | Shared? | | ----------------------------------- | ------------------- | --------------- | | `~/.config/devin/config.json` | XDG path | No | | `.devin/config.json` | Walking up from cwd | Yes (committed) | | `.devin/config.local.json` | Walking up from cwd | No (gitignored) | | `.devin/skills/*/SKILL.md` | Project root | Yes (committed) | | `~/.config/devin/skills/*/SKILL.md` | XDG path | No | | `AGENTS.md` | Project root | Yes (committed) | | `~/.config/devin/AGENTS.md` | XDG path | No | **Windows:** Paths shown as `~/.config/devin/` use the XDG convention for Linux/macOS. On Windows, these resolve to `%APPDATA%\devin\` (typically `C:\Users\\AppData\Roaming\devin\`). # Configuration Import Source: https://docs.devin.ai/cli/reference/configuration/read-config-from Control how Devin CLI imports settings from Cursor, Windsurf, Claude Code, OpenCode, VS Code, and Zed Devin CLI can automatically import rules and configuration from other AI coding tools installed in your project. This happens when standard project rule files or configuration files from Cursor, Windsurf, Claude Code, OpenCode, VS Code, or Zed are detected in your workspace. *** ## How It Works When you start a session, Devin CLI checks for standard project rule files and configuration files from supported tools, then imports what it finds. ### Standard project rules | What's imported | Source files | | --------------- | ------------------------------------------------------------ | | Rules | `AGENTS.md`, `AGENTS.local.md`, `AGENT.md`, `.windsurfrules` | ### Cursor | What's imported | Source files | | --------------- | ------------------------------------------- | | Rules | `.cursor/rules/*.md`, `.cursor/rules/*.mdc` | | MCP servers | `.cursor/mcp.json` | ### Windsurf | What's imported | Source files | | --------------- | ------------------------------------------------------------------------------------------ | | Rules | `.windsurf/rules/*.md`, `.windsurf/global_rules.md` (at workspace root and subdirectories) | | Skills | `.windsurf/skills/` (project), `~/.codeium//skills/` (global, channel-dependent) | | MCP servers | `~/.codeium//mcp_config.json` (channel-dependent) | Devin CLI reads from the Windsurf config directory matching its own channel: stable reads from `~/.codeium/windsurf/`, next reads from `~/.codeium/windsurf-next/`, insiders reads from `~/.codeium/windsurf-insiders/`. `.windsurf/rules/` directories can exist at multiple levels in your project. Rules at the workspace root are loaded at session start. Rules in subdirectories are discovered lazily when the agent accesses files in that directory. Windsurf workflows (`.windsurf/workflows/` and `~/.codeium//global_workflows/`) are **not** imported as skills. ### Claude Code | What's imported | Source files | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Rules | `CLAUDE.md`, `~/.claude/CLAUDE.md` | | Skills | `.claude/skills/**/SKILL.md` | | Commands (as skills) | `.claude/commands/**/*.md` | | MCP servers | `.mcp.json`, `.claude/settings.json`, `.claude/settings.local.json`, `~/.claude.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json`, `~/.claude/mcp_servers.json` | ### OpenCode | What's imported | Source files | | --------------- | ---------------------------------------------------------------------- | | MCP servers | `opencode.json` (project), `~/.config/opencode/opencode.json` (global) | OpenCode uses a different MCP schema from the standard format. Commands can be arrays or strings, environment variables use the `"environment"` key, and servers use an `"enabled"` flag (inverted from the standard `"disabled"` flag). These are automatically converted during import. ### VS Code | What's imported | Source files | | --------------- | --------------------------------- | | MCP servers | `.vscode/mcp.json` (project only) | VS Code uses a `"servers"` key instead of the standard `"mcpServers"` key. ### Zed | What's imported | Source files | | --------------- | ---------------------------------------------------------------------- | | MCP servers | `.zed/settings.json` (project), `~/.config/zed/settings.json` (global) | Zed uses a `"context_servers"` key in its settings file. *** ## Disabling Configuration Import To stop importing from a specific tool, set it to `false` in your config: ```json theme={null} // ~/.config/devin/config.json // (on Windows: %APPDATA%\devin\config.json) { "read_config_from": { "agents_standard": false, "cursor": false, "windsurf": false, "claude": false, "opencode": false, "vscode": false, "zed": false } } ``` ```json theme={null} // .devin/config.json { "read_config_from": { "windsurf": false } } ``` You can disable imports selectively — for example, import from Cursor but not Windsurf: ```json theme={null} { "read_config_from": { "cursor": true, "windsurf": false } } ``` *** ## Options | Option | Type | Default | Description | | ----------------- | ------- | ------- | --------------------------------------------------------------------------------------------------- | | `agents_standard` | boolean | `true` | Import standard project rules from `AGENTS.md`, `AGENTS.local.md`, `AGENT.md`, and `.windsurfrules` | | `cursor` | boolean | `true` | Import rules and MCP servers from Cursor config files | | `windsurf` | boolean | `true` | Import rules, skills, and MCP servers from Windsurf | | `claude` | boolean | `true` | Import rules, skills, commands, and MCP servers from Claude Code | | `opencode` | boolean | `true` | Import MCP servers from OpenCode config files | | `vscode` | boolean | `true` | Import MCP servers from VS Code config files | | `zed` | boolean | `true` | Import MCP servers from Zed settings files | Setting a value to `true` (or leaving it unset) enables import. Setting it to `false` disables import for that tool. *** ## Default Behavior If you don't explicitly configure `read_config_from`, all imports are enabled by default. Set any option to `false` to disable imports from that tool. # Keyboard Shortcuts Source: https://docs.devin.ai/cli/reference/keyboard-shortcuts Common keyboard shortcuts in Devin CLI ## Input Shortcuts These shortcuts work while typing at the prompt. | Shortcut | Description | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | | `Enter` | Submit your message | | `Shift+Enter`\* or `Alt+Enter` | Insert a newline (for multi-line input) | | `Shift+Tab` | Cycle between modes (Normal, Accept Edits, Plan, Bypass, Autonomous) | | `Ctrl+C` | Cancel current input (clears text), or cancel running agent | | `Ctrl+D` | Exit (when input is empty) | | `Esc` | Cancel running agent | | `Ctrl+G` | Open external editor for composing your message | | `Ctrl+R` | Open fuzzy search over previous prompts and insert the selected prompt | | `Ctrl+O` | Open full-screen viewer for the thinking trace | | `Ctrl+L` | Redraw / refresh the screen | | `Ctrl+V` or `Shift+Insert` | Paste from clipboard (images appear in input area; use Left/Right to navigate, Backspace to remove) | | `!` | Enter bash mode to run a shell command directly (when input is empty). Press `Backspace` or `Esc` on an empty input to exit bash mode | | `@` | Open file/directory autocomplete to add context | On macOS, `Alt` is the `Option` key. Some shortcuts below use `Alt` (Option) as a modifier. We recommend [configuring Option as Meta](/cli/reference/terminal-compatibility#configuring-option-as-meta-on-macos) for the best experience. \* Requires a [compatible terminal](/cli/reference/terminal-compatibility). Terminals that do not support the Kitty keyboard protocol cannot distinguish `Shift+Enter` from `Enter`. Use `Alt+Enter` or `Ctrl+J` instead. *** ## Mode & Model Shortcuts | Shortcut | Description | | ------------------------ | ------------------------------------------------------------------------------------ | | `Shift+Tab` | Cycle to the next mode (Normal → Accept Edits → Plan → Bypass → Autonomous → Normal) | | `Alt+T` (macOS: `Opt+T`) | Cycle thinking level for the current model | You can also switch modes with slash commands: `/normal`, `/plan`, `/bypass`, or `/mode `. Use `/ask ` as a oneshot command to ask questions without switching modes. *** ## Text Editing The input uses readline-style or Emacs-style keybindings for text editing. # Permissions Source: https://docs.devin.ai/cli/reference/permissions Control what the agent can do with fine-grained permission rules The permission system controls which actions the agent can perform without asking for your approval. You can pre-approve safe actions, block dangerous ones, and always prompt for sensitive operations. *** ## Default Permission Behavior Devin CLI uses a tiered permission system to balance power and safety. The default behavior depends on the current [mode](/cli/essential-commands#modes): Each cell shows whether that tool runs automatically (**Auto**, no prompt) or waits for your approval (**Prompt**) in that mode: | Tool type | Example | Normal | Accept Edits | Bypass | Autonomous (sandbox) | | ----------------------------- | ---------------------- | ------ | ------------------- | ------ | -------------------- | | Read-only | File reads, grep, glob | Auto | Auto | Auto | Auto | | Fetch | HTTP requests | Prompt | Prompt | Auto | Auto | | Bash commands | Shell execution | Prompt | Prompt | Auto | Auto | | File edits via `edit`/`write` | Edit/write files | Prompt | Auto (in workspace) | Auto | Prompt | In **Normal mode** (the default), read-only operations are auto-approved while writes and shell commands require your explicit approval. Each time you approve an action, you can choose to allow it once, for the session, or permanently for the project. In **Accept Edits mode**, file edits within the workspace are auto-approved, but shell commands and writes outside the workspace still prompt. In **Bypass mode**, all tool calls are auto-approved without prompting. In **Autonomous mode**, shell commands and network fetches auto-approve because the OS-level sandbox enforces what they can touch. Direct file edits via the `edit`/`write` tools still prompt, because those tools operate outside the sandbox. Autonomous is only available when the [OS-level sandbox](#autonomous-mode) is active. Bypass and Autonomous modes do **not** override organization-level permissions. Admin-enforced deny and ask rules configured via [Team Settings](/cli/enterprise/team-settings) remain active regardless of the user's permission mode. See [Precedence](#precedence) for details. ### Autonomous Mode Autonomous is the permission mode that pairs with the `--sandbox` flag. Conceptually it is roughly "Accept Edits in the current workspace" plus the ability to run any shell command, with both behaviors contained by the OS-level sandbox. When sandbox is active: * **It is the only permission mode available.** Normal, Accept Edits, and Bypass are hidden in sandbox sessions. Plan mode remains available. * **Shell commands and fetches auto-approve** instead of prompting, because the sandbox enforces what they can read, write, and reach over the network. * **Direct file edits via the `edit` and `write` tools still prompt.** These tools run inside the CLI process rather than inside the sandbox, so they cannot be bounded by it. Granting a `Write(...)` scope at the prompt dynamically expands the sandbox so subsequent shell commands can write there. * **Scopes granted mid-session dynamically expand the sandbox** for subsequent commands. ```bash theme={null} devin --sandbox --permission-mode autonomous ``` Use Bypass when you want unrestricted execution without OS-level isolation; use `--sandbox` (which selects Autonomous) when you want unattended execution with OS-enforced limits on filesystem and network access. See the [sandbox configuration reference](/cli/reference/configuration/config-file#sandbox) for details on writable/readable roots and domain filtering, and [Team Settings → Sandbox Enforcement](/cli/enterprise/team-settings#sandbox-enforcement) for enterprise controls. *** ## How Permissions Work When the agent calls a tool, the permission system checks your rules in priority order: 1. **Deny rules** — Checked first. If matched, the action is blocked immediately. 2. **Ask rules** — Checked second. If matched, you're always prompted (overrides any allow rules). 3. **Allow rules** — Checked last. If matched, the action proceeds without prompting. 4. **Default** — If no rule matches, you're prompted for approval. Because deny is checked before ask, and ask is checked before allow, a deny rule always wins. If the same scope matches both a deny and an ask rule, the deny takes effect. *** ## Configuration Add permissions to your config file's `permissions` section: On Windows, the user config path is `%APPDATA%\devin\config.json` (typically `C:\Users\\AppData\Roaming\devin\config.json`) rather than `~/.config/devin/config.json`. See [Configuration File](/cli/reference/configuration/config-file#file-locations) for details. ```json theme={null} // .devin/config.json { "permissions": { "allow": [ "Read(src/**)", "Exec(npm run)" ], "deny": [ "Exec(rm)" ] } } ``` ```json theme={null} // ~/.config/devin/config.json { "permissions": { "allow": [ "Read(**)", "Exec(git)" ] } } ``` ```json theme={null} // .devin/config.local.json { "permissions": { "allow": [ "Exec(docker compose)" ] } } ``` *** ## Permission Syntax There are two types of permission matchers: **scope-based** (controlling what paths/commands/URLs are accessible) and **tool-based** (controlling which tools can be used). ### Scope-Based Permissions Controls file read access. The glob pattern matches file paths. ```json theme={null} "allow": [ "Read(src/**)", // All files under src/ "Read(~/.config/**)", // Home config files "Read(/tmp/**)" // Temp directory ] ``` Directory paths automatically match all files within them. Controls file write/edit access. ```json theme={null} "allow": [ "Write(src/**)", // Can write anywhere in src/ "Write(tests/**)" // Can write test files ], "deny": [ "Write(*.lock)", // Can't modify lock files "Write(.env*)" // Can't modify env files ] ``` Controls shell command execution. Matches commands that start with the given prefix. ```json theme={null} "allow": [ "Exec(git)", // git, git status, git commit... "Exec(npm run)", // npm run test, npm run build... "Exec(python)" // python, python script.py... ], "deny": [ "Exec(rm)", // Blocks rm, rm -rf, etc. "Exec(sudo)" // Blocks sudo commands ] ``` `Exec(git)` matches "git", "git status", "git commit -m 'msg'" but NOT "gitk" or "github-cli". The prefix must match as a complete word. Controls HTTP fetch access using URL patterns. ```json theme={null} "allow": [ "Fetch(https://api.github.com/*)", // GitHub API "Fetch(https://*.example.com/*)", // All example.com subdomains "Fetch(domain:npmjs.org)" // Any URL on npmjs.org ] ``` URL patterns follow the [WHATWG URL Pattern](https://urlpattern.spec.whatwg.org/) standard. The `domain:` shorthand matches any path on the exact domain. ### Tool-Based Permissions Match by tool name to control entire tools: ```json theme={null} { "permissions": { "deny": [ "edit", // Block all file edits "exec" // Block all command execution ], "allow": [ "read", // Allow all file reads "grep", // Allow all searches "glob" // Allow all file finding ] } } ``` **Available tool names:** `read`, `edit`, `grep`, `glob`, `exec` ### MCP Tool Permissions Control access to MCP server tools: ```json theme={null} { "permissions": { "allow": [ "mcp__github__list_issues", // Specific tool on specific server "mcp__github__*", // All tools on github server "mcp__*" // All MCP tools ], "deny": [ "mcp__github__delete_repo" // Block specific dangerous tool ] } } ``` | Pattern | Matches | | ------------------- | ------------------------ | | `mcp__server__tool` | One specific tool | | `mcp__server__*` | All tools on a server | | `mcp__*` | All MCP tools everywhere | *** ## Path Patterns Glob patterns in `Read()` and `Write()` support: | Pattern | Meaning | | ------- | ----------------------------------------------- | | `*` | Any characters in a single path segment | | `**` | Any characters across path segments (recursive) | | `~` | Home directory expansion | **Examples:** ```json theme={null} "allow": [ "Read(**)", // All files everywhere "Read(src/**/*.ts)", // All TypeScript in src/ "Write(~/projects/myapp/**)" // Write to specific project ] ``` Use an absolute path prefix (e.g., `Read(/**)`) when you want to match all files on the system. A bare `Read(**)` without a leading `/` is resolved relative to your current working directory, so it only matches files under that directory — not files accessed via absolute paths elsewhere. *** ## Persistence Options When the agent asks for permission during a session, you can choose how to save your decision: | Option | Where it's saved | Shared with team? | | ------------------------- | ------------------------------------------------------------------------ | ----------------- | | Allow once | Not saved | No | | Allow for session | In memory only | No | | Allow for project | `.devin/config.json` | Yes | | Allow for project (local) | `.devin/config.local.json` | No | | Allow globally | `~/.config/devin/config.json` (`%APPDATA%\devin\config.json` on Windows) | No | ### MCP Server-Level Grants When prompted for a specific MCP tool (e.g., `list_issues` on the Figma server), the permission prompt also offers broader server-level options: | Option | Effect | | --------------------------------------------- | ---------------------------------------------------------- | | Allow this tool (this session) | Grants access to the specific tool for the current session | | Always allow this tool | Persists the specific tool grant to config | | Allow all tools on this server (this session) | Grants access to every tool on the server for the session | | Always allow tools on this server | Persists server-wide access to config | This lets you quickly grant blanket access to a trusted MCP server without approving each tool individually. *** ## Precedence When multiple permission sources define rules, they're merged with this precedence (highest first): 1. Organization/team settings (if enterprise) 2. Session-level grants (interactive approvals) 3. Project local config (`.devin/config.local.json`) 4. Project config (`.devin/config.json`) 5. User config (`~/.config/devin/config.json`; `%APPDATA%\devin\config.json` on Windows) Organization-level denials cannot be overridden by project or user config. This ensures enterprise policies are enforced. *** ## Examples ### Minimal Development Setup Allow common read-only operations, prompt for everything else: ```json theme={null} { "permissions": { "allow": [ "Read(**)", "Exec(git status)", "Exec(git diff)", "Exec(git log)" ] } } ``` ### Full Trust for a Project Auto-approve most operations within the project: ```json theme={null} { "permissions": { "allow": [ "Read(**)", "Write(src/**)", "Write(tests/**)", "Exec(npm)", "Exec(git)", "Exec(node)" ], "deny": [ "Exec(rm -rf)", "Exec(sudo)", "Write(.env*)" ] } } ``` ### Locked-Down Enterprise Restrict to specific safe operations, always prompt for writes: ```json theme={null} { "permissions": { "allow": [ "Read(src/**)", "Exec(git status)", "Exec(git diff)", "Exec(npm run lint)" ], "deny": [ "Exec(rm)", "Exec(sudo)", "Write(.env*)" ], "ask": [ "Write(**)", "exec" ] } } ``` In this example, writes to `.env*` are denied outright, all other writes always prompt the user, and only a few read-only commands are auto-approved. Since deny is checked before ask, the `.env*` denial takes priority over the `Write(**)` ask rule. # Terminal Compatibility Source: https://docs.devin.ai/cli/reference/terminal-compatibility Supported terminals and recommendations for the best Devin CLI experience Devin CLI works across a wide range of terminal emulators, but some terminals offer a better experience than others. This page covers compatibility levels, recommendations, and configuration tips. *** ## Compatibility Overview Terminals are grouped into three tiers based on their feature support: ### Fully Supported (all features work) These terminals support the [Kitty keyboard protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol/), which enables reliable detection of key combinations like `Shift+Enter` for multi-line input. | Terminal | Platform | Notes | | ------------------------------------------- | ---------------------- | --------------------------------------------------------------------- | | [Kitty](https://sw.kovidgoyal.net/kitty/) | macOS†, Linux | Recommended for power users. Used by the developers of Devin CLI. | | [Ghostty](https://ghostty.org/) | macOS†, Linux | Recommended for power users. Used by the developers of Devin CLI. | | [WezTerm](https://wezfurlong.org/wezterm/) | macOS†, Linux, Windows | Recommended for power users. | | [iTerm2](https://iterm2.com/) | macOS† | Recommended for most users. Version 3.5+ required for best support. | | [Windows Terminal](https://aka.ms/terminal) | Windows | Recommended for most users. 1.25 or higher required for best support. | ### Supported (some features limited) These terminals work with Devin CLI but are not ideal because they do not support the Kitty keyboard protocol. For example, `Shift+Enter` will not insert a newline — use `Alt+Enter` or `Ctrl+J` instead. | Terminal | Platform | Notes | | -------------------------------------------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------- | | [Terminal.app](https://support.apple.com/guide/terminal/welcome/mac) | macOS† | Built-in macOS terminal. Requires [Option-as-Meta configuration](#configuring-option-as-meta-on-macos) for `Alt` shortcuts. | | Git Bash | Windows | Included with [Git for Windows](https://git-scm.com/download/win). | | DEC VT100 | Various | Set terminal mode to `legacy` in `/config`. | | Generic ANSI terminals | Various | Any terminal with basic ANSI escape code support. | | [Alacritty](https://alacritty.org/) | macOS†, Linux, Windows | Strongly discouraged / not recommended for best performance. | † On macOS, we recommend [configuring Option as Meta](#configuring-option-as-meta-on-macos) for the best experience with `Alt`-based shortcuts. On macOS terminals that have not been configured for Option-as-Meta, `Alt` (Option) shortcuts like `Alt+Enter` for multi-line input won't work. See [Configuring Option-as-Meta on macOS](#configuring-option-as-meta-on-macos) below. ### Unsupported These terminals are not supported and may exhibit significant issues. We highly recommend switching to a supported terminal. | Terminal | Platform | Notes | | ----------------- | -------- | --------------------------------------------------------------------------------------- | | cmd.exe (conhost) | Windows | Legacy Windows command prompt. Use [Windows Terminal](https://aka.ms/terminal) instead. | *** ## Recommendations | Platform | Recommendation | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | **Windows** | [Windows Terminal](https://aka.ms/terminal) 1.25 or higher | | **macOS** (general) | [iTerm2](https://iterm2.com/) | | **macOS / Linux** (power users) | [Kitty](https://sw.kovidgoyal.net/kitty/), [Ghostty](https://ghostty.org/), or [WezTerm](https://wezfurlong.org/wezterm/) | *** ## Configuring Option-as-Meta on macOS On macOS, the Option key is used as a compose key by default in most terminals, which means `Alt`-based shortcuts (like `Alt+Enter` for multi-line input or `Alt+T` for cycling thinking level) won't work until you configure the terminal to treat Option as Meta/Alt. 1. Open **iTerm2 > Settings** (or press `Cmd+,`) 2. Go to **Profiles > Keys > General** 3. Set **Left Option Key** to **Esc+** 4. Optionally set **Right Option Key** to **Esc+** as well [iTerm2 documentation](https://iterm2.com/documentation-preferences-profiles-keys.html) 1. Open **Terminal > Settings** (or press `Cmd+,`) 2. Go to **Profiles** and select your active profile 3. Click the **Keyboard** tab 4. Check **Use Option as Meta Key** [Apple documentation](https://support.apple.com/guide/terminal/change-profiles-keyboard-settings-trmlkbrd/mac) Add the following to your `alacritty.toml` configuration file: ```toml theme={null} [keyboard] option_as_alt = "Both" ``` [Alacritty configuration reference](https://alacritty.org/config-alacritty.html) Add the following to your `kitty.conf` configuration file: ```text theme={null} macos_option_as_alt yes ``` Restart Kitty after making this change. [Kitty documentation](https://sw.kovidgoyal.net/kitty/conf/#opt-kitty.macos_option_as_alt) Add the following to your Ghostty configuration file: ```text theme={null} macos-option-as-alt = true ``` Restart Ghostty after making this change. [Ghostty documentation](https://ghostty.org/docs/config/reference#macos-option-as-alt) Add the following to your `~/.wezterm.lua` configuration file: ```lua theme={null} config.send_composed_key_when_left_alt_is_pressed = false config.send_composed_key_when_right_alt_is_pressed = false ``` [WezTerm documentation](https://wezfurlong.org/wezterm/config/lua/config/send_composed_key_when_left_alt_is_pressed.html) # Sandbox Source: https://docs.devin.ai/cli/sandbox OS-level isolation for Devin CLI sessions: how the sandbox works, network filtering, and enterprise enforcement. The `--sandbox` flag runs the CLI with OS-level isolation, enforcing the active Read and Write permission scopes at the operating-system level and optionally restricting network traffic. ## How the sandbox works When the sandbox is active: * **Writable paths** are derived from granted `Write(...)` permission scopes plus the workspace directory * **Readable paths** are derived from granted `Read(...)` scopes (platform defaults like `/usr/bin` are always readable) * Scopes granted mid-session dynamically expand the sandbox for subsequent commands If sandbox resolution fails (e.g., the sandboxing tools are unavailable on the user's platform), the CLI will **refuse to start** rather than running unsandboxed. This fail-closed behavior applies whether sandbox was enabled by a [team setting](/cli/enterprise/team-settings#sandbox-enforcement) or by the user passing `--sandbox` directly, ensuring the security intent is never silently bypassed. Common causes of sandbox resolution failure: * **Windows**: OS-level sandboxing is not currently supported on Windows. Sessions on Windows will hard-fail when `--sandbox` is passed or when sandbox enforcement is **Required**, including when the CLI runs as an ACP server inside an IDE (e.g., Devin Desktop). * **Linux**: Sandboxing requires `bubblewrap` (`bwrap`) and `socat` to be installed. Sessions hard-fail with installation instructions when these are missing. * **Permission scope errors**: Invalid paths in permission scopes that can't be resolved. ## Network filtering Sandbox network filtering is currently unstable. If you need this feature, please reach out to your account representative for stability timelines. Configure domain-level network filtering for the sandbox in the [`sandbox` section of your config file](/cli/reference/configuration/config-file#sandbox) (user config only). When `--sandbox` is active and domain filtering is configured, a managed network proxy starts on loopback and the sandbox restricts all child traffic to route through it. | Option | Type | Default | Description | | ----------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------- | | `allowed_domains` | string\[] | `[]` | Domain patterns allowed through the proxy. When non-empty, only matching domains are allowed (allowlist mode) | | `denied_domains` | string\[] | `[]` | Domain patterns always blocked. Deny rules take precedence over allow rules | | `network_mode` | string | `"full"` | `"full"` allows all HTTP methods; `"limited"` allows only GET/HEAD/OPTIONS | **Domain pattern syntax:** | Pattern | Matches | | ---------------- | ----------------------------- | | `example.com` | Exact match only | | `*.example.com` | Any subdomain (not the apex) | | `**.example.com` | Apex domain and any subdomain | **Example:** ```json theme={null} { "sandbox": { "allowed_domains": [ "github.com", "**.npmjs.org", "**.crates.io", "**.pypi.org" ], "denied_domains": ["evil.example.com"], "network_mode": "full" } } ``` Domain filtering applies when the sandbox is active (`--sandbox`). Without `--sandbox`, the sandbox section is ignored. ## Excluded commands Sometimes a specific command needs to run *outside* the sandbox — for example `git` commands that must access credentials or hooks the sandbox blocks. The `sandbox.excluded` config section lets you exclude matching commands from sandbox isolation using the same `Exec(...)` rule syntax as [permissions](/cli/reference/permissions): | Option | Type | Description | | ---------------- | --------- | -------------------------------------------------------------------------- | | `excluded.allow` | string\[] | Matching commands run outside the sandbox automatically | | `excluded.ask` | string\[] | Matching commands run outside the sandbox after the user approves a prompt | | `excluded.deny` | string\[] | Matching commands are never excluded — they always stay inside the sandbox | **Example:** ```json theme={null} { "sandbox": { "excluded": { "allow": ["Exec(git status *)"], "ask": ["Exec(git push *)"], "deny": ["Exec(git tag *)"] } } } ``` **Rule resolution:** for each command, the most specific matching rule wins within a source (e.g., `Exec(git push *)` beats `Exec(git *)`), and when both user config and [team settings](#enterprise-excluded-commands) match, the more restrictive verdict wins (`deny` > `ask` > `allow`). Commands with no matching rule — including when `sandbox.excluded` is not configured at all — always run inside the sandbox. * Only `Exec(...)` rules are supported in `sandbox.excluded`; any other rule type (e.g., `Read(...)`, `Write(...)`) is ignored with a warning. * Exclusion is fail-closed: if a command can't be safely resolved (e.g., it can't be parsed), it stays inside the sandbox. * Exclusions apply to the default per-command exec path. Commands run through a persistent PTY shell (interactive sessions, or when `pty_for_noninteractive_exec` is enabled) always stay inside the sandbox. ## Enterprise enforcement Enterprise admins can control sandbox behavior for their entire organization via [Team Settings](/cli/enterprise/team-settings#sandbox-enforcement). ### Sandbox enforcement mode Set the enforcement level for the `--sandbox` flag across your organization: * **Optional** (default) — Users choose whether to pass `--sandbox`. No enforcement. * **Required** — The `--sandbox` flag is forced on for all users, even if they don't pass it on the command line. All CLI sessions run with OS-level file system sandboxing that enforces Read/Write permission scopes. A future **Strict** mode may lock down sandbox configuration entirely, preventing users from modifying sandbox settings. Ensure all target machines are provisioned before setting sandbox enforcement mode to **Required** across your organization. If any users are on Windows, they will be unable to run the CLI until OS-level sandboxing is supported on Windows or the policy is relaxed to **Optional**. ### Enterprise domain filtering Admins can also configure organization-wide domain allowlists and denylists: * **Domain allowlist** — When set, **only** the domains in this list are reachable through the sandbox network proxy. This list is **authoritative**: it completely replaces any user-configured `allowed_domains`. Users cannot add additional domains to bypass admin restrictions. * **Domain denylist** — Domains that are always blocked. Enterprise denied domains are **additive**: they are merged with the user's local `denied_domains`, making the combined list more restrictive. **How enterprise and user domain lists interact:** | Scenario | Enterprise config | User config | Effective result | | -------------------- | --------------------------------- | --------------------------------- | ------------------------------------------------------------ | | Admin sets allowlist | `allowed_domains: ["github.com"]` | `allowed_domains: ["npmjs.org"]` | Only `github.com` is allowed (enterprise replaces user list) | | Admin sets denylist | `denied_domains: ["evil.com"]` | `denied_domains: ["risky.io"]` | Both `evil.com` and `risky.io` are blocked (merged) | | No admin allowlist | `allowed_domains: []` | `allowed_domains: ["github.com"]` | User's allowlist is used | Because the user's local `denied_domains` are preserved and merged additively, a user could deny a domain that appears in the enterprise allowlist. This is intentional: the combined effect is always more restrictive, never less. If this causes access issues, the user should remove the conflicting entry from their local config. ### Enterprise excluded commands Admins can also set organization-wide [excluded command](#excluded-commands) rules in team settings: * **Excluded allow / ask** — `Exec(...)` rules for commands that may run outside the sandbox across the organization, automatically or after a prompt. * **Excluded deny** — `Exec(...)` rules for commands that must never run outside the sandbox. A team `deny` overrides any user-level `allow` or `ask` for matching commands, so users cannot exclude commands their admins have locked down. Team and user rules are resolved together: the most specific matching rule wins within each source, and the more restrictive verdict wins across sources (`deny` > `ask` > `allow`). **Example: lock down all exclusions except `gh`.** A wildcard `deny` with an `allow` carve-out keeps every command inside the sandbox except `gh`, regardless of what users configure locally. These values go into the team-settings excluded-commands configuration (not the user config file, so there is no enclosing `sandbox` key): ```json theme={null} { "excluded": { "deny": ["Exec(**)"], "allow": ["Exec(gh *)"] } } ``` Because the more specific `Exec(gh *)` rule beats the wildcard `Exec(**)`, `gh` commands run outside the sandbox while everything else stays inside — and the team-level wildcard `deny` overrides any user-level `allow` or `ask` rules for other commands. ## Further reading * [Team Settings](/cli/enterprise/team-settings#sandbox-enforcement) — enterprise sandbox enforcement and domain filtering * [Config file reference](/cli/reference/configuration/config-file#sandbox) — the user-level `sandbox` config section * [Permissions](/cli/reference/permissions) — permission scopes that drive sandbox path resolution # Shell Integration [Feature Preview] Source: https://docs.devin.ai/cli/shell-integration Wrap your shell with Devin to invoke it instantly and give Devin visibility into your recent commands. Shell integration is a **Feature Preview**. It is available on macOS, Linux, and WSL with Bash, Zsh, and Fish. Shell integration is not yet supported on Windows (PowerShell or CMD). You can still run Devin CLI on Windows — this feature just isn't available there yet. It is feature complete but may interact poorly with other shell functionality. If you run into something incompatible please let us know! Shell integration wraps your existing shell session so that Devin runs alongside it. Once set up, you can: * Hit **Ctrl+G** (configurable) anywhere in your shell to invoke Devin with your current command line as context * Type `# ` and press Enter to pass it straight to Devin (Zsh only) * Give Devin automatic visibility into your recent shell commands and their output We strongly recommend using `zsh` over `bash` or `fish` for best support. *** ## Setup Run the setup command to install shell integration into your shell config file: ```bash theme={null} devin shell setup ``` This adds managed blocks to your shell rc file (`~/.bashrc`, `~/.zshrc`, or `~/.config/fish/config.fish`). Then restart your terminal or source the config: ```bash theme={null} source ~/.bashrc ``` ```bash theme={null} source ~/.zshrc ``` ```fish theme={null} source ~/.config/fish/config.fish ``` You can also target a specific shell explicitly: ```bash theme={null} devin shell setup bash devin shell setup zsh devin shell setup fish ``` Shell integration is separate from the `devin setup` wizard. Running `devin setup` does **not** install shell integration — you must run `devin shell setup` separately. *** ## Features