Runtime Security
Overview
Runtime security settings are used to configure security policies during Agent execution, and include three tabs: Contacts, Nodes, and Sandbox.
Tool Permission Levels
All tools are classified into three levels by security level:
| Level | Name | Behavior | Example Tools |
|---|---|---|---|
| P0 | Auto Execute | No user confirmation required, executes silently | Read File, List Directory, Memory Query |
| P1 | First-Time Confirmation | A permission dialog pops up for confirmation on the first call | Bash, Web Fetch, Skill |
| P2 | Confirm Every Time | Every call requires user confirmation | High-risk operations |
Permission Dialog
When the Agent calls a P1/P2 level tool, the interface displays a permission confirmation dialog:
| Information | Description |
|---|---|
| Tool Name | The tool requested to be called |
| Operation Description | The specific operation the tool will perform |
| Input Parameters | Details of the parameters the tool receives |
| Allow/Deny | User decision buttons |
Dangerous Command Preflight Check
The Bash tool has a built-in dangerous command preflight check mechanism (bashCommandPreflightCheck):
| Detection Type | Description |
|---|---|
| Destructive Path Detection | Detects high-risk deletion commands such as rm -rf / and rm -rf ~ |
| System Command Detection | Detects system-level commands such as shutdown and reboot |
| Data Loss Risk | Detects operations that may cause data loss |
When a dangerous command is detected, it is automatically escalated to P2 level (confirm every time).
Hook Interception
The system supports beforeToolUse and afterToolUse hooks:
| Hook | Trigger Timing | Capability |
|---|---|---|
| beforeToolUse | Before tool execution | Can block execution, modify parameters, and force escalation of the confirmation level |
| afterToolUse | After tool execution | Can log records and trigger follow-up operations |
Sandbox Execution Environment
The sandbox provides an isolated code execution environment that protects the security of the host system.
Technical Specifications
| Parameter | Value |
|---|---|
| Virtualization | Micro virtual machine with VirtIO Serial communication |
| Architecture Support | arm64, amd64 |
| Runtime | Full Linux environment (Bash, Python, Node.js) |
Three Execution Modes
| Mode | Description |
|---|---|
| local | Executes directly on the host system (default) |
| sandbox | Forces execution inside the sandbox |
| auto | The system automatically determines whether the sandbox is needed |
Installation Process
- System Detection: Check host system compatibility
- Download Runtime: Download the virtualization runtime
- Download Image: Download the Linux disk image
- Ready: The sandbox is available
Installation progress is displayed via the CoworkSandboxProgress component (stage, downloaded/total, percentage).
Status Detection
| Status Field | Description |
|---|---|
supported |
Whether the current system supports the sandbox |
runtimeReady |
Whether the runtime is installed |
imageReady |
Whether the image is installed |
downloading |
Whether a download is in progress |
Node Security
The Nodes tab configures security policies for multi-node scenarios:
| Configuration | Description |
|---|---|
| Node Visibility | Controls the external visibility scope of this node (account / enterprise) |
| Capability Declaration | Configures the list of tools and commands this node exposes externally |
| Remote Permissions | The handling policy when a remote node requests permission (for specific cross-node distribution rules, see Multi-Node Architecture — Permission Dialog Distribution Rules) |
Real-World Impact of Security Levels
Understanding the real impact of security levels on daily use:
| Scenario | P0 (Auto Execute) | P1 (First-Time Confirmation) | P2 (Confirm Every Time) |
|---|---|---|---|
| Agent needs to read a file | Reads silently, unnoticed | Dialog confirmation on first call, then automatic | A dialog asks every time |
Agent runs npm install |
Executes directly | Dialog confirmation on first call | A dialog every time |
Agent runs rm -rf node_modules |
Executes directly (dangerous!) | Dialog confirmation on first call | A dialog every time |
| Agent searches the web | Searches directly | Dialog confirmation on first call | A dialog every time |
Note: Under P0, the Bash tool silently executes any shell command, including deleting files. Although a dangerous command preflight check is built in, it cannot cover all risky commands. It is recommended to set Bash to at least P1.
Recommendations for Choosing Security Levels
| Usage Environment | Recommended Configuration | Reason |
|---|---|---|
| Personal dev machine, fully trusted | Bash: P1, Others: P0 | High efficiency, with Bash first-time confirmation to prevent accidental operations |
| Shared device / team environment | Bash: P2, Web Fetch: P1, Others: P0 | Every command execution requires confirmation, preventing accidental operations from affecting others |
| Novice users | All P1 or P2 | Learn the Agent's behavior patterns through confirmation dialogs |
| Demo environment | All P2 | Maximum security, fully controllable |
Real-World Impact of the Sandbox
| Comparison Dimension | Sandbox Off (local mode) | Sandbox On (sandbox mode) |
|---|---|---|
| File Operations | The Agent directly reads and writes your local files | The Agent operates in an isolated environment, not affecting local files |
| Installing Software | npm install installs directly into your project |
Installed inside the sandbox, disappears after exit |
| Dangerous Commands | rm -rf directly deletes your files |
Only affects the virtual file system inside the sandbox |
| Execution Speed | Native speed | Slightly slower (virtualization overhead) |
| Applicable Scenarios | Trusted daily development tasks | Running untrusted code, experimental operations |
How to Choose Among the Three Execution Modes
| Mode | Target Users | Description |
|---|---|---|
| local (default) | Everyday developers | All commands execute directly on the local machine, fastest speed |
| sandbox | Security-sensitive users | All commands execute in the sandbox, fully isolated |
| auto | Advanced users | The system decides automatically based on command risk—low-risk commands execute locally, high-risk commands go into the sandbox |
How to Install the Sandbox
- Open APP → Settings → Runtime Security → Sandbox tab
- The system automatically detects whether the current device supports the sandbox
- If supported, click the Install button
- Wait for the Runtime (about 50-100MB) and Image (about 200-500MB) to download
- Once downloaded, the sandbox status shows "Ready"
- Select sandbox or auto in the execution mode
Note: The sandbox currently only supports macOS (arm64 and amd64). Windows support is planned.
Real-World Impact of Node Visibility
| Setting | Impact |
|---|---|
| account (personal) | Only you can see and call this node when logged in on your other devices. Team members cannot see it. |
| enterprise (enterprise) | All members of the same workspace can see this node and can dispatch tasks to this device for execution via the Gateway. |
Tip: Setting it to enterprise means that conversations initiated by team members may execute Agent tasks on your computer (including file read/write and command execution). Please make sure you understand this impact and trust your team members.
Related Documentation
- Security Guardrails — Enterprise-level security policies
- Tool Management — Tool security level details
- Multi-Node Architecture — Node security mechanisms