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

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

Security

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

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:

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

Command displayed

The command is shown to the user in the dashboard or channel.

User decides

The user approves or rejects the command.

Execution or fallback

If approved, the command executes. 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

Getting Started

Installation

Channels

Agents

Connectors

Tools

Concepts

Memory

Model Router

Overview

Usage

Parameters

Security

Sandbox Modes

Tool Policies

Approval Flow

Working Directory

Timeouts

Output Handling

​Overview

​Usage

​Parameters

​Security

​Sandbox Modes

​Tool Policies

​Approval Flow

​Working Directory

​Timeouts

​Output Handling

Overview

Usage

Parameters

Security

Sandbox Modes

Tool Policies

Approval Flow

Working Directory

Timeouts

Output Handling