Sandbox & Code Execution

Overview

Thoughtful includes a powerful sandbox environment that allows the AI assistant to write and execute code on your behalf. This enables sophisticated automation workflows, data processing, API integrations, and custom scripts - all within a secure, isolated environment.

The sandbox is particularly useful when you need to:

• Run automation scripts you've created in your workspace
• Process data or transform information
• Connect to external APIs and services
• Execute multi-step workflows that require running code
• Test and debug scripts before deploying them elsewhere

How It Works

When you ask the AI to run code, it uses a secure cloud-based sandbox powered by E2B. Here's what happens behind the scenes:

• Sandbox Creation: A fresh, isolated environment is created with your workspace files
• Code Execution: The AI runs your command or script in this secure environment
• Results Returned: Output, errors, and any generated files are returned to the conversation
• Persistence: The sandbox stays active for about 5 minutes between commands, allowing multi-step workflows

Persistent Sandboxes

Within a conversation, the sandbox persists across multiple commands. This means you can:

• Install dependencies with bun install, then run tests with bun test
• Create a file, then read it back
• Build a project, then execute it

If the sandbox expires (after ~5 minutes of inactivity), a new one is automatically created with your workspace files the next time you run a command.

The Sandbox Environment

Each sandbox comes pre-configured with modern development tools:

File Page Execution

Your workspace "file" pages are automatically synced to the sandbox. When you create a page with:

• Page type: file
• Extension: ts, js, or json

The content becomes an executable file in the sandbox. For example, a file page named fetch-tickets with extension ts becomes /home/user/workspace/fetch-tickets.ts.

To run it:

The AI will execute:

Environment Variables (Secrets)

One of the most powerful features of the sandbox is secure access to your secrets. API keys, database credentials, and other sensitive values can be stored encrypted and automatically injected when code runs.

Setting Up Secrets

• Open Settings (gear icon)
• Navigate to Secrets
• Choose the scope:

- Workspace secrets: Shared with your team

- My secrets: Personal, visible only to you

• Click Add secret and provide:

- Name: The environment variable name (e.g., HELPSCOUT_API_KEY)

- Value: The secret value (stored encrypted)

- Description: Optional notes for your team

How Secrets Work

When the AI runs code in the sandbox:

• Your secrets are decrypted server-side
• They're injected as environment variables
• Your code accesses them normally (e.g., Deno.env.get("HELPSCOUT_API_KEY"))
• Values are never exposed in logs or responses

Priority: If both workspace and personal secrets have the same name, your personal secret takes precedence.

Example: Accessing a Secret in Code

Connecting to External APIs

The sandbox can connect to any external service. Here are common integration patterns:

Help Scout (Support Tickets)

Stripe (Payments)

Database Connections

For PostgreSQL and other databases, use the appropriate client library:

Generic REST APIs

Security Considerations

The sandbox is designed with security as a priority:

Isolation

• Each sandbox runs in a completely isolated environment
• Sandboxes cannot access your local machine or other users' data
• Network access is outbound only (the sandbox can call APIs, but nothing can call into it)

Secrets Protection

• Secrets are encrypted at rest using AES-256-GCM
• Decryption happens server-side, just before code execution
• Secret values are never logged or included in AI responses
• Personal secrets are never visible to teammates

Deno's Permission Model

When running Deno scripts, specific permissions must be granted:

The AI automatically includes appropriate permissions based on your script's needs.

What the Sandbox Cannot Do

• Access your local files outside the workspace
• Make inbound network connections
• Persist data beyond the sandbox lifetime (~5 minutes)
• Access other users' secrets or workspaces

Example Use Cases

Customer Support Dashboard

Create a script that pulls data from Help Scout and summarizes support metrics:

Ask the AI: "Run the support-metrics script and tell me how we're doing"

Automated Data Processing

Process a CSV file and generate insights:

Web Scraping with Browser Automation

Use agent-browser for pages that require JavaScript rendering:

Stealth Browser with Kernel.sh

If a site blocks normal browser automation, you can switch to Kernel.sh's stealth cloud browser provider.

Setup

• Create a Kernel account at kernel.sh
• Open Settings → Secrets in Thoughtful
• Add a secret named KERNEL_API_KEY with your Kernel API key

How It Works

• When KERNEL_API_KEY is present, the agent can run agent-browser -p kernel ... for stealth browsing
• Kernel runs in a cloud browser designed to reduce bot detection
• Browser profiles persist, so logins can carry over across conversations
• Without KERNEL_API_KEY, the agent continues using the default local browser flow

Notes and Limitations

• Kernel may not support all targets (for example, some high-friction social/e-commerce domains may be blocked)
• Sessions can expire after long idle periods (around 1 hour)
• Kernel is a third-party paid service; check Kernel pricing and usage limits directly on their site

Tips for Writing Scripts

• Use Deno for new scripts - It has better security defaults and simpler imports
• Always handle missing secrets gracefully - Check if environment variables exist before using them
• Use npm packages via `npm:` prefix - Deno can import npm packages directly: import x from "npm:package-name"
• Keep scripts focused - One script per task makes them easier to maintain and debug
• Log useful output - The AI reads your console output to understand results

Getting Help

If you run into issues:

• Script errors: The AI will see the error message and can help debug
• Missing permissions: The AI will suggest the right Deno flags
• API issues: Check that your secrets are configured correctly in Settings
• Timeout errors: Long-running scripts may need the timeoutMs parameter increased

Need to do something the sandbox doesn't support? Ask the AI - there's often a creative workaround or alternative approach.