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:

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 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:

API	Description
`browser`	(Puppeteer only) `browser.getPage()` → primary Page; `browser.getPages()` → all pages. Use `import { browser } from "@deeptask/sandbox";`
`tool`	`tool.self.settings` (encrypted at rest), `tool.call(name, params, sandboxId?)`, `tool.chain([{name, params, sandboxId?}, ...])`. Use `import { tool } from "@deeptask/sandbox";`
`document`, `image`, `audio`, `video`, `model`, `archive`	Built-in APIs (see sections below). All return `{ files, data, isError, message }`.
`language`, `timeZone`	Sandbox locale and timezone.
`fs` / `fs/promises`	(when `fsEnabled`) Virtual FS under `/` with `/Temp`, `/Documents`, `/Images`, etc. Use `fs/promises` — sync methods are blocked.

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.

Method	Description
`convertDocument`	Convert between formats. Pairs: md↔html, pdf↔html, docx/pptx/epub↔html, html→docx/pdf/pptx/epub, csv↔xlsx. Options vary by pair (e.g. html→pdf: `format`, `printBackground`; pdf→html: `startPage`, `endPage`).
`mergePdf`	Merge multiple PDFs into one.
`splitPdf`	Split PDF into pages. Omit `pages` for one file per page. Outputs go to `/Temp/`.
`compressPdf`	Compress PDF. Options: `quality` (screen, ebook, printer, prepress).
`fillPdfForm`	Fill PDF form fields. Keys are raw PDF field names (case-sensitive).
`getPdfInfo`	Get page count, title, author, etc.
`getPdfForm`	List form fields in a PDF.
`extractArticle`	Extract main article text (Readability). Supports md, pdf, docx, pptx, epub, html. Returns `data.text`; check for empty string.
`extractPages`	Extract page range from PDF (1-based inclusive).
`searchFiles`	Full-text search across indexed files. Only `/Documents` is indexed. Returns `data.hits`, `data.total`. Use `limit` (default 20).
`searchInFile`	Search inside a single file. Supports text and office types. `offset`/`limit` paginate hits.

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 }.

Method	Description
`resizeImage`	Resize. Options: `fit` (cover, contain, fill, inside, outside), `withoutEnlargement`.
`compressImage`	Re-encode to reduce size; preserves metadata.
`minifyImage`	Strip metadata only.
`cropImage`	Crop by `left`, `top`, `width`, `height`.
`rotateImage`	Rotate by angle.
`flipImage` / `flopImage`	Mirror horizontally or vertically.
`convertImage`	Convert format. Supports png, jpeg, gif, tiff, webp, ico, icns; SVG as source.
`removeBackground`	Simple color-match (not AI). Output PNG. `threshold` 0–255 (default 10).
`compositeImage`	Overlay images at `left`, `top`, optional `opacity`.
`mergeImages`	Combine images. Options: `layout` (horizontal, vertical, grid), `gap`, `columns`, `maxWidth`, `maxHeight`.
`getImageInfo`	Returns `data: { width, height, format, channels, hasAlpha, space }`.
`blurImage`, `sharpenImage`	Blur or sharpen; `sigma` controls strength.
`grayscaleImage`, `trimImage`, `normalizeImage`, `extendImage`, `modulateImage`, `negateImage`, `tintImage`	Color and layout operations.

audio

import { audio } from "@deeptask/sandbox"

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

Method	Description
`convertAudio`	Convert format. Supports mp3, wav, aac, ogg, flac, m4a, wma, opus.
`trimAudio`	Trim by `start`, `end` or `duration` (seconds).
`concatAudio`	Concatenate audio files.
`setAudioVolume`	Set volume (number).
`setAudioTempo`	Tempo 0.5–2.0 (FFmpeg limit).
`fadeAudio`	Fade in/out. Options: `type`, `start`, `duration`.
`normalizeAudio`	Loudness normalize. `target` LUFS (default -16).
`removeAudioSilence`	Remove silence. `threshold` dB (default -50), `duration` seconds (default 0.5).
`mixAudio`	Mix multiple audio files. Optional `volumes`.
`getAudioInfo`	Returns `data: { duration, sampleRate, channels, bitrate, format, codec }`.
`textToSpeech`	Text-to-speech. macOS/Windows only. `format`: mp3, wav, ogg.

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 }.

Method	Description
`convertVideo`	Convert format. Supports mp4, webm, avi, mov, mkv, m4v, flv, wmv.
`compressVideo`	Compress. Options: `crf` (18–28, default 23), `maxWidth`, `maxHeight`, `videoBitrate`, `audioBitrate`.
`trimVideo`	Trim by `start`, `end` or `duration`.
`concatVideos`	Concatenate video files.
`extractAudioTrack`	Extract audio to mp3, wav, aac, m4a, ogg, flac.
`extractFrame`	Extract a single frame at `timestamp`.
`screenshotVideo`	Extract frames at multiple `timestamps`. Returns one image per timestamp in order.
`videoToGif`	Convert video to GIF. Options: `start`, `duration`, `fps`, `width`, `height`.
`generateGif`	Create GIF from image sequence. Options: `fps`, `width`, `height`, `loop`.
`burnSubtitles`	Burn subtitle file into video.
`extractSubtitles`	Extract subtitles to srt or vtt.
`cropVideo`, `rotateVideo`	Crop or rotate (90, 180, 270).
`setVideoSpeed`, `setVideoVolume`, `fadeVideo`	Speed, volume, fade effects.
`getVideoInfo`	Returns `data: { duration, width, height, fps, videoBitrate, audioBitrate, format, ... }`.

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.

Method	Description
`generateText`	Chat completion. `messages`, optional `system`, `options: { provider, apiKey, baseURL }`. Providers: openai, anthropic, google, cohere, mistral, openrouter, grok, deepseek, groq. Default: openai (gpt-4o-mini).
`generateImage`	Image generation. `prompt`, optional `image` (image-to-image). Providers: openai, stability, replicate, fal, together, nano-banana, ideogram. Image-to-image only with fal, nano-banana.
`generateVideo`	Video generation. `prompt`, optional `image`. Providers: runway, replicate, luma, kling, minimax, seedance, veo3. Resolution is provider-specific (e.g. `ratio`, `resolution`).

archive

import { archive } from "@deeptask/sandbox"

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

Method	Description
`zipFiles`	Zip files into one archive. Output: `archive-{timestamp}.zip` in `/Temp/`. Files at zip root (no directory structure preserved).
`unzipFile`	Unzip. `filter`: filename substrings to include. `files[]` contains virtual paths for extracted files; directory structure preserved.

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: support@deeptask.ai
Issues: Report bugs or request features via the app's feedback menu.