DeepTask Sandbox Documentation

DeepTask Sandbox is a cross-platform desktop application for executing automation tools in secure, isolated environments. Built with Electron and integrated with a Go-based MCP (Model Context Protocol) server, it gives your AI assistant a safe, toolable environment on your machine. Through natural conversation (via MCP), your assistant can run tools, access approved local capabilities, and orchestrate workflows reliably — with optional browser-backed execution (Puppeteer) when a task needs a real page.

Note: DeepTask Sandbox is free for personal and educational use. Commercial use requires a paid license with monthly subscription pricing based on the number of users.

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.
• Toolable Sandbox: Run Node tools for backend automation, and Puppeteer tools for browser automation and web scraping — each in isolated worker processes.
• Built-in Guardrails: Scheduling (cron), task history, resource limits (memory 64–2048 MB, CPU thresholds), 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:

Example Config Block (Claude Desktop):

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

Step 3: Your First Tool

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

Try this prompt:

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

02. Tool Guide

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

Anatomy of a Tool

Every tool consists of two parts: Metadata (the configuration) and the Main Function (the logic). Tool names must use snake_case (lowercase letters, numbers, underscores only; e.g. web_scraper). Tools must be ESM (.mjs) modules; Node.js 24+ is supported.

import { browser } from "@deeptask/sandbox";

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

export async function main({url}) {
    const page = 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.) using JSON Schema: contentEncoding: "base64", contentMediaType (e.g. application/pdf), and maxLength for size limits (base64 is ~33% larger; e.g. ~5MB → maxLength: 6990506).

inputSchema: {
    properties: {
        document: {
            type: "string",
            contentEncoding: "base64",
            contentMediaType: "application/pdf",
            maxLength: 6990506,  // ~5MB file
            description: "Upload a PDF for analysis"
        }
    }
}

In your tool, decode with atob(input.document) (or new Uint8Array(atob(input.document).split('').map(c=>c.charCodeAt(0))) for binary) and process as needed. For size limits: maxLength = Math.ceil(bytes/3)*4 (e.g. 1MB → 1398101, 5MB → 6990506).

Encrypted Settings

Store sensitive configuration securely. Users are prompted for these values in the UI, and they are encrypted at rest. Use format: "password" for password fields.

settingsSchema: {
    properties: {
        apiKey: {
            type: "string",
            format: "password",
            title: "API Key"
        }
    }
}

03. Security & Isolation

All plans include these safeguards. DeepTask is built for reliability and safety:

• Domain allowlists: Tools cannot access the network unless you set networkEnabled: true and specify domainsAllowed (use ["*"] to allow all hosts). When a URL is blocked, fetch() throws before any request — wrap fetch() in try/catch.
• Resource Limits: Configurable memory (64–2048 MB; default 256 MB for Node, 512 MB for Puppeteer) and CPU threshold (50–100%, default 95%). Tools exceeding limits are automatically terminated.
• Timeout Protection: Configurable per tool via defaultTimeout (default 5 minutes).
• Filesystem: Optional read/write access to a virtual filesystem (root /) with folders /Temp, /Documents, /Images, /Videos, /Audios, /Downloads. No host filesystem access; paths cannot escape the root. Use fsEnabled and fsWriteEnabled. Use fs/promises (sync methods like readFileSync are blocked). Files persist across tool invocations; /Temp is cleaned on app startup and every 24h (48h max age).

04. 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)

05. API & Tool Reference

Sandbox API

Import from @deeptask/sandbox:

Puppeteer: page.goto() accepts http/https only. Wrap in try/catch. Use response.buffer() (not body()) for response bytes.

document

import { document } from "@deeptask/sandbox"

Document conversion, PDF manipulation, and full-text search. All methods return { files, data, isError, message }. Always check isError before using files or data.

Note: protectPdf is not implemented — do not use.

image

import { image } from "@deeptask/sandbox"

Image processing with Sharp/libvips. All methods return { files, data, isError, message }.

audio

import { audio } from "@deeptask/sandbox"

Audio conversion and processing. All methods return { files, data, isError, message }.

Note: voiceToText is not implemented — do not use.

video

import { video } from "@deeptask/sandbox"

Video conversion, trimming, and effects. All methods return { files, data, isError, message }.

model

import { model } from "@deeptask/sandbox"

LLM text generation, image generation, and video generation. Requires networkEnabled and API keys. Store apiKey in settingsSchema with format: "password"; access via tool.self.settings.apiKey. Never hardcode keys.

archive

import { archive } from "@deeptask/sandbox"

Zip and unzip files. All methods return { files, data, isError, message }.

MCP Tools for Assistants

Your AI assistant interacts with DeepTask via these MCP tools:

• install_tool — Install a tool for reuse. Run with call_tool after.
• uninstall_tool — Remove an installed tool.
• call_tool — Run an installed tool. Sync/async based on tool defaultTimeout (>60s = async).
• get_call_tool_result — Poll result for async call_tool (by taskId).
• eval_tool_script — Run tool once without installing (one-off). Params: type, content, optional sandboxId.
• batch_call_tools — Call multiple tools in one request.
• list_more_tools — List installed tools. Use get_tool_script_syntax for tool syntax (sections: document, image, audio, video, model, archive).

Support & Resources

• Website: deeptask.ai
• Email: [email protected]
• Issues: Report bugs or request features via the app's feedback menu.