Sandbox

Constraints

File Access Control

After sandbox is enabled, the file and directory access permissions for CodeArts Agent are configured as follows. You can also configure the sandbox.json file to customize the file and network access scope of processes in the sandbox environment of the current project. For details, see 5.

Enabling the Sandbox Mode

1. Log in to CodeArts Agent IDE as instructed in Quick Start.
2. Click in the upper right corner of CodeArts Agent IDE to open the settings page.
3. Enable the sandbox mode.
   1. In the navigation pane on the left, choose Chats.
   2. Under Agents, select Running in Sandbox from the Terminal Command Running Mode drop-down list.
      Figure 1 Selecting Running in Sandbox
      

4. Configure the command whitelist.

   This allows you to add the prefix of a specific command to the whitelist as required. Commands added to the whitelist bypass the sandbox mechanism and are executed outside the sandbox.

5. Customize sandbox configuration.

   By configuring the sandbox.json file, you can customize files and the network access scopes for processes within the current project's sandbox environment.

   1. Click Open Configuration next to Sandbox Custom Configuration. The IDE will generate a sandbox.json file in your local user directory (%USERPROFILE%/.codeartsdoer) and automatically open it in the editor.
      The initial structure of the file is as follows:

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

      Table 3 Parameters in the sandbox.json file

      Parameter	Mandatory (Yes/No)	Parameter 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 4 Parameters in filesystem

      Parameter	Parameter Type	Default Value	Format of Supported Paths	Priority Rule	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 prevail.	List of read/write paths.
      readOnly	Array	[ ]			List of read-only paths.

      Table 5 Parameters in network

      Parameter	Parameter Type	Default Value	Priority Rule	Description
      default	String	Allow	deny > allow > default If both allow and deny are configured, deny shall prevail.	Default network access 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 configured by separating them with commas. If no port is specified, the rule applies to all ports by default.
      allow	Array	[ ]		Network rules that allow access to processes in the sandbox.
      deny	Array	[ ]		Network rules that reject access to processes in the sandbox.

      Table 6 Parameters in resources

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

   2. In the opened sandbox.json file, enter your custom sandbox configuration.

      Example configuration of sandbox.json:

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

   3. Save the file for the configuration to take effect.

6. Configure the network access policy.

   Table 7 Network access policy description

   Parameter	Description
   Network-wide	Allows access to all internal and external networks.
   Local	Only the local network (LAN/intranet) can be accessed. Access to external networks is not allowed. This option is unavailable for the Linux sandbox.
   Blocked	All network connections are blocked, and access to any internal or external network is prohibited. In the Linux environment, the Linux sandbox generates an isolated virtual address (127.0.0.1), which is separated from the host machine's localhost. Even when network access is prohibited, this virtual address can still be accessed in the sandbox, and such access will not be blocked by the sandbox.
   Custom	Allows you to modify the JSON policy configuration file to customize the network access scope for processes within the project sandbox environment. For details about how to configure the JSON file, see 5.

7. Exit the current setting page. The sandbox mode is enabled.

Execution Policy for High-Risk Commands

When the agent detects a high-risk command, the AI will display a prompt in the chat flow. You need to evaluate risks and select an execution mode as required.

• Skip: The target command is not executed.
• Trust XXX: The prefix of the target command is added to the whitelist. Then all commands starting with this prefix will be executed outside the sandbox.
• Continue running: The target command can be executed outside the sandbox for the current chat.