← Back to Blog

Understanding the Terminal Sandbox for AI Agents

Security AI Agents Sandbox

In simple terms, the enableTerminalSandbox setting is like putting a "digital clear-box" around your AI agent.

When you ask an AI to run commands in your terminal, it normally has full access to your computer—just like you do. Turning this setting on (true) locks the AI inside a strict, isolated container. The AI can look at the code inside your project folder, but it cannot touch, read, or change anything else on your computer.

The Scenario It Prevents: Rogue Code Sabotage

Imagine you are using an AI agent to help you test an unfamiliar open-source project that you just downloaded from the internet.

❌ Without the Sandbox (Setting is false)

  1. You tell the AI: "Install the dependencies and run the test script."
  2. The AI reads the project's setup file and runs a command like npm install && npm test.
  3. Unbeknownst to you and the AI, a malicious hacker hid a trick command inside the test script.
  4. When the AI executes the script, the trick command runs with full access to your Mac. It quietly reaches outside your project folder, finds your private SSH keys (~/.ssh/id_rsa), and uploads them to a hacker's server. Your entire computer is now compromised.

✅ With the Sandbox Enabled (Setting is true)

  1. You give the AI the exact same instruction.
  2. The AI attempts to execute the npm test script.
  3. Because the sandbox is on, your Mac instantly activates a built-in security shield.
  4. The moment the trick command attempts to step outside the project folder to read your ~/.ssh/ directory, the system violently blocks the request.
  5. The command fails immediately with a "Permission Denied" error. The AI reports the error to you, and your private personal files remain completely safe.

Enabling the Sandbox via Config Files

You can enable the sandbox permanently by adding the security flags directly to your global settings file.

  1. Open your configuration file in a text editor. The path is usually ~/.agents/antigravity-cli/settings.json.
  2. Add or update the following lines inside the JSON object:
{
  "agent.terminal.enableTerminalSandbox": true,
  "agent.terminal.sandboxAllowNetwork": false
}

Enabling the Sandbox via Command Line

If you only want to use the sandbox for a single, specific session without changing your global settings, you can pass it directly as a flag when you start the agent: 

agy run --sandbox=true

Note: To turn it off for a quick task where you trust the code completely, you can explicitly run agy run --sandbox=false.

What is sandboxAllowNetwork?

The sandboxAllowNetwork setting is a security toggle that decides whether the isolated AI agent is allowed to connect to the internet. When you turn on the terminal sandbox, the system automatically cuts off the AI's internet access inside that sandbox by default to keep you completely safe.

Why keep it false? (Maximum Security)

It stops the AI or any malicious script from sending your data outside your computer. Even if a script reads a secret file, it cannot upload it to a hacker's server because the network door is completely locked.

When should you change it to true? (High Functionality)

You must set it to true (or use the flag --sandbox-network=true) if the AI needs to run commands that require an internet connection. Examples include:

References

  1. https://antigravity.google