> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcore.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Exec

> Execute shell commands on your machine with security controls

## Overview

The Exec capability lets CORE run shell commands on your machine. This is powerful but requires careful configuration - you control exactly which commands are allowed through allow/deny patterns.

***

## Security Model

Commands are validated against three layers before execution:

1. **Built-in deny list** — common-sense blocks like `rm -rf /`, `sudo`, `curl … | bash`. Skipped only if `allowUnsafe: true`.
2. **User deny patterns** — checked next; takes precedence over allow.
3. **User allow patterns** — if configured, the command must match at least one. If empty, all non-denied commands are allowed.

In addition, when at least one folder is registered the `dir` parameter must resolve into a folder with the `exec` scope — otherwise the call fails with `FOLDER_SCOPE_DENIED`.

***

## Configuration

Configure exec patterns through the CLI:

```bash theme={null}
corebrain exec config
```

Or set them in your gateway slots configuration.

### Pattern Format

Patterns use the format `Bash(<glob>)`:

```
Bash(git *)        # Allow all git commands
Bash(npm run *)    # Allow npm run scripts
Bash(ls *)         # Allow ls commands
Bash(*)            # Allow everything (use with caution)
```

### Example Configuration

```json theme={null}
{
  "exec": {
    "allow": [
      "Bash(git *)",
      "Bash(npm run *)",
      "Bash(ls *)",
      "Bash(cat *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)"
    ],
    "defaultDir": "/Users/me/projects"
  }
}
```

***

## Gateway Tool

### exec\_command

Execute a shell command:

```json theme={null}
{
  "command": "git status",
  "dir": "/Users/me/projects/myapp",
  "timeout": 30000
}
```

| Parameter | Required | Description                                                                                                                                               |
| --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `command` | Yes      | The command to execute                                                                                                                                    |
| `dir`     | No       | Working directory. Must resolve into an `exec`-scoped registered folder when folders exist. Falls back to `ExecConfig.defaultDir` (deprecated) otherwise. |
| `timeout` | No       | Timeout in milliseconds (default: 30000)                                                                                                                  |

### Response

```json theme={null}
{
  "success": true,
  "result": {
    "command": "git status",
    "dir": "/Users/me/projects/myapp",
    "exitCode": 0,
    "stdout": "On branch main\nnothing to commit, working tree clean",
    "stderr": null
  }
}
```

***

## Use Cases

**Git operations:** CORE checks branch status, creates commits, pushes changes:

```
"Check if there are uncommitted changes in the API repo"
```

**Build and test:** Run build scripts and test suites:

```
"Run the test suite and tell me if anything fails"
```

**System checks:** Query system state:

```
"How much disk space is left on my machine?"
```

**File operations:** Read and process files:

```
"Show me the last 50 lines of the server log"
```

***

## Recommended Patterns

### Development Workflow

```json theme={null}
{
  "allow": [
    "Bash(git *)",
    "Bash(npm *)",
    "Bash(pnpm *)",
    "Bash(yarn *)",
    "Bash(cargo *)",
    "Bash(make *)"
  ]
}
```

### Read-Only Access

```json theme={null}
{
  "allow": [
    "Bash(ls *)",
    "Bash(cat *)",
    "Bash(head *)",
    "Bash(tail *)",
    "Bash(grep *)",
    "Bash(find *)"
  ]
}
```

### Always Deny

```json theme={null}
{
  "deny": [
    "Bash(rm -rf *)",
    "Bash(sudo *)",
    "Bash(chmod 777 *)",
    "Bash(curl * | bash)",
    "Bash(wget * | bash)"
  ]
}
```

***

## Notes

* Commands run with your user permissions (the user the gateway service runs as).
* Output is captured and returned (`stdout`, `stderr`, `exitCode`).
* Long-running commands should set `timeout`.
* Commands that require user input will hang — avoid interactive commands. Use `coding_ask` with the appropriate agent for interactive flows.
* The `exec` slot can be turned off entirely in `corebrain gateway config` — disabled slots are not just hidden in the manifest, their HTTP route is not registered at all.