Sandbox

Constraints

File Access Control

After sandbox is enabled, CodeArts Agent CLI configures file directory access permissions as described below. You can also customize the access permissions based on your service requirements. For details, see Enabling Sandbox.

Enabling Sandbox

The following describes how to enable sandbox in the TUI development environment. In the CLI development environment, run the codearts run "prompt" --sandbox command.

1. Enter the TUI development environment.
   1. Open the root directory of the target project.
   2. Right-click in the blank area and select Open Windows Terminal here.
   3. Enter /codearts in the terminal and press Enter to enter the TUI development environment.

2. Enable the sandbox mode.
   1. In the TUI dialog box, enter /run-mode and press Enter. The Select Run Mode configuration is displayed.
   2. Click Sandbox to go to the Sandbox Config page.
      Figure 1 Selecting the Sandbox mode
      

3. Configure the command whitelist.

   Add prefixes of specific commands to the whitelist as required. Commands added to the whitelist bypass the sandbox mechanism and are executed outside the sandbox.

4. Select a network policy.

   Table 3 Network policy description

   Parameter	Description
   Allow All	Allows access to all internal and external network resources.
   Local Network Only	Only allows access to local networks (LAN/intranet); blocks all external internet access.
   Block All	Blocks all network connections and prohibits access to any internal or external resources.
   Custom Policy	Allows you to modify the JSON policy configuration file to customize the file and network access scope for processes within the project sandbox environment. For details, see 5.

5. Customize a network policy.
   1. In the Network Policy area, select Custom Policy and click Confirm. The Custom Policy page is displayed.
   2. In the JSON policy configuration file, modify the configuration as required.
      The initial structure of the file is as follows:

      {
          "filesystem": {
              "readWrite": [],
              "readOnly": []
          },
          "network": {
              "default": "Allow",
              "allow": [],
              "deny": []
          },
          "resources": {
              "cpu": 50,
              "memory": 8
          }
      }

      Table 4 Parameters in the JSON policy configuration file

      Parameter	Mandatory	Type	Description
      filesystem	No	filesystem Object	Used to precisely control the sandbox's access permissions to the local file system. If it is not set (the filesystem field is empty or does not exist), the sandbox's built-in file system security policy will be applied.
      network	No	network Object	Used to control the network access policies for processes within the sandbox, supporting configurations to allow or block access to specific network resources. If it is not set, network access is allowed by default.
      resources	No	resources Object	Used to define the maximum limit of computing resources during sandbox runtime, ensuring service stability and preventing resource abuse. If it is not set, the system will share the host machine's resources.

      Table 5 Fields in filesystem

      Parameter	Type	Default Value	Format of Supported Paths	Priority	Description
      readWrite	Array	[ ]	Absolute path: for example, /home/user/project or C:\Projects Relative path: for example, ./src or ./config Environment variable: $HOME (Linux/Mac) or %USERPROFILE% (Windows) Abbreviation of the home directory: ~	readOnly > readWrite > Default system policy If a specific path matches both readOnly and readWrite, readOnly shall be applied.	List of read/write paths.
      readOnly	Array	[ ]			List of read-only paths.

      Table 6 Fields in network

      Parameter	Type	Default Value	Priority	Description
      default	String	Allow	deny > allow > default If both allow and deny are configured, deny shall be applied.	Default network policy. Allow: access allowed. Deny: access denied. NOTE: This field supports two configuration formats: Domain:Port and IP address:Port. Wildcards are supported for the domain part, and CIDR notation is supported for IP addresses. Multiple ports can be separated with commas (,). If no port is specified, the policy applies to all ports by default.
      allow	Array	[ ]		List of network rules that allow access.
      deny	Array	[ ]		List of network rules that deny access.

      Table 7 Fields in resources

      Parameter	Type	Default Value	Min. Value	Description
      cpu	Integer	50	20	CPU usage, in percentage.
      memory	Integer	8	1	Memory size, in GB.

      The following is an example of the JSON policy configuration file:

      {
          "filesystem": {
              "readWrite": [
                  "/home/user/project/output",
                  "~/workspace/temp"
              ],
              "readOnly": [
                  "/etc/systemd",
                  "%USERPROFILE%/.ssh"
              ]
          },
          "network": {
              "default": "Allow",
              "deny": [
                  "10.0.0.0/8",
                  "192.168.0.0/16"
              ]
          },
          "resources": {
              "cpu": 50,
              "memory": 8
          }
      }

   3. Click Confirm to exit the current setting page and complete the enabling of the sandbox mode.

Execution Policy for High-Risk Commands

When the agent detects a high-risk command, the AI will send a prompt in the chat session. (In the TUI development environment, a dialog box is displayed to ask whether the command is intercepted. In the CLI development environment, the command is intercepted directly.) You need to evaluate risks and select an execution mode as required.

• Allow once: Only the current execution is allowed. The same command will prompt for approval again the next time.
• Allow always: For the current session, commands of this type will run without further prompts for approval.
• Reject: The command is not executed and the session continues. This is suitable for actions that you consider risky or unnecessary.

To disable sandbox, see Disabling Sandbox.

Disabling Sandbox

The following describes how to disable sandbox in the TUI development environment. In the CLI development environment, run the codearts run "prompt" --auto command.

1. Enter the TUI development environment.
   1. Open the root directory of the target project.
   2. Right-click in the blank area and select Open Windows Terminal here.
   3. Enter /codearts in the terminal and press Enter to enter the TUI development environment.

2. Disable the sandbox mode.
   Disabling sandbox is to set the run mode to Auto or Manual.

   1. In the TUI dialog box, enter /run-mode and press Enter. The Select Run Mode configuration is displayed.
   2. Select Auto or Manual and press Enter to exit the sandbox run mode.
      • Auto: The agent directly executes all commands without your approval.

        For security purposes, you are advised to select Auto only when necessary. In this mode, the agent bypasses all security checks and may perform high-risk operations without prior notification.

      • Manual: Before executing any command, the agent sends a confirmation prompt to you. The command proceeds only after you manually confirm it.
        Figure 3 Switching the sandbox run mode