DeepTask Sandbox는 안전하고 격리된 환경에서 자동화 도구를 실행하기 위한 크로스 플랫폼 데스크톱 애플리케이션입니다. Electron으로 빌드되고 Go 기반 MCP(Model Context Protocol) 서버와 통합되어, AI 어시스턴트가 머신에서 안전하고 도구를 사용할 수 있는 환경을 제공합니다. 자연스러운 대화를 통해(MCP 사용) 어시스턴트는 도구를 실행하고, 승인된 로컬 기능에 액세스하며, 작업에 실제 페이지가 필요할 때 선택적 브라우저 기반 실행(Puppeteer)으로 신뢰할 수 있게 워크플로를 조율할 수 있습니다.

참고: DeepTask Sandbox는 개인 및 교육적 용도로 무료입니다. 상업적 사용에는 사용자 수를 기반으로 한 월간 구독료가 적용되는 유료 라이선스가 필요합니다.

핵심 원칙

프라이버시 우선: 모든 자동화는 로컬에서 실행됩니다. 데이터는 절대 머신을 벗어나지 않습니다.
어시스턴트 준비 완료: Model Context Protocol (MCP)에 맞게 기본 제공됩니다. Claude, Cursor 등과 원활하게 작동합니다.
도구 사용 가능한 샌드박스: 백엔드 자동화를 위한 Node 도구와 브라우저 자동화 및 웹 스크래핑을 위한 Puppeteer 도구를 각각 격리된 워커 프로세스에서 실행합니다.
내장 가드레일: 스케줄링(cron), 작업 기록, 리소스 제한(메모리 64–2048 MB, CPU 임계값), 도메인 허용 목록, 암호화된 설정/자격 증명.

01. 빠른 시작

시작하는 데 5분 미만이 걸립니다.

1단계: 데스크톱 앱 설치

운영 체제용 설치 프로그램을 다운로드하여 실행하세요.

DeepTask Sandbox 다운로드

2단계: 어시스턴트 연결

DeepTask는 AI와 통신하기 위해 **Model Context Protocol (MCP)**를 사용합니다. 선호하는 환경에 맞는 지침을 따르세요:

OS	설치 유형	명령 경로
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`

예시 설정 블록 (Claude Desktop):

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

3단계: 첫 번째 도구

연결되면 어시스턴트에게 샌드박스 안에서 작은 도구를 만들고 실행하라고 요청하세요.

이 프롬프트를 시도해 보세요:

"DeepTask를 사용하여 https://example.com의 제목을 가져와 구조화된 출력으로 반환하는 작은 node 도구를 작성해 주세요."

02. 도구 가이드

DeepTask 도구는 강력하고 타입 안전하며 쉽게 빌드할 수 있습니다. AI가 대신 생성해 줄 수도 있고, 직접 작성할 수도 있습니다.

도구의 구조

모든 도구는 두 부분으로 구성됩니다: 메타데이터(구성)와 메인 함수(로직). 도구 이름은 snake_case를 사용해야 합니다(소문자, 숫자, 밑줄만; 예: web_scraper). 도구는 ESM(.mjs) 모듈이어야 하며; Node.js 24+가 지원됩니다.

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

고급 기능

파일 업로드

JSON Schema를 사용하여 파일(PDF, 이미지 등)을 허용하는 입력을 정의할 수 있습니다: contentEncoding: "base64", contentMediaType(예: application/pdf), 크기 제한을 위한 maxLength(base64는 약 33% 더 큼; 예: ~5MB → maxLength: 6990506).

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

도구에서 atob(input.document)로 디코딩하세요(또는 바이너리의 경우 new Uint8Array(atob(input.document).split('').map(c=>c.charCodeAt(0))))하고 필요에 따라 처리하세요. 크기 제한: maxLength = Math.ceil(bytes/3)*4(예: 1MB → 1398101, 5MB → 6990506).

암호화된 설정

민감한 구성을 안전하게 저장하세요. 사용자는 UI에서 이러한 값을 입력하라는 메시지를 받으며, 저장 시 암호화됩니다. 비밀번호 필드에 format: "password"를 사용하세요.

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

03. 보안 및 격리

모든 플랜에 이 안전 조치가 포함됩니다. DeepTask는 안정성과 보안을 위해 구축되었습니다:

도메인 허용 목록: networkEnabled: true를 설정하고 domainsAllowed를 지정하지 않으면 도구가 네트워크에 액세스할 수 없습니다(모든 호스트 허용: ["*"]). URL이 차단되면 fetch()가 요청 전에 throw합니다 — fetch()를 try/catch로 감싸세요.
리소스 제한: 구성 가능한 메모리(64–2048 MB; Node 기본 256 MB, Puppeteer 512 MB)와 CPU 임계값(50–100%, 기본 95%). 제한을 초과하는 도구는 자동으로 종료됩니다.
타임아웃 보호: defaultTimeout을 통해 도구별로 구성 가능(기본 5분).
파일시스템: 폴더 /Temp, /Documents, /Images, /Videos, /Audios, /Downloads가 있는 가상 파일시스템(루트 /)에 대한 선택적 읽기/쓰기 액세스. 호스트 파일시스템 액세스 없음; 경로는 루트를 벗어날 수 없음. fsEnabled 및 fsWriteEnabled 사용. fs/promises 사용 — readFileSync 같은 동기 메서드는 차단됨. 파일은 도구 호출 간에 유지됨; /Temp는 앱 시작 시 및 24시간마다 정리됨(최대 48시간).

04. Pro 기능

스마트 스케줄링

내장 Cron 지원으로 워크플로를 자동화하세요.

일일 리포트: 0 9 * * *(매일 오전 9시)
주간 정리: 0 0 * * 0(매주 일요일 자정)

05. API 및 도구 참조

Sandbox API

@deeptask/sandbox에서 가져오기:

API	설명
`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`	내장 API(아래 섹션 참조). 모두 `{ files, data, isError, message }`를 반환합니다.
`language`, `timeZone`	샌드박스 로케일 및 타임존.
`fs` / `fs/promises`	(`fsEnabled`일 때) `/Temp`, `/Documents`, `/Images` 등이 있는 `/` 아래 가상 FS. `fs/promises` 사용 — 동기 메서드는 차단됨.

Puppeteer: page.goto()는 http/https만 허용합니다. try/catch로 감싸세요. 응답 바이트에는 response.buffer() 사용(body() 아님).

document

import { document } from "@deeptask/sandbox"

문서 변환, PDF 조작 및 전문 검색. 모든 메서드는 { files, data, isError, message }를 반환합니다. files 또는 data 사용 전에 항상 isError를 확인하세요.

Method	설명
`convertDocument`	형식 간 변환. 쌍: md↔html, pdf↔html, docx/pptx/epub↔html, html→docx/pdf/pptx/epub, csv↔xlsx. 쌍에 따라 옵션 다름(예: html→pdf: `format`, `printBackground`; pdf→html: `startPage`, `endPage`).
`mergePdf`	여러 PDF를 하나로 병합.
`splitPdf`	PDF를 페이지로 분할. 페이지당 한 파일: `pages` 생략. 출력은 `/Temp/`로 감.
`compressPdf`	PDF 압축. 옵션: `quality` (screen, ebook, printer, prepress).
`fillPdfForm`	PDF 양식 필드 채우기. 키는 원시 PDF 필드 이름(대소문자 구분).
`getPdfInfo`	페이지 수, 제목, 작성자 등 가져오기.
`getPdfForm`	PDF의 양식 필드 목록.
`extractArticle`	주요 기사 텍스트 추출(Readability). md, pdf, docx, pptx, epub, html 지원. `data.text` 반환; 빈 문자열 확인.
`extractPages`	PDF에서 페이지 범위 추출(1부터 시작, 포함).
`searchFiles`	인덱싱된 파일 전체 전문 검색. `/Documents`만 인덱싱됨. `data.hits`, `data.total` 반환. `limit` 사용(기본 20).
`searchInFile`	단일 파일 내 검색. 텍스트 및 오피스 유형 지원. `offset`/`limit`로 결과 페이지네이션.

참고: protectPdf는 구현되지 않음 — 사용하지 마세요.

image

import { image } from "@deeptask/sandbox"

Sharp/libvips를 사용한 이미지 처리. 모든 메서드는 { files, data, isError, message }를 반환합니다.

Method	설명
`resizeImage`	크기 조정. 옵션: `fit` (cover, contain, fill, inside, outside), `withoutEnlargement`.
`compressImage`	크기 줄이기 위해 재인코딩; 메타데이터 유지.
`minifyImage`	메타데이터만 제거.
`cropImage`	`left`, `top`, `width`, `height`로 자르기.
`rotateImage`	각도로 회전.
`flipImage` / `flopImage`	가로 또는 세로 미러.
`convertImage`	형식 변환. png, jpeg, gif, tiff, webp, ico, icns 지원; 소스로 SVG.
`removeBackground`	단순 색상 매칭(AI 아님). PNG 출력. `threshold` 0–255(기본 10).
`compositeImage`	`left`, `top`에 이미지 오버레이, 선택적 `opacity`.
`mergeImages`	이미지 결합. 옵션: `layout` (horizontal, vertical, grid), `gap`, `columns`, `maxWidth`, `maxHeight`.
`getImageInfo`	`data: { width, height, format, channels, hasAlpha, space }` 반환.
`blurImage`, `sharpenImage`	블러 또는 선명화; `sigma`가 강도 제어.
`grayscaleImage`, `trimImage`, `normalizeImage`, `extendImage`, `modulateImage`, `negateImage`, `tintImage`	색상 및 레이아웃 작업.

audio

import { audio } from "@deeptask/sandbox"

오디오 변환 및 처리. 모든 메서드는 { files, data, isError, message }를 반환합니다.

Method	설명
`convertAudio`	형식 변환. mp3, wav, aac, ogg, flac, m4a, wma, opus 지원.
`trimAudio`	`start`, `end` 또는 `duration`(초)로 자르기.
`concatAudio`	오디오 파일 연결.
`setAudioVolume`	볼륨 설정(숫자).
`setAudioTempo`	템포 0.5–2.0(FFmpeg 제한).
`fadeAudio`	페이드 인/아웃. 옵션: `type`, `start`, `duration`.
`normalizeAudio`	음량 정규화. `target` LUFS(기본 -16).
`removeAudioSilence`	묵음 제거. `threshold` dB(기본 -50), `duration` 초(기본 0.5).
`mixAudio`	여러 오디오 파일 믹스. 선택적 `volumes`.
`getAudioInfo`	`data: { duration, sampleRate, channels, bitrate, format, codec }` 반환.
`textToSpeech`	텍스트-음성 변환. macOS/Windows만. `format`: mp3, wav, ogg.

참고: voiceToText는 구현되지 않음 — 사용하지 마세요.

video

import { video } from "@deeptask/sandbox"

비디오 변환, 자르기 및 효과. 모든 메서드는 { files, data, isError, message }를 반환합니다.

Method	설명
`convertVideo`	형식 변환. mp4, webm, avi, mov, mkv, m4v, flv, wmv 지원.
`compressVideo`	압축. 옵션: `crf` (18–28, 기본 23), `maxWidth`, `maxHeight`, `videoBitrate`, `audioBitrate`.
`trimVideo`	`start`, `end` 또는 `duration`로 자르기.
`concatVideos`	비디오 파일 연결.
`extractAudioTrack`	오디오를 mp3, wav, aac, m4a, ogg, flac로 추출.
`extractFrame`	`timestamp`에서 단일 프레임 추출.
`screenshotVideo`	여러 `timestamps`에서 프레임 추출. 순서대로 각 타임스탬프당 이미지 하나 반환.
`videoToGif`	비디오를 GIF로 변환. 옵션: `start`, `duration`, `fps`, `width`, `height`.
`generateGif`	이미지 시퀀스에서 GIF 생성. 옵션: `fps`, `width`, `height`, `loop`.
`burnSubtitles`	비디오에 자막 파일 번인.
`extractSubtitles`	자막을 srt 또는 vtt로 추출.
`cropVideo`, `rotateVideo`	자르기 또는 회전(90, 180, 270).
`setVideoSpeed`, `setVideoVolume`, `fadeVideo`	속도, 볼륨, 페이드 효과.
`getVideoInfo`	`data: { duration, width, height, fps, videoBitrate, audioBitrate, format, ... }` 반환.

model

import { model } from "@deeptask/sandbox"

LLM 텍스트 생성, 이미지 생성 및 비디오 생성. networkEnabled 및 API 키 필요. format: "password"로 settingsSchema에 apiKey 저장; tool.self.settings.apiKey로 액세스. 키 하드코딩 금지.

Method	설명
`generateText`	채팅 완성. `messages`, 선택적 `system`, `options: { provider, apiKey, baseURL }`. 프로바이더: openai, anthropic, google, cohere, mistral, openrouter, grok, deepseek, groq. 기본: openai (gpt-4o-mini).
`generateImage`	이미지 생성. `prompt`, 선택적 `image`(이미지-이미지). 프로바이더: openai, stability, replicate, fal, together, nano-banana, ideogram. fal, nano-banana에서만 이미지-이미지.
`generateVideo`	비디오 생성. `prompt`, 선택적 `image`. 프로바이더: runway, replicate, luma, kling, minimax, seedance, veo3. 해상도는 프로바이더별(예: `ratio`, `resolution`).

archive

import { archive } from "@deeptask/sandbox"

파일 압축 및 압축 해제. 모든 메서드는 { files, data, isError, message }를 반환합니다.

Method	설명
`zipFiles`	파일을 하나의 아카이브로 압축. 출력: `/Temp/`에 `archive-{timestamp}.zip`. zip 루트의 파일(디렉터리 구조 유지 안 됨).
`unzipFile`	압축 해제. `filter`: 포함할 파일명 부분 문자열. `files[]`는 추출된 파일의 가상 경로 포함; 디렉터리 구조 유지.

어시스턴트용 MCP 도구

AI 어시스턴트가 다음 MCP 도구를 통해 DeepTask와 상호작용합니다:

install_tool — 재사용을 위해 도구 설치. 이후 call_tool로 실행.
uninstall_tool — 설치된 도구 제거.
call_tool — 설치된 도구 실행. 도구 defaultTimeout에 따라 동기/비동기(>60s = 비동기).
get_call_tool_result — 비동기 call_tool의 결과 폴링(taskId로).
eval_tool_script — 설치 없이 한 번만 도구 실행(1회용). 매개변수: type, content, 선택적 sandboxId.
batch_call_tools — 한 요청에서 여러 도구 호출.
list_more_tools — 설치된 도구 목록. 도구 구문에 get_tool_script_syntax 사용(섹션: document, image, audio, video, model, archive).

지원 및 리소스

웹사이트: deeptask.ai
이메일: support@deeptask.ai
이슈: 앱의 피드백 메뉴를 통해 버그 신고 또는 기능 요청.