Command Execution

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:

{
  "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

Security

Command execution is the highest-risk tool. ArgentOS provides several layers of protection:

Sandbox Modes

• 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:

{
  "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:

1. The command is shown to the user in the dashboard or channel
2. The user approves or rejects
3. If approved, the command executes
4. If rejected, the agent is informed and can try an alternative

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

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.

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