Join us June 23 to see the ROI of switching to Tailscale.REGISTER ->

Troubleshoot sandbox issues

Last validated:

Aperture chat sandbox is currently in alpha.
The chat sandbox requires activation by Tailscale before you can use it. To request access, sign up using this form.

The chat sandbox gives the assistant access to tools for running commands, viewing files, creating files, and editing files in an isolated environment. Use the following sections to diagnose and resolve common sandbox issues.

Sandbox tools do not appear in conversations

The assistant does not offer to run code, create files, or use any sandbox tools.

This happens when one or more of the required conditions are not met. Check the following in order:

  1. The chat_sandbox feature flag is not enabled. The sandbox tools require the chat_sandbox flag. Enable it from the configuration editor in the Aperture dashboard. Because this is a hidden flag, press Shift+F in the dashboard to reveal it, or add it directly to the flags configuration.
  2. The user does not have chat access. Chat access is required for sandbox tools. The chat UI is available by default, so confirm that no grant sets enable_chat_ui to false for the user.
  3. The sandbox infrastructure is not available for your instance. Tailscale provisions and manages the infrastructure that runs the sandbox. If the flag and grant are both in place and tools still do not appear, contact Tailscale support.

When any of these conditions is not met, the sandbox tools are silently omitted from conversations. There is no explicit error message.

Tool calls fail with connection errors

The assistant tries to use a sandbox tool but the tool call fails with an error such as exec failed: followed by a connection-related message.

This indicates a temporary problem reaching the sandbox infrastructure, which Tailscale provisions and manages for your instance. Try the following:

  1. Retry the request. Transient connectivity issues often resolve on the next tool call.
  2. Start a new conversation to confirm the failure is not specific to one conversation.
  3. If the errors persist across conversations, contact Tailscale support with the approximate time and the error message.

If the sandbox infrastructure restarts, existing conversations automatically reconnect on the next tool call. No action is required on your side.

Storage limit exceeded

All sandbox tool calls in a conversation fail with the message:

This conversation's attached files exceed the sandbox capacity (5 GiB combined). Archive or remove some files and try again.

The conversation's combined uploaded and generated files exceed the 5 GiB limit. This limit is enforced per conversation. The error is permanent for that conversation until the total file size drops below the limit.

To resolve this, start a new conversation. To avoid hitting this limit in the future, use the sandbox working directory for intermediate files (note that this directory is not preserved when the sandbox is idle-terminated) and place only final deliverables in the output directory.

File downloads fail

Clicking a download link for a sandbox-generated file returns an error. The following table lists common HTTP status codes and their causes.

Status codeCauseResolution
401The user is not authenticated.Verify the request comes through the tailnet with valid Tailscale authentication.
403The user does not have chat access.Confirm no grant sets enable_chat_ui to false for the user. Chat access is on by default.
404The conversation does not exist, the user is not the conversation owner, or the file was not found.Verify the conversation ID and file path. Only the conversation owner can download files.
502The sandbox infrastructure is temporarily unreachable or returned an error.Retry the download. If it keeps failing, contact Tailscale support.
503The sandbox is not enabled on this instance.Confirm the chat_sandbox feature flag is enabled. If it is and downloads still fail, contact Tailscale support.

For security, a 404 response is returned both when a conversation does not exist and when the requesting user is not the owner. This prevents leaking information about other users' conversations.

Chat access gates the download endpoint before any file lookup. A user without chat access receives a 403 response. Chat access is available by default unless a grant sets enable_chat_ui to false.

Command output is truncated

The assistant's command output ends with a truncation notice such as ... output truncated (exceeded 1 MiB) ... or ... output truncated ....

This is expected behavior. Sandbox commands have per-tool output limits to keep tool results efficient for the assistant:

  • General commands (bash, file creation, string replacement): 1 MiB (1,048,576 bytes)
  • File viewing: 16,000 bytes

For large outputs, ask the assistant to redirect output to a file and then view specific sections of the file using line ranges. The assistant can also use commands like head, tail, or grep to filter output before it reaches the limit.

Verify sandbox health

Use the following steps to verify that the sandbox is working end-to-end:

  1. Start a new conversation in the chat interface.
  2. Ask the assistant to run a command, such as "What is the output of echo hello?"
  3. Verify the assistant uses a sandbox tool and returns the expected output. If this step fails, the sandbox infrastructure may be unreachable. Refer to tool calls fail with connection errors.
  4. Ask the assistant to create a file and share it with you.
  5. Verify a download link appears and the file downloads correctly. If this step fails, refer to file downloads fail.