Sandboxing

Sandboxing (v6.1.0)

Sandboxing (v6.1.0) in Tabnine CLI is an OS-level process isolation mechanism that enforces hard filesystem and network boundaries around the CLI process itself. When sandbox mode is active, the CLI runs inside a process jail enforced by the operating system kernel — using macOS Seatbelt (sandbox-exec) on macOS, or a container runtime (Docker, Podman, or others) on Linux and Windows. The OS prevents the process from reading or writing outside permitted paths, regardless of what the AI agent attempts.

This is distinct from the tool-approval layer (controlled by --approval-mode), which governs which agent actions require your confirmation. See Tool Approval vs. Sandbox Mode for a full comparison.

---

How Sandbox Mode Works

When you enable sandbox mode, Tabnine CLI re-launches itself as a child process inside a sandbox environment. The sandbox backend is selected automatically based on your platform:

1. macOS — Uses sandbox-exec (Apple Seatbelt), a kernel-enforced SBPL profile. No external tools required.

2. Linux — Prefers Docker, then Podman, then lxc, then runsc (gVisor).

3. Windows — Uses a native Windows sandboxing mechanism (windows-native).

You can also specify a backend explicitly instead of relying on auto-detection (see Configuration).

Filesystem Isolation

The sandbox restricts which paths the process can read from and write to. Write access is always limited to a defined allowlist regardless of strictness level. Read access varies by the macOS profile selected (see macOS Sandbox Profiles). On container-based backends, the working directory and .tabnine config paths are mounted into the container.

Network Isolation

Network access is controlled independently of filesystem isolation. Two modes are available:

• Open — All outbound network connections are permitted.

• Proxied — Only connections through a local proxy (listening on localhost:8877) are permitted. Set via TABNINE_SANDBOX_PROXY_COMMAND.

---

When to Use Sandbox Mode

Use sandbox mode when you need an enforceable guarantee that the CLI process cannot access or modify files outside your working directory, or cannot make unrestricted network connections. Unlike approval mode, sandbox restrictions are enforced by the OS — the AI agent cannot bypass them even if it tries.

Sandbox mode is a strong fit for:

• Analyzing code from an untrusted or unfamiliar repository

• Running Tabnine CLI in a CI/CD pipeline with restricted system access

• Auditing a project for security issues in a controlled environment

• Ensuring the CLI cannot touch files outside the current project directory

• Working in environments where a security team requires verifiable process isolation

If your goal is to review and approve each agent action interactively (rather than enforce hard OS-level boundaries), --approval-mode default is usually a better fit. Sandbox mode is stricter and non-interactive by design.

---

Quickstart

Enable sandboxing with a command flag

tabnine -s -p "analyze the code structure"

Use an environment variable

macOS/Linux

export TABNINE_SANDBOX=true
tabnine -p "review the architecture"

Windows (PowerShell)

$env:TABNINE_SANDBOX="true"
tabnine -p "review the architecture"

Configure in settings.json

{
  "tools": {
    "sandbox": true
  }
}

---

macOS Sandbox Profiles

On macOS, the sandbox is implemented using Apple Seatbelt (sandbox-exec) with one of six built-in SBPL profiles. The profile controls how strictly filesystem access is constrained and whether network access is open or proxied.

Select a profile by setting the SEATBELT_PROFILE environment variable before invoking tabnine. If unset, the default is permissive-open.

Profile	Read Access	Write Access	Network
permissive-open (default)	Everywhere (allow default)	Allowlist only¹	All outbound
permissive-proxied	Everywhere (allow default)	Allowlist only¹	Proxied only (localhost:8877)
restrictive-open	Explicit allowlist (target dir, system paths, ~/.tabnine, ~/.nvm, ~/.config, …)	Allowlist only¹	All outbound
restrictive-proxied	Same as restrictive	Allowlist only¹	Proxied only (localhost:8877)
strict-open	Narrow allowlist (target dir + essential dotfiles + explicit system paths only)	Allowlist only¹	All outbound
strict-proxied	Same as strict	Allowlist only¹	Proxied only (localhost:8877)

¹ Write allowlist: working directory, system temp dir, ~/.tabnine, ~/.cache, ~/.npm, ~/.gitconfig, and any paths passed via --include-directories (up to 5).

# Use the most restrictive profile with proxied network
SEATBELT_PROFILE=strict-proxied tabnine -s -p "audit this codebase"

---

Tool Approval vs. Sandbox Mode

These are two separate, independently configurable features that address different concerns.

	--sandbox / -s	--approval-mode
What it controls	OS-level process isolation	Which AI agent actions require user confirmation
Enforcement	Kernel / container runtime	CLI application logic
Can the AI bypass it?	No	No (but scope is different)
Affects file writes?	Yes — OS blocks them outside allowlist	Yes — prompts or auto-approves based on mode
Affects shell commands?	Yes — restricted by the OS sandbox profile	Yes — controlled by approval policy
Network restrictions?	Yes — open or proxied, per profile	No
Requires external tool?	On macOS: no. On Linux/Windows: Docker or Podman	No

You can use both together. For example, running with -s --approval-mode default gives you OS-level isolation and interactive confirmation of every agent action.

Approval Mode Reference

Mode	Behavior
default	Prompts for confirmation before every file edit and shell command
auto_edit	Auto-approves file edits; prompts for shell commands
yolo	Auto-approves everything (use with caution)
plan (v6.1.0)	Agent plans actions and presents them; no automatic execution

# OS isolation + interactive confirmation of every action
tabnine -s --approval-mode default -p "your prompt"

---

Configuration

Enable Sandboxing (in order of precedence)

1. Command-line flag — Pass -s or --sandbox.

tabnine -s -p "your prompt here"

1. Environment variable — Set TABNINE_SANDBOX.

macOS/Linux

export TABNINE_SANDBOX=true
tabnine -p "your prompt here"

Windows (PowerShell)

$env:TABNINE_SANDBOX="true"
tabnine -p "your prompt here"

You can also set TABNINE_SANDBOX to a specific backend name instead of true, which skips auto-detection:

Value	Effect
true or 1	Auto-detect backend (macOS: sandbox-exec; Linux: docker → podman)
sandbox-exec	Force macOS Seatbelt (macOS only)
docker	Force Docker container backend
podman	Force Podman container backend
lxc	Force LXC container backend (Linux only)
runsc	Force gVisor via Docker (Linux only; requires Docker)
windows-native	Force Windows native sandbox (Windows only)

1. Configuration file — In settings.json, set "sandbox" under "tools".

Settings file location:

• macOS/Linux: ~/.tabnine/agent/settings.json

• Windows: %USERPROFILE%\.tabnine\agent\settings.json

Boolean form (auto-detect backend):

{
  "tools": {
    "sandbox": true
  }
}

String form (specify backend explicitly):

{
  "tools": {
    "sandbox": "docker"
  }
}

Object form (full control):

{
  "tools": {
    "sandbox": {
      "enabled": true,
      "command": "docker",
      "networkAccess": false,
      "allowedPaths": ["/path/to/extra/dir"],
      "image": "your-org/custom-sandbox-image:latest"
    }
  }
}

Field	Type	Default	Description
enabled	boolean	—	Whether sandboxing is active
command	string	auto-detect	Backend to use (docker, podman, sandbox-exec, etc.)
networkAccess	boolean	true	Set to false to block all outbound network
allowedPaths	string[]	[]	Additional filesystem paths to mount/allow
image	string	Tabnine default	Custom container image (Docker/Podman only)

You can also set sandboxNetworkAccess as a top-level tools setting:

{
  "tools": {
    "sandbox": true,
    "sandboxNetworkAccess": false
  }
}

Additional Environment Variables

Variable	Description
SEATBELT_PROFILE	macOS only. Selects the Seatbelt profile: permissive-open (default), permissive-proxied, restrictive-open, restrictive-proxied, strict-open, strict-proxied
TABNINE_SANDBOX_IMAGE	Override the container image used for Docker/Podman backends
TABNINE_SANDBOX_PROXY_COMMAND	Command to launch a proxy for proxied network profiles (must listen on localhost:8877)

---

Verification

To confirm sandbox mode is active, run with debug output:

DEBUG=1 tabnine -s -p "your prompt"

Look for a log line such as:

hopping into sandbox (command: sandbox-exec) ...

or, for container backends:

hopping into sandbox (command: docker) ...

If this line does not appear, sandbox mode is not active.

---

Troubleshooting

Common Issues

FatalSandboxError: TABNINE_SANDBOX is true but failed to determine command for sandbox

• No compatible sandbox backend was found on your system.

• On Linux: install Docker or Podman, or set TABNINE_SANDBOX to a specific backend name.

• On macOS: sandbox-exec is built in and should always be available. If this error appears on macOS, try setting TABNINE_SANDBOX=sandbox-exec explicitly.

FatalSandboxError: Invalid sandbox command '...'

• The value of TABNINE_SANDBOX is not a recognized backend name.

• Valid values: docker, podman, sandbox-exec, lxc, runsc, windows-native.

FatalSandboxError: Missing sandbox command '...'

• The specified backend binary is not installed or not on PATH.

• Install the required tool (e.g., brew install docker) or choose a different backend.

FatalSandboxError: gVisor (runsc) sandboxing is only supported on Linux

• runsc is Linux-only. Use docker or podman on macOS/Windows instead.

FatalSandboxError: Missing macos seatbelt profile file '...'

• The value of SEATBELT_PROFILE does not match any of the six built-in profiles.

• Valid values: permissive-open, permissive-proxied, restrictive-open, restrictive-proxied, strict-open, strict-proxied.

Agent cannot write files or run commands (expected)

• This is correct behavior. The OS sandbox restricts writes to the defined allowlist.

• If writes to a specific directory are required, pass it via --include-directories or add it to allowedPaths in settings.json.

Sandbox image '...' is missing or could not be pulled

• Docker/Podman cannot pull the sandbox container image.

• Check your network connection, or set TABNINE_SANDBOX_IMAGE to an image already present locally.

---

Alternatives to Sandbox Mode

If you need safety without OS-level process isolation, the approval mode system provides interactive guardrails without requiring Docker or a container runtime.

Approval Modes

Default mode — prompt before every file edit and shell command:

tabnine --approval-mode default

Auto-edit mode — auto-approve file edits, prompt for shell commands:

tabnine --approval-mode auto_edit

Plan mode — agent plans and presents actions; no automatic execution:

tabnine --approval-mode plan

Persist a Default Approval Mode

{
  "general": {
    "defaultApprovalMode": "default"
  }
}

Disable Session Retention for Sensitive Work

{
  "general": {
    "sessionRetention": {
      "enabled": false
    }
  }
}

---

Security Best Practices

1. Use sandbox mode for untrusted code review — Always enable sandbox when analyzing code from unknown sources. OS-level isolation provides a verifiable boundary that approval mode alone does not.

2. Prefer stricter macOS profiles for sensitive environments — Use SEATBELT_PROFILE=strict-proxied when you want both narrow filesystem read access and restricted network egress.

3. Combine sandbox with --approval-mode default — For modifiable sessions, pairing OS isolation with interactive confirmation gives you two independent layers of control.

4. Limit workspace scope with --include-directories — Restrict the AI's context to specific folders. These paths are also the only additional write targets allowed by the macOS sandbox profiles.

5. Use networkAccess: false or a proxied profile for air-gapped review — Set "networkAccess": false in settings.json or use a *-proxied Seatbelt profile to prevent the sandboxed process from making outbound connections.

6. Never combine --yolo with --sandbox on untrusted code — YOLO mode auto-approves all agent actions. Even inside a sandbox, this removes the interactive safeguard layer. Use --approval-mode default instead.

7. Review settings.json regularly — Check ~/.tabnine/agent/settings.json for persistent sandbox settings that may carry over between sessions.

---

Frequently Asked Questions

Q: Can the AI access the internet in sandbox mode?

A: It depends on the configuration. Container-based backends (Docker, Podman) allow network access by default unless "networkAccess": false is set. On macOS, the *-open Seatbelt profiles allow all outbound connections, while *-proxied profiles restrict network to a local proxy on localhost:8877. To enforce no network access, set "networkAccess": false in settings.json or use SEATBELT_PROFILE=strict-proxied with TABNINE_SANDBOX_PROXY_COMMAND unset.

Q: Does sandbox mode make the AI read-only?

A: Not exactly. Sandbox mode enforces OS-level filesystem boundaries — the process cannot write outside the defined allowlist. However, the AI agent's tools (such as write_file and replace) remain available; the OS sandbox will cause those operations to fail if they target a path outside the allowlist. If you want to prevent the agent from attempting file edits in the first place, combine sandbox mode with --approval-mode default or --approval-mode plan.

Q: Will sandbox mode slow down the AI?

A: Negligibly on macOS (Seatbelt adds no measurable overhead). Container-based backends (Docker/Podman) have a startup cost of a few seconds on first use, but subsequent operations run at normal speed.

Q: Does sandbox mode protect against prompt injection attacks?

A: It reduces the impact. Prompt injection attacks that attempt to exfiltrate files or modify the filesystem outside the working directory will be blocked by the OS. However, actions within the allowed write paths are still possible. Always review AI responses critically, especially when working with untrusted input.

Q: Can I enable sandbox mode by default for all sessions?

A: Yes. Set "sandbox": true in ~/.tabnine/agent/settings.json under the "tools" section.

Q: Can I customize which paths are writable inside the sandbox?

A: Yes, via two mechanisms: pass --include-directories /your/path on the CLI (up to 5 paths), or set "allowedPaths" in the object form of tools.sandbox in settings.json.

Q: Can I use my own container image?

A: Yes. Set TABNINE_SANDBOX_IMAGE to your image name, or set the "image" field in the object form of tools.sandbox in settings.json. The image name must consist of alphanumeric characters, dots, colons, hyphens, underscores, and forward slashes only.