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

# Command Execution

> The exec tool — run bash commands, scripts, and system operations from your agent.

## Overview

The `exec` tool gives your agent the ability to run bash commands on the host system. This is one of the most powerful tools available, enabling the agent to install software, manage files, run scripts, query APIs, and automate system tasks.

## Usage

The agent calls the `exec` tool with a command string:

```json theme={null}
{
  "tool": "exec",
  "input": {
    "command": "ls -la /Users/sem/projects/",
    "timeout": 30000
  }
}
```

The command runs in a bash shell and returns stdout, stderr, and the exit code.

## Parameters

| Parameter | Type   | Default   | Description                 |
| --------- | ------ | --------- | --------------------------- |
| `command` | string | required  | The bash command to execute |
| `timeout` | number | 120000    | Timeout in milliseconds     |
| `cwd`     | string | workspace | Working directory           |

## Security

<Warning>
  Command execution is the highest-risk tool. ArgentOS provides several layers of protection.
</Warning>

### Sandbox Modes

| Mode             | Behavior                                                          |
| ---------------- | ----------------------------------------------------------------- |
| **Unrestricted** | Commands run with no restrictions                                 |
| **Sandboxed**    | Dangerous commands (`rm -rf`, `sudo`, etc.) require user approval |
| **Locked**       | Command execution is disabled entirely                            |

### Tool Policies

You can configure per-command policies in `argent.json`:

```json theme={null}
{
  "agents": {
    "defaults": {
      "toolPolicies": {
        "exec": {
          "mode": "sandboxed",
          "blockedCommands": ["rm -rf /", "sudo"],
          "allowedPaths": ["/Users/sem/projects/"]
        }
      }
    }
  }
}
```

### Approval Flow

In sandboxed mode, when the agent attempts a command that requires approval:

<Steps>
  <Step title="Command displayed">
    The command is shown to the user in the dashboard or channel.
  </Step>

  <Step title="User decides">
    The user approves or rejects the command.
  </Step>

  <Step title="Execution or fallback">
    If approved, the command executes. If rejected, the agent is informed and can try an alternative.
  </Step>
</Steps>

## Working Directory

By default, commands run in the agent's workspace directory (configured in `argent.json`). The agent can specify a different `cwd` per command.

## Timeouts

<Info>
  Commands that exceed the timeout are killed. The default timeout is 120 seconds (2 minutes). Long-running tasks should be broken into smaller steps or run in the background.
</Info>

## Output Handling

* **stdout** is returned as the tool result
* **stderr** is included in the result with an error flag if the exit code is non-zero
* Large outputs may be truncated to fit within token limits