Documentation

DeepTask Sandbox Documentation

A secure, local-first sandbox that connects your AI assistant to your environment.
4 min read
Updated Jan 26, 2026

DeepTask Sandbox is a local-first desktop application that gives your AI assistant a safe, scriptable environment on your machine. Through natural conversation (via MCP), your assistant can run scripts, access approved local capabilities, and orchestrate workflows reliably — with optional browser-backed execution when a task truly needs a real page.

Core Principles

  • Privacy First: All automation runs locally. Your data never leaves your machine.
  • Assistant Ready: Built natively for the Model Context Protocol (MCP). Works seamlessly with Claude, Cursor, and more.
  • Scriptable Sandbox: Run lightweight Javascript logic, and opt into a browser-backed runtime (Puppeteer) only when needed.
  • Built-in Guardrails: Scheduling, task history, resource limits, domain allowlists, and encrypted settings/credentials.

01. Quick Start

Getting up and running takes less than five minutes.

Step 1: Install the Desktop App

Download and run the installer for your operating system.

Download DeepTask Sandbox

Step 2: Connect Your Assistant

DeepTask uses the Model Context Protocol (MCP) to communicate with your AI. Follow the instructions for your favorite environment:

OS Installation Type Command Path
Windows System (Default) C:\Program Files\deeptask-sandbox\resources\mcp\deeptask-mcp.exe
Windows User C:\Users\<user>\AppData\Local\Programs\deeptask-sandbox\resources\mcp\deeptask-mcp.exe
macOS Standard /Applications/DeepTask Sandbox.app/Contents/Resources/mcp/deeptask-mcp
Linux Standard /opt/deeptask-sandbox/resources/mcp/deeptask-mcp

Example Config Block (Claude Desktop):

{
  "mcpServers": {
    "deeptask": {
      "command": "PASTE_THE_COMMAND_PATH_HERE"
    }
  }
}

Step 3: Your First Script

Once connected, simply ask your assistant to create and run a small script inside the sandbox.

Try this prompt:

"Using DeepTask, write a small javascript script that fetches the title of https://example.com and returns it as structured output."

02. Scripting Guide

DeepTask scripts are powerful, type-safe, and easy to build. Your AI can generate these for you, or you can write them yourself.

Anatomy of a Script

Every script consists of two parts: Metadata (the configuration) and the Main Function (the logic).

export const metadata = {
    name: "web-scraper",
    type: "puppeteer", // "javascript" for pure logic, "puppeteer" when you need a real browser
    description: "Extracts basic info from a webpage (browser-backed, optional)",
    networkEnabled: true,
    domainsAllowed: ["example.com"],
    inputSchema: {
        type: "object",
        properties: {
            url: {type: "string", format: "uri"}
        },
        required: ["url"]
    }
};

export async function main({url}) {
    const page = await browser.getPage();
    await page.goto(url, {waitUntil: "networkidle0"});

    const title = await page.title();
    return {
        content: [{type: "text", text: `Scraped: ${title}`}],
        structuredContent: {title},
        isError: false
    };
}

Advanced Features

File Uploads

You can define inputs that accept files (PDFs, Images, etc.) which are passed to your script as Base64 strings.

inputSchema: {
    properties: {
        document: {
            type: "string",
                contentEncoding
        :
            "base64",
                contentMediaType
        :
            "application/pdf",
                description
        :
            "Upload a PDF for analysis"
        }
    }
}

Encrypted Settings

Store sensitive configuration securely. Users are prompted for these values in the UI, and they are encrypted at rest.

settingsSchema: {
    properties: {
        apiKey: {
            type: "string",
                format
        :
            "password",
                title
        :
            "OpenAI Key"
        }
    }
}
// Access via: const { apiKey } = browser.currentScript.settings;

03. Pro Features

Smart Scheduling

Automate your workflows with built-in Cron support.

  • Daily Reports: 0 9 * * * (Every morning at 9 AM)
  • Weekly Cleanup: 0 0 * * 0 (Every Sunday at midnight)

Security & Isolation

DeepTask is built for the enterprise:

  • Domain Whitelisting: Scripts cannot access the internet unless you explicitly allow specific domains.
  • Resource Limits: Configurable CPU (50-100%) and RAM (64MB-2GB) caps per script.
  • Timeout Protection: Prevent runaway processes with automatic script termination.

04. API & Tool Reference

Global APIs

API Description
browser.getPage() (Puppeteer only) Returns the active page object.
browser.scripts.run(name, params) Execute another installed script.
browser.downloads.download({url, filename}) Save files to the local machine.
browser.currentScript.settings Access the script's configured settings.

MCP Tools for Assistants

Your AI assistant can interact with DeepTask using these standard tools:

  • install_script / uninstall_script
  • list_scripts / get_script_info
  • run_script
  • update_script_settings

Support & Resources