{
"canonical_name": "e2b-dev/E2B",
"compilation_id": "pack_4d128e9ee73f496586bf3787334fb73a",
"created_at": "2026-05-18T03:20:19.264178+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=skill, recipe, host_instruction, eval, preflight",
"recommended_asset_types=skill, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `npm i e2b` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "npm i e2b",
"sandbox_container_image": "node:22-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_ab3ddeefa40e476485f6919752db89f8"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_dc63a90daf91aaaf36b16981cf9f68a3",
"canonical_name": "e2b-dev/E2B",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/e2b-dev/E2B",
"slug": "e2b",
"source_packet_id": "phit_c7049c31b89a4a90b1fabba255e18796",
"source_validation_id": "dval_f21c731f96224a40a2c234a37a3e5491"
},
"merchandising": {
"best_for": "需要软件开发与交付能力，并使用 local_cli的用户",
"github_forks": 907,
"github_stars": 12212,
"one_liner_en": "Open-source, secure environment with real-world tools for enterprise-grade agents.",
"one_liner_zh": "Open-source, secure environment with real-world tools for enterprise-grade agents.",
"primary_category": {
"category_id": "software-development",
"confidence": "medium",
"name_en": "Software Development",
"name_zh": "软件开发与交付",
"reason": "matched_keywords:git, cli"
},
"target_user": "使用 local_cli 等宿主 AI 的用户",
"title_en": "E2B",
"title_zh": "E2B 能力包",
"visible_tags": [
{
"label_en": "Browser Agents",
"label_zh": "浏览器 Agent",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-browser-agents",
"type": "product_domain"
},
{
"label_en": "Web Task Automation",
"label_zh": "网页任务自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-web-task-automation",
"type": "user_job"
},
{
"label_en": "Browser Automation",
"label_zh": "浏览器自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-browser-automation",
"type": "core_capability"
},
{
"label_en": "Checkpoint Resume",
"label_zh": "断点恢复流程",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-checkpoint-resume",
"type": "workflow_pattern"
},
{
"label_en": "Local-first",
"label_zh": "本地优先",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-local-first",
"type": "selection_signal"
}
]
},
"packet_id": "phit_c7049c31b89a4a90b1fabba255e18796",
"page_model": {
"artifacts": {
"artifact_slug": "e2b",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "npm i e2b",
"label": "Node.js / npm · 官方安装入口",
"source": "https://github.com/e2b-dev/E2B#readme",
"verified": true
}
],
"display_tags": [
"浏览器 Agent",
"网页任务自动化",
"浏览器自动化",
"断点恢复流程",
"本地优先"
],
"eyebrow": "软件开发与交付",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要软件开发与交付能力，并使用 local_cli的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "Open-source, secure environment with real-world tools for enterprise-grade agents."
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "local_cli",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "skill, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：process was not killed when auto paused",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_66994844a2ec44a784ad5b80307d82e9 | https://github.com/e2b-dev/E2B/issues/1031 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：process was not killed when auto paused",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Closed Port Error",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_33133a8885a44301a7f98b23844205cc | https://github.com/e2b-dev/E2B/issues/907 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Closed Port Error",
"user_impact": "可能阻塞安装或首次运行。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Please add skills to use with any ai agent to use e2b in our project",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_8cebd572dbd2485ab6cdbc13733fdee0 | https://github.com/e2b-dev/E2B/issues/1138 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Please add skills to use with any ai agent to use e2b in our project",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: Incorrect info about webhooks in docs and dashboard",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_8b25841679fd4eaea5d759a33dfad3b1 | https://github.com/e2b-dev/E2B/issues/1103 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：[Bug]: Incorrect info about webhooks in docs and dashboard",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: Sandbox create fails from template, but succeeds without template",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_3ae274a17e7e420ca9f2cd6e7c6105bd | https://github.com/e2b-dev/E2B/issues/1130 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：[Bug]: Sandbox create fails from template, but succeeds without template",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：build status polling timed out",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_88fc7403d6a44edb8b8d4c9deaff0279 | https://github.com/e2b-dev/E2B/issues/1009 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：build status polling timed out",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Paused sandbox is not persisting the file changes / addition after second time resumed and onward",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_2fc5340254c94ae2931673fede53e25b | https://github.com/e2b-dev/E2B/issues/884 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Paused sandbox is not persisting the file changes / addition after second time resumed and onward",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "[Bug]: torch.compile fails for Gemma3n on pytorch 2.8 ### Your current environment The output of python collect_env.py
```text Your output of `python collect_env.py` here ``` ### 🐛 Describe the bug run ``` vllm serve google/gemma-3n-E2B-it -tp 1 ``` on torch==2.8.0:…",
"category": "配置坑",
"evidence": [
"social_signal:github | ssig_3c3209f718cd4d108c88e3bf9d35db24 | https://github.com/vllm-project/vllm/issues/24547 | [Bug]: torch.compile fails for Gemma3n on pytorch 2.8"
],
"severity": "medium",
"suggested_check": "Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。",
"title": "社区讨论暴露的待验证问题：[Bug]: torch.compile fails for Gemma3n on pytorch 2.8",
"user_impact": "这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:609539715 | https://github.com/e2b-dev/E2B | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：When using autoPause in sandbox creation, connect overrides this when resuming the sandbox again",
"category": "维护坑",
"evidence": [
"community_evidence:github | cevd_3002fb1e72dd4aa2ab6baed80425d7b2 | https://github.com/e2b-dev/E2B/issues/875 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：When using autoPause in sandbox creation, connect overrides this when resuming the sandbox again",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:609539715 | https://github.com/e2b-dev/E2B | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:609539715 | https://github.com/e2b-dev/E2B | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:609539715 | https://github.com/e2b-dev/E2B | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：(feature request) Run-scoped messaging for multi-sandbox agent workflows",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_a6ad64f1b6d54498906e63b880471ac4 | https://github.com/e2b-dev/E2B/issues/1330 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：(feature request) Run-scoped messaging for multi-sandbox agent workflows",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：AuthenticationError: Unauthorized, please check your credentials. - Invalid API key",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_c6225e71e02943b7a367a36c86c96b65 | https://github.com/e2b-dev/E2B/issues/980 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：AuthenticationError: Unauthorized, please check your credentials. - Invalid API key",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Docker Build Secrets Support",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_6d5e325b8d00480b8ac7acf0b5b01379 | https://github.com/e2b-dev/E2B/issues/815 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Docker Build Secrets Support",
"user_impact": "可能影响升级、迁移或版本选择。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 20 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：配置坑 - 来源证据：process was not killed when auto paused。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 50,
"forks": 907,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 12212
},
"source_url": "https://github.com/e2b-dev/E2B",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "Open-source, secure environment with real-world tools for enterprise-grade agents.",
"title": "E2B 能力包",
"trial_prompt": "# E2B - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for e2b-dev/E2B.\n\nProject:\n- Name: E2B\n- Repository: https://github.com/e2b-dev/E2B\n- Summary: Open-source, secure environment with real-world tools for enterprise-grade agents.\n- Host target: local_cli\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: Open-source, secure environment with real-world tools for enterprise-grade agents.\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Open-source, secure environment with real-world tools for enterprise-grade agents.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. overview: Overview. Produce one small intermediate artifact and wait for confirmation.\n2. sandbox-usage: Sandbox Usage. Produce one small intermediate artifact and wait for confirmation.\n3. js-sdk: JavaScript/TypeScript SDK. Produce one small intermediate artifact and wait for confirmation.\n4. python-sdk: Python SDK. Produce one small intermediate artifact and wait for confirmation.\n5. sandbox-management: Sandbox Management. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/e2b-dev/E2B\n- https://github.com/e2b-dev/E2B#readme\n- README.md\n- CLAUDE.md\n- packages/js-sdk/src/index.ts\n- packages/python-sdk/e2b/__init__.py\n- packages/js-sdk/src/sandbox/index.ts\n- packages/js-sdk/src/sandbox/sandboxApi.ts\n- packages/python-sdk/e2b/sandbox/main.py\n- packages/python-sdk/e2b/sandbox/sandbox_api.py\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_issue: Paused sandbox is not persisting the file changes / addition after secon（https://github.com/e2b-dev/E2B/issues/884）；github/github_issue: (feature request) Run-scoped messaging for multi-sandbox agent workflows（https://github.com/e2b-dev/E2B/issues/1330）；github/github_issue: process was not killed when auto paused（https://github.com/e2b-dev/E2B/issues/1031）；github/github_issue: Docker Build Secrets Support（https://github.com/e2b-dev/E2B/issues/815）；github/github_issue: When using autoPause in sandbox creation, connect overrides this when re（https://github.com/e2b-dev/E2B/issues/875）；github/github_issue: Closed Port Error（https://github.com/e2b-dev/E2B/issues/907）；github/github_issue: AuthenticationError: Unauthorized, please check your credentials. - Inva（https://github.com/e2b-dev/E2B/issues/980）；github/github_issue: Template Build Fails with \"syncing took too long\" Error（https://github.com/e2b-dev/E2B/issues/996）；github/github_issue: build status polling timed out（https://github.com/e2b-dev/E2B/issues/1009）；github/github_issue: [Bug]: Incorrect info about webhooks in docs and dashboard（https://github.com/e2b-dev/E2B/issues/1103）；github/github_issue: How to use the file that I uploaded when I create template（https://github.com/e2b-dev/E2B/issues/1049）；github/github_issue: [Bug]: Sandbox create fails from template, but succeeds without template（https://github.com/e2b-dev/E2B/issues/1130）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "Paused sandbox is not persisting the file changes / addition after secon",
"url": "https://github.com/e2b-dev/E2B/issues/884"
},
{
"kind": "github_issue",
"source": "github",
"title": "(feature request) Run-scoped messaging for multi-sandbox agent workflows",
"url": "https://github.com/e2b-dev/E2B/issues/1330"
},
{
"kind": "github_issue",
"source": "github",
"title": "process was not killed when auto paused",
"url": "https://github.com/e2b-dev/E2B/issues/1031"
},
{
"kind": "github_issue",
"source": "github",
"title": "Docker Build Secrets Support",
"url": "https://github.com/e2b-dev/E2B/issues/815"
},
{
"kind": "github_issue",
"source": "github",
"title": "When using autoPause in sandbox creation, connect overrides this when re",
"url": "https://github.com/e2b-dev/E2B/issues/875"
},
{
"kind": "github_issue",
"source": "github",
"title": "Closed Port Error",
"url": "https://github.com/e2b-dev/E2B/issues/907"
},
{
"kind": "github_issue",
"source": "github",
"title": "AuthenticationError: Unauthorized, please check your credentials. - Inva",
"url": "https://github.com/e2b-dev/E2B/issues/980"
},
{
"kind": "github_issue",
"source": "github",
"title": "Template Build Fails with \"syncing took too long\" Error",
"url": "https://github.com/e2b-dev/E2B/issues/996"
},
{
"kind": "github_issue",
"source": "github",
"title": "build status polling timed out",
"url": "https://github.com/e2b-dev/E2B/issues/1009"
},
{
"kind": "github_issue",
"source": "github",
"title": "[Bug]: Incorrect info about webhooks in docs and dashboard",
"url": "https://github.com/e2b-dev/E2B/issues/1103"
},
{
"kind": "github_issue",
"source": "github",
"title": "How to use the file that I uploaded when I create template",
"url": "https://github.com/e2b-dev/E2B/issues/1049"
},
{
"kind": "github_issue",
"source": "github",
"title": "[Bug]: Sandbox create fails from template, but succeeds without template",
"url": "https://github.com/e2b-dev/E2B/issues/1130"
}
],
"status": "已收录 13 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "软件开发与交付",
"desc": "Open-source, secure environment with real-world tools for enterprise-grade agents.",
"effort": "安装已验证",
"forks": 907,
"icon": "code",
"name": "E2B 能力包",
"risk": "可发布",
"slug": "e2b",
"stars": 12212,
"tags": [
"浏览器 Agent",
"网页任务自动化",
"浏览器自动化",
"断点恢复流程",
"本地优先"
],
"thumb": "gray",
"type": "Skill Pack"
},
"manual": {
"markdown": "# https://github.com/e2b-dev/E2B 项目说明书\n\n生成时间：2026-05-18 03:19:07 UTC\n\n## 目录\n\n- [Overview](#overview)\n- [Installation](#installation)\n- [Sandbox Usage](#sandbox-usage)\n- [JavaScript/TypeScript SDK](#js-sdk)\n- [Python SDK](#python-sdk)\n- [CLI Tool](#cli-tool)\n- [Sandbox Management](#sandbox-management)\n- [Template System](#template-system)\n- [Filesystem and Git Operations](#filesystem-git)\n- [Network Configuration](#network-config)\n\n\n\n## Overview\n\n### 相关页面\n\n相关主题：[Sandbox Usage](#sandbox-usage), [JavaScript/TypeScript SDK](#js-sdk), [Python SDK](#python-sdk)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/e2b-dev/E2B/blob/main/README.md)\n- [packages/js-sdk/README.md](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/README.md)\n- [packages/python-sdk/README.md](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/README.md)\n- [packages/js-sdk/src/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/index.ts)\n- [packages/python-sdk/e2b/__init__.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/__init__.py)\n- [packages/js-sdk/src/template/types.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/template/types.ts)\n- [packages/js-sdk/src/sandbox/sandboxApi.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/sandboxApi.ts)\n- [packages/js-sdk/src/template/readycmd.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/template/readycmd.ts)\n \n\n# Overview\n\nE2B is an open-source infrastructure platform that enables developers to run AI-generated code in secure, isolated cloud-based sandboxes. It provides a unified API layer across multiple programming languages, allowing seamless integration of sandboxed code execution into AI applications, agents, and workflows.\n\n## What is E2B?\n\nE2B addresses the fundamental challenge of safely executing code generated by Large Language Models (LLMs) and AI agents. When AI systems produce code, executing that code directly in production environments poses significant security risks. E2B creates isolated execution environments where AI-generated code can be run safely without affecting the host system.\n\n资料来源：[README.md:1]()\n\n### Core Capabilities\n\n| Capability | Description |\n|------------|-------------|\n| **Secure Sandboxes** | Isolated cloud environments for safe code execution |\n| **Multi-Language SDKs** | Official JavaScript/TypeScript and Python SDKs |\n| **Template System** | Customizable sandbox environments with Dockerfile-like syntax |\n| **Code Interpreter** | Dedicated SDK for AI code execution use cases |\n| **MCP Server Support** | Integration with Model Context Protocol servers |\n| **Volume Management** | Persistent storage and file system operations |\n\n## Architecture Overview\n\nE2B's architecture consists of several interconnected components that work together to provide secure code execution.\n\n```mermaid\ngraph TD\n A[Client Application] --> B[E2B SDK]\n B --> C[API Gateway]\n C --> D[Sandbox Manager]\n D --> E[Isolated Sandbox]\n D --> F[Template Registry]\n E --> G[envd Runtime]\n F --> H[Docker Images]\n \n I[Volume Storage] <--> E\n J[MCP Gateway] --> C\n```\n\n### Key Components\n\n#### Sandboxes\n\nSandboxes are the core execution units in E2B. Each sandbox is an isolated environment based on a template that defines the base image, installed packages, environment variables, and startup commands.\n\n```mermaid\ngraph LR\n A[Sandbox Instance] --> B[Filesystem]\n A --> C[Process Execution]\n A --> D[Network Access]\n A --> E[Volume Mounts]\n```\n\nSandbox configuration options control the execution environment behavior:\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `templateID` | string | required | Template identifier to base the sandbox on |\n| `timeout` | number | 300000ms | Maximum execution time before auto-termination |\n| `secure` | boolean | `true` | Enable security restrictions |\n| `allowInternetAccess` | boolean | `true` | Control network connectivity |\n| `metadata` | object | `{}` | User-defined metadata for the sandbox |\n| `envs` | Record | `{}` | Environment variables to inject |\n\n资料来源：[packages/js-sdk/src/sandbox/sandboxApi.ts:1]()\n\n#### Templates\n\nTemplates define the configuration for sandbox environments. They use a fluent builder pattern to construct sandbox definitions that are then built and deployed to E2B infrastructure.\n\nSupported base images include:\n\n| Method | Description |\n|--------|-------------|\n| `fromBaseImage()` | E2B's default base image (e2bdev/base:latest) |\n| `fromDebianImage(variant?)` | Debian-based image |\n| `fromUbuntuImage(variant?)` | Ubuntu-based image |\n| `fromPythonImage(version?)` | Python runtime image |\n| `fromNodeImage(variant?)` | Node.js runtime image |\n| `fromBunImage(variant?)` | Bun runtime image |\n\n资料来源：[packages/js-sdk/src/template/types.ts:1]()\n\n## SDKs Overview\n\nE2B provides official SDKs for two major programming languages, both offering equivalent functionality through idiomatic API designs.\n\n### JavaScript/TypeScript SDK\n\nThe JavaScript SDK is available on npm and supports both CommonJS and ES modules.\n\n```bash\nnpm install e2b\n```\n\n资料来源：[packages/js-sdk/README.md:1]()\n\n**Installation and Quick Start:**\n\n```typescript\nimport Sandbox from 'e2b'\n\nconst sandbox = await Sandbox.create()\nconst result = await sandbox.commands.run('echo \"Hello from E2B!\"')\nconsole.log(result.stdout) // Hello from E2B!\n```\n\n### Python SDK\n\nThe Python SDK is available on PyPI and supports Python 3.8+.\n\n```bash\npip install e2b\n```\n\n资料来源：[packages/python-sdk/README.md:1]()\n\n**Installation and Quick Start:**\n\n```python\nfrom e2b import Sandbox\n\nwith Sandbox.create() as sandbox:\n result = sandbox.commands.run('echo \"Hello from E2B!\"')\n print(result.stdout) # Hello from E2B!\n```\n\n### Code Interpreter SDK\n\nFor AI applications requiring code execution capabilities (like REPLs or code agents), E2B provides a specialized Code Interpreter SDK.\n\n| SDK | Package | Use Case |\n|-----|---------|----------|\n| JS | `@e2b/code-interpreter` | AI agents, code generators |\n| Python | `e2b-code-interpreter` | AI agents, code generators |\n\n资料来源：[packages/js-sdk/README.md:1]()\n\n```typescript\nimport { Sandbox } from '@e2b/code-interpreter'\n\nconst sandbox = await Sandbox.create()\nconst execution = await sandbox.runCode('x = 1; x += 1; x')\nconsole.log(execution.text) // outputs 2\n```\n\n## Template Builder System\n\nTemplates in E2B use a fluent builder pattern that generates Dockerfile-like instructions. This approach provides flexibility while maintaining simplicity.\n\n### Instruction Types\n\n| Instruction | Description |\n|-------------|-------------|\n| `run_cmd()` / `RUN` | Execute shell commands during build |\n| `copy()` / `COPY` | Copy files into the sandbox |\n| `set_envs()` / `ENV` | Set environment variables |\n| `add_mcp_server()` | Install MCP servers via mcp-gateway |\n| `apt_install()` | Install APT packages |\n\n资料来源：[packages/python-sdk/e2b/template/main.py:1]()\n\n### Template Lifecycle\n\n```mermaid\nstateDiagram-v2\n [*] --> TemplateBuilder: Create Template\n TemplateBuilder --> TemplateBuilder: Add Instructions\n TemplateBuilder --> TemplateBuilder: Configure Start Command\n TemplateBuilder --> TemplateFinal: set_start_cmd()\n TemplateFinal --> Building: Template.build()\n Building --> BuildInfo: Success\n Building --> Error: Failure\n BuildInfo --> [*]\n Error --> [*]\n```\n\n### Ready Commands\n\nReady commands determine when a sandbox is considered fully initialized and ready to accept requests:\n\n| Function | Implementation | Use Case |\n|----------|---------------|----------|\n| `waitForURL(url, statusCode)` | `curl` + `grep` | HTTP service health checks |\n| `waitForProcess(name)` | `pgrep` | Daemon process verification |\n| `waitForFile(path)` | shell test | File system readiness |\n\n资料来源：[packages/js-sdk/src/template/readycmd.ts:1]()\n\n## File System Operations\n\nE2B provides comprehensive file system operations within sandboxes through the `Filesystem` API.\n\n### Supported Read Formats\n\n| Format | Return Type | Use Case |\n|--------|-------------|----------|\n| `text` (default) | `string` | Source code, configs |\n| `bytes` | `Uint8Array` | Binary files |\n| `blob` | `Blob` | Web-compatible binary |\n| `stream` | `ReadableStream` | Large file handling |\n\nFilesystem operations support gzip compression via the `gzip` option to reduce network transfer for large files.\n\n资料来源：[packages/js-sdk/src/sandbox/filesystem/index.ts:1]()\n\n## Command Execution\n\nCommands executed within sandboxes return structured results containing stdout, stderr, and exit codes.\n\n### Command Result Properties\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `stdout` | string | Standard output content |\n| `stderr` | string | Standard error content |\n| `exitCode` | number | Process exit code (0 = success) |\n| `error` | string | Error message if execution failed |\n\nThe `CommandHandle.wait()` method throws a `CommandExitError` when the exit code is non-zero, enabling automatic error propagation in async workflows.\n\n资料来源：[packages/js-sdk/src/sandbox/commands/commandHandle.ts:1]()\n\n## Volume System\n\nVolumes provide persistent storage that can be mounted into sandboxes. They are managed through the Volume API which supports CRUD operations on files and directories.\n\n### Volume Mount Configuration\n\n```typescript\nopts.volumeMounts = {\n '/mount/path': 'volume-name'\n}\n```\n\nEach mount maps a volume name to a path within the sandbox filesystem.\n\n资料来源：[packages/js-sdk/src/sandbox/sandboxApi.ts:1]()\n\n### Volume Read Operations\n\n| Format | API Method | Return Type |\n|--------|------------|-------------|\n| text | `readFile(path, { format: 'text' })` | `string` |\n| bytes | `readFile(path, { format: 'bytes' })` | `Uint8Array` |\n| blob | `readFile(path, { format: 'blob' })` | `Blob` |\n| stream | `readFile(path, { format: 'stream' })` | `ReadableStream` |\n\n资料来源：[packages/js-sdk/src/volume/index.ts:1]()\n\n## Authentication\n\nAll E2B SDKs require API key authentication. The API key should be set as an environment variable before initializing SDK clients.\n\n```bash\nexport E2B_API_KEY=e2b_your_api_key_here\n```\n\nAPI keys can be obtained from the E2B dashboard at https://e2b.dev/dashboard?tab=keys.\n\n## Next Steps\n\n| Resource | Description |\n|----------|-------------|\n| [JavaScript SDK Guide](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/README.md) | Detailed JS/TS SDK documentation |\n| [Python SDK Guide](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/README.md) | Detailed Python SDK documentation |\n| [E2B Cookbook](https://github.com/e2b-dev/e2b-cookbook) | Example projects with various LLMs |\n| [Official Documentation](https://www.e2b.dev/docs) | Full platform documentation |\n\n---\n\n\n\n## Installation\n\n### 相关页面\n\n相关主题：[JavaScript/TypeScript SDK](#js-sdk), [Python SDK](#python-sdk), [CLI Tool](#cli-tool)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/js-sdk/package.json](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/package.json)\n- [packages/python-sdk/pyproject.toml](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/pyproject.toml)\n- [packages/cli/package.json](https://github.com/e2b-dev/E2B/blob/main/packages/cli/package.json)\n- [packages/python-sdk/README.md](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/README.md)\n- [packages/js-sdk/README.md](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/README.md)\n \n\n# Installation\n\nThis guide covers how to install and configure the E2B SDKs for different programming languages. E2B provides two official SDKs: a Python SDK and a JavaScript/TypeScript SDK, both enabling developers to run AI-generated code in secure isolated sandboxes in the cloud.\n\n## Prerequisites\n\nBefore installing any E2B SDK, ensure you have:\n\n| Requirement | Description |\n|-------------|-------------|\n| **E2B Account** | Sign up at [e2b.dev](https://www.e2b.dev) |\n| **API Key** | Obtain from [E2B Dashboard](https://www.e2b.dev/dashboard?tab=keys) |\n| **Runtime** | Python 3.x or Node.js 18+ depending on SDK |\n\nYou must set the `E2B_API_KEY` environment variable with your API key before using the SDK:\n\n```bash\nexport E2B_API_KEY=e2b_***\n```\n\n## SDK Overview\n\nE2B provides multiple SDK packages depending on your use case:\n\n| SDK Package | Purpose | Language |\n|-------------|---------|----------|\n| `e2b` | Core sandbox functionality | Python |\n| `e2b` | Core sandbox functionality | JavaScript/TypeScript |\n| `@e2b/code-interpreter` | Code execution sandbox | Python |\n| `@e2b/code-interpreter` | Code execution sandbox | JavaScript/TypeScript |\n| `e2b` (CLI) | Command-line interface | Node.js |\n\n## Installing the Python SDK\n\n### Core SDK\n\nInstall the core E2B Python SDK using pip:\n\n```bash\npip install e2b\n```\n\nThe SDK is published to PyPI and can be installed in any Python environment with pip support. The package includes all necessary dependencies for sandbox management, command execution, and file operations.\n\n### Code Interpreter SDK\n\nFor running AI-generated code in a sandboxed environment:\n\n```bash\npip install e2b-code-interpreter\n```\n\nThis specialized SDK provides enhanced code execution capabilities with support for multiple programming languages and automatic dependency resolution.\n\n## Installing the JavaScript/TypeScript SDK\n\n### Core SDK\n\nInstall the E2B JavaScript SDK using npm:\n\n```bash\nnpm i e2b\n```\n\nThe JavaScript SDK supports both CommonJS and ESM module formats. It is written in TypeScript and includes full type definitions out of the box.\n\n### Code Interpreter SDK\n\nFor JavaScript-based code execution:\n\n```bash\nnpm i @e2b/code-interpreter\n```\n\n## Installing the CLI\n\nThe E2B CLI provides command-line access to template management and sandbox operations.\n\n### Installation via npm\n\n```bash\nnpm i e2b\n```\n\n### Installation via npx\n\nFor one-time usage without global installation:\n\n```bash\nnpx e2b \n```\n\n## Package Dependencies\n\n### Python SDK Dependencies\n\nThe Python SDK requires the following runtime dependencies:\n\n- `httpx` - HTTP client for API communication\n- Python 3.8+ compatible\n\n### JavaScript SDK Dependencies\n\nThe JavaScript SDK requires:\n\n- Node.js 18 or higher\n- Browser environment support (for client-side usage)\n\n## Verifying Installation\n\nAfter installation, verify that the SDK is correctly installed by checking the version or importing the package:\n\n### Python Verification\n\n```python\nimport e2b\nprint(e2b.__version__)\n```\n\n### JavaScript Verification\n\n```javascript\nimport Sandbox from 'e2b'\nconsole.log(Sandbox)\n```\n\n## Environment Configuration\n\n### Required Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `E2B_API_KEY` | Yes | Your E2B API key for authentication |\n\n### Optional Configuration\n\nThe SDKs support additional configuration options passed during client initialization:\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `timeout` | number | varies | Maximum request timeout in seconds |\n| `verify_ssl` | boolean | true | Whether to verify SSL certificates |\n| `follow_redirects` | boolean | false | Whether to follow HTTP redirects |\n| `base_url` | string | E2B API | Custom API endpoint URL |\n\n## Quick Start After Installation\n\nOnce installed, you can create and use sandboxes:\n\n### Python Example\n\n```python\nfrom e2b import Sandbox\n\nwith Sandbox.create() as sandbox:\n result = sandbox.commands.run('echo \"Hello from E2B!\"')\n print(result.stdout) # Hello from E2B!\n```\n\n### JavaScript/TypeScript Example\n\n```typescript\nimport Sandbox from 'e2b'\n\nconst sandbox = await Sandbox.create()\nconst result = await sandbox.commands.run('echo \"Hello from E2B!\"')\nconsole.log(result.stdout) // Hello from E2B!\n```\n\n### Code Interpreter Example (Python)\n\n```python\nfrom e2b_code_interpreter import Sandbox\n\nwith Sandbox.create() as sandbox:\n execution = sandbox.run_code(\"x = 1; x += 1; x\")\n print(execution.text) # outputs 2\n```\n\n## Installation from Source\n\nFor development or custom builds, you can install from source:\n\n```bash\n# Clone the repository\ngit clone https://github.com/e2b-dev/E2B.git\ncd E2B\n\n# Install Python SDK from source\ncd packages/python-sdk\npip install -e .\n\n# Install JavaScript SDK from source\ncd ../js-sdk\nnpm install\n```\n\n## Troubleshooting\n\n### Common Installation Issues\n\n| Issue | Solution |\n|-------|----------|\n| `ModuleNotFoundError` | Ensure pip/npm is updated and try reinstalling |\n| API key errors | Verify `E2B_API_KEY` environment variable is set correctly |\n| Network timeouts | Check firewall/proxy settings for outbound HTTPS connections |\n| Version conflicts | Use virtual environments or ensure Node.js version compatibility |\n\n### Getting Help\n\nIf installation issues persist:\n\n- Check [E2B Documentation](https://e2b.dev/docs)\n- Contact support at [https://e2b.dev/docs/support](https://e2b.dev/docs/support)\n- Visit the [E2B Cookbook](https://github.com/e2b-dev/e2b-cookbook) for examples\n\n---\n\n\n\n## Sandbox Usage\n\n### 相关页面\n\n相关主题：[Sandbox Management](#sandbox-management), [Filesystem and Git Operations](#filesystem-git), [Network Configuration](#network-config)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/js-sdk/src/sandbox/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/index.ts)\n- [packages/js-sdk/src/sandbox/sandboxApi.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/sandboxApi.ts)\n- [packages/js-sdk/src/api/schema.gen.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/api/schema.gen.ts)\n- [packages/python-sdk/e2b/sandbox_async/sandbox_api.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_async/sandbox_api.py)\n- [packages/python-sdk/e2b/sandbox_async/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_async/main.py)\n- [packages/python-sdk/e2b/sandbox_sync/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_sync/main.py)\n- [packages/python-sdk/e2b/template/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template/main.py)\n- [packages/cli/src/commands/sandbox/info.ts](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/sandbox/info.ts)\n- [README.md](https://github.com/e2b-dev/E2B/blob/main/README.md)\n \n\n# Sandbox Usage\n\n## Overview\n\nA **Sandbox** in E2B is a secure, isolated cloud environment that allows you to execute AI-generated code safely. Sandboxes provide a controlled runtime environment with configurable resources, network settings, and lifecycle management. They are created from **sandbox templates** that define the base configuration, installed dependencies, and startup behavior of the environment.\n\nSandboxes are the core execution unit in E2B, providing:\n- Isolated execution of untrusted code\n- Configurable CPU and memory resources\n- Network access control\n- File system operations\n- Terminal/PTY access\n- Git operations\n\n资料来源：[README.md:1-20](https://github.com/e2b-dev/E2B/blob/main/README.md)\n\n## Architecture\n\n```mermaid\ngraph TD\n A[Developer/AI Agent] -->|Creates Sandbox| B[E2B API]\n B -->|Template Config| C[Sandbox Instance]\n C -->|Provides| D[Filesystem API]\n C -->|Provides| E[Commands API]\n C -->|Provides| F[PTY/Terminal API]\n C -->|Provides| G[Git API]\n C -->|Manages| H[Lifecycle & Timeout]\n \n I[Template Definition] -->|Defines base image| C\n J[Resource Config] -->|CPU/Memory| C\n K[Network Config] -->|Internet access| C\n```\n\n## Creating a Sandbox\n\n### JavaScript/TypeScript SDK\n\n#### Create with default template\n\n```typescript\nimport Sandbox from 'e2b'\n\nconst sandbox = await Sandbox.create()\nconst result = await sandbox.commands.run('echo \"Hello from E2B!\"')\nconsole.log(result.stdout) // Hello from E2B!\n```\n\n资料来源：[packages/js-sdk/src/sandbox/index.ts:80-100](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/index.ts)\n\n#### Create with specific template\n\n```typescript\nconst sandbox = await Sandbox.create('my-custom-template')\n```\n\n#### Create with options\n\n```typescript\nconst sandbox = await Sandbox.create({\n template: 'my-template',\n metadata: { user: 'alice', app: 'production' },\n envs: { NODE_ENV: 'production' },\n timeoutMs: 60000,\n})\n```\n\n资料来源：[packages/js-sdk/src/sandbox/index.ts:95-130](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/index.ts)\n\n### Python SDK\n\n#### Async usage\n\n```python\nimport asyncio\nfrom e2b import Sandbox\n\nasync def main():\n sandbox = await Sandbox.create()\n result = sandbox.commands.run('echo \"Hello from E2B!\"')\n print(result.stdout) # Hello from E2B!\n\nasyncio.run(main())\n```\n\n#### Sync usage\n\n```python\nfrom e2b import Sandbox\n\nwith Sandbox.create() as sandbox:\n result = sandbox.commands.run('echo \"Hello from E2B!\"')\n print(result.stdout) # Hello from E2B!\n```\n\n资料来源：[README.md:30-50](https://github.com/e2b-dev/E2B/blob/main/README.md)\n\n## Sandbox Options\n\n### Configuration Parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `template` | `string` | `'base'` | Sandbox template name or ID. Use `'mcp-gateway'` when `mcp` option is set |\n| `metadata` | `Record` | `{}` | Custom metadata for the sandbox |\n| `envs` | `Record` | `{}` | Custom environment variables for the sandbox |\n| `timeoutMs` | `number` | varies | Timeout in milliseconds (max 24h for Pro, 1h for Hobby) |\n| `mcp` | `boolean` | `false` | Enable MCP gateway support |\n| `onTimeout` | `'pause' \\| 'kill'` | `'pause'` | Action on sandbox timeout |\n| `autoResume` | `boolean` | `false` | Auto-resume paused sandbox (requires `onTimeout: 'pause'`) |\n| `cpuCount` | `number` | `2` | Number of CPU cores |\n| `memoryMB` | `number` | `512` | Memory in MiB (must be even) |\n| `allowInternetAccess` | `boolean` | `true` | Enable/disable internet access |\n| `network` | `boolean \\| SandboxNetworkOpts` | `true` | Network configuration |\n| `volumeMounts` | `Array<{name, path}>` | `[]` | Volume mounts |\n\n资料来源：[packages/js-sdk/src/sandbox/sandboxApi.ts:50-120](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/sandboxApi.ts)\n资料来源：[packages/python-sdk/e2b/sandbox_async/sandbox_api.py:1-50](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_async/sandbox_api.py)\n\n### Network Configuration\n\n```typescript\nconst sandbox = await Sandbox.create({\n network: true, // Full network access (default)\n // Or with custom configuration:\n network: {\n timeoutMs: 30000,\n }\n})\n```\n\n### Resource Configuration\n\n```typescript\nconst sandbox = await Sandbox.create({\n cpuCount: 4, // Number of CPUs (default: 2)\n memoryMB: 1024, // Memory in MiB (default: 512, must be even)\n})\n```\n\n### Lifecycle Configuration\n\n```typescript\nconst sandbox = await Sandbox.create({\n timeoutMs: 3600000, // 1 hour max\n lifecycle: {\n onTimeout: 'pause', // Pause instead of kill\n autoResume: true, // Auto-resume when accessed\n }\n})\n```\n\n资料来源：[packages/js-sdk/src/sandbox/sandboxApi.ts:40-70](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/sandboxApi.ts)\n\n## Sandbox API Response\n\nWhen a sandbox is created, the API returns a `SandboxInfo` object containing:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `sandboxId` | `string` | Unique sandbox identifier |\n| `sandboxDomain` | `string` | Domain name for the sandbox |\n| `envdVersion` | `string` | Version of envd running in sandbox |\n| `envdAccessToken` | `string` | Token for envd API authentication |\n| `trafficAccessToken` | `string` | Token for traffic authentication |\n| `templateId` | `string` | ID of the template used |\n| `name` | `string` | Sandbox alias/name |\n| `startedAt` | `Date` | Sandbox start time |\n| `endAt` | `Date` | Sandbox expiration date |\n| `state` | `'running' \\| 'paused'` | Current sandbox state |\n| `cpuCount` | `number` | Number of CPUs allocated |\n| `memoryMB` | `number` | Memory allocated in MiB |\n| `metadata` | `Record` | Custom metadata |\n| `allowInternetAccess` | `boolean` | Internet access setting |\n| `lifecycle` | `SandboxInfoLifecycle` | Lifecycle configuration |\n| `volumeMounts` | `Array<{name, path}>` | Mounted volumes |\n\n资料来源：[packages/js-sdk/src/api/schema.gen.ts:1-80](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/api/schema.gen.ts)\n资料来源：[packages/js-sdk/src/sandbox/sandboxApi.ts:200-280](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/sandboxApi.ts)\n\n## Sandbox State Machine\n\n```mermaid\nstateDiagram-v2\n [*] --> Creating: Sandbox.create()\n Creating --> Running: Sandbox ready\n Running --> Paused: Timeout reached (if onTimeout: pause)\n Running --> Killed: Timeout reached (if onTimeout: kill)\n Paused --> Running: Sandbox accessed\n Paused --> Killed: Timeout reached\n Running --> [*]: sandbox.kill()\n Paused --> [*]: sandbox.kill()\n Killed --> [*]: Sandbox terminated\n```\n\n## Sandbox Instances\n\n### JavaScript SDK Instance\n\nThe `Sandbox` class provides the following APIs:\n\n| API | Description |\n|-----|-------------|\n| `sandbox.filesystem` | File system operations (upload, download, list, etc.) |\n| `sandbox.commands` | Execute shell commands |\n| `sandbox.pty` | Terminal/PTY access |\n| `sandbox.git` | Git operations |\n\n```typescript\nconst sandbox = await Sandbox.create()\n\n// File operations\nawait sandbox.filesystem.write('/app/main.py', 'print(\"hello\")')\nconst content = await sandbox.filesystem.read('/app/main.py')\n\n// Run commands\nconst result = await sandbox.commands.run('python /app/main.py')\n\n// Terminal access\nconst pty = await sandbox.pty.start({ cmd: 'bash' })\n```\n\n资料来源：[packages/js-sdk/src/sandbox/index.ts:130-180](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/index.ts)\n\n### Python SDK Instance\n\n```python\nsandbox = await Sandbox.create()\n\n# File operations\nawait sandbox.filesystem.write('/app/main.py', 'print(\"hello\")')\n\n# Run commands\nresult = sandbox.commands.run('python /app/main.py')\n\n# Cleanup\nawait sandbox.kill()\n```\n\nOr with sync context manager:\n\n```python\nwith Sandbox.create() as sandbox:\n result = sandbox.commands.run('echo \"Hello\"')\n```\n\n## Sandbox Metrics\n\nSandbox resource usage can be monitored through the metrics API:\n\n| Metric | Type | Description |\n|--------|------|-------------|\n| `timestamp` | `Date` | Timestamp of metrics |\n| `cpuUsedPct` | `number` | CPU usage percentage |\n| `cpuCount` | `number` | Number of CPU cores |\n| `memUsed` | `number` | Memory used in bytes |\n| `memTotal` | `number` | Total memory in bytes |\n| `diskUsed` | `number` | Used disk space in bytes |\n| `diskTotal` | `number` | Total disk space in bytes |\n\n资料来源：[packages/js-sdk/src/sandbox/sandboxApi.ts:250-300](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/sandboxApi.ts)\n\n## CLI Commands\n\n### List Sandboxes\n\n```bash\ne2b sandbox list\n```\n\n### Get Sandbox Info\n\n```bash\ne2b sandbox info \n# or\ne2b sandbox in \n```\n\nOptions:\n- `-f, --format ` - Output format (json, pretty)\n\nThe info command displays:\n\n| Field | Label |\n|-------|-------|\n| `sandboxId` | Sandbox ID |\n| `templateId` | Template ID |\n| `name` | Alias |\n| `startedAt` | Started at |\n| `endAt` | End at |\n| `state` | State |\n| `cpuCount` | vCPUs |\n| `memoryMB` | RAM MiB |\n| `envdVersion` | Envd version |\n| `allowInternetAccess` | Internet access |\n| `lifecycle` | Lifecycle |\n| `network` | Network |\n| `sandboxDomain` | Sandbox domain |\n| `metadata` | Metadata |\n\n资料来源：[packages/cli/src/commands/sandbox/info.ts:1-60](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/sandbox/info.ts)\n\n### Create Sandbox Template\n\n```bash\ne2b template create \n```\n\nOptions:\n- `-p, --path ` - Path to template directory\n- `-d, --dockerfile ` - Custom Dockerfile name\n- `-c, --cmd ` - Command executed when sandbox starts\n- `--ready-cmd ` - Command that must exit 0 for sandbox to be ready\n- `--cpu-count ` - Number of CPUs (default: 2)\n- `--memory-mb ` - Memory in MB (default: 512, must be even)\n- `--no-cache` - Skip cache when building\n\n### Build Sandbox Template\n\n```bash\ne2b template build [template-id]\n# or\ne2b template bd [template-id]\n```\n\nOptions:\n- `-p, --path ` - Path to template directory\n- `-d, --dockerfile ` - Custom Dockerfile name\n- `-n, --name ` - Template name\n- `-c, --cmd ` - Command executed when sandbox starts\n- `--ready-cmd ` - Command that must exit 0\n- `--cpu-count ` - Number of CPUs\n- `--memory-mb ` - Memory in MB\n- `--build-arg ` - Build arguments\n- `--no-cache` - Skip cache when building\n\n资料来源：[packages/cli/src/commands/template/create.ts:1-100](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/template/create.ts)\n资料来源：[packages/cli/src/commands/template/build.ts:1-100](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/template/build.ts)\n\n## Beta Features\n\n### MCP Gateway\n\nEnable MCP (Model Context Protocol) gateway support:\n\n```typescript\nconst sandbox = await Sandbox.betaCreate({\n mcp: true,\n // Uses 'mcp-gateway' template by default\n})\n```\n\n### Dev Container Support\n\nTemplates can use devcontainer configuration:\n\n```typescript\ntemplate\n .gitClone('https://myrepo.com/project.git', '/my-devcontainer')\n .betaDevContainerPrebuild('/my-devcontainer')\n .betaSetDevContainerStart('/my-devcontainer')\n```\n\n资料来源：[packages/js-sdk/src/sandbox/index.ts:40-80](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/index.ts)\n资料来源：[packages/js-sdk/src/template/types.ts:1-50](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/template/types.ts)\n\n## Timeout and Lifecycle Management\n\n### Maximum Timeout Limits\n\n| User Tier | Maximum Timeout |\n|-----------|-----------------|\n| Pro | 24 hours (86,400,000 ms) |\n| Hobby | 1 hour (3,600,000 ms) |\n\n### Lifecycle Options\n\n```typescript\n// Option 1: Pause sandbox on timeout\nconst sandbox = await Sandbox.create({\n timeoutMs: 3600000,\n lifecycle: {\n onTimeout: 'pause',\n autoResume: true, // Can auto-resume when accessed\n }\n})\n\n// Option 2: Kill sandbox on timeout\nconst sandbox = await Sandbox.create({\n timeoutMs: 3600000,\n lifecycle: {\n onTimeout: 'kill', // Sandbox is terminated\n }\n})\n```\n\nWhen a sandbox is paused, accessing it again will automatically resume it, allowing you to continue where you left off (with some limitations based on the template).\n\n资料来源：[packages/js-sdk/src/sandbox/sandboxApi.ts:20-60](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/sandboxApi.ts)\n\n## Best Practices\n\n1. **Always clean up resources**: Use context managers or explicitly call `kill()` to terminate sandboxes when done.\n\n2. **Set appropriate timeouts**: Match the timeout to your workload. Shorter timeouts are more cost-effective for quick tasks.\n\n3. **Use metadata for tracking**: Add meaningful metadata to easily identify sandboxes in listings.\n\n4. **Handle errors gracefully**: Catch exceptions for sandbox creation and command execution.\n\n5. **Use pause lifecycle for interactive sessions**: When you need to resume work later, use `onTimeout: 'pause'` with `autoResume: true`.\n\n6. **Configure resources appropriately**: Allocate CPU and memory based on your actual workload requirements.\n\n---\n\n\n\n## JavaScript/TypeScript SDK\n\n### 相关页面\n\n相关主题：[Python SDK](#python-sdk), [CLI Tool](#cli-tool), [Sandbox Usage](#sandbox-usage)\n\n\nRelated Source Files
\n\nThe following source files were used to generate this documentation:\n\n- [packages/js-sdk/src/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/index.ts)\n- [packages/js-sdk/src/sandbox/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/index.ts)\n- [packages/js-sdk/src/connectionConfig.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/connectionConfig.ts)\n- [packages/js-sdk/src/errors.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/errors.ts)\n- [packages/js-sdk/src/sandbox/commands/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/commands/index.ts)\n- [packages/js-sdk/src/sandbox/filesystem/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/filesystem/index.ts)\n- [packages/js-sdk/src/sandbox/network.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/network.ts)\n- [packages/js-sdk/src/volume/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/volume/index.ts)\n- [packages/js-sdk/tsup.config.js](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/tsup.config.js)\n \n\n# JavaScript/TypeScript SDK\n\n## Overview\n\nThe E2B JavaScript/TypeScript SDK (`e2b`) is an official client library that enables developers to interact with E2B's cloud-based sandbox infrastructure for running AI-generated code in secure, isolated environments. The SDK provides a programmatic interface to create, manage, and communicate with sandboxes, as well as to work with templates and volumes. 资料来源：[packages/js-sdk/README.md]()\n\n### Key Capabilities\n\nThe SDK supports multiple runtime environments including Node.js and browser applications, offering a unified API for sandbox operations. Developers can spawn isolated sandboxes, execute commands, manage files, handle network communications, and mount persistent storage volumes through a well-structured TypeScript interface. 资料来源：[packages/js-sdk/src/api/metadata.ts]()\n资料来源：[packages/js-sdk/tsup.config.js]()\n\n### Package Configuration\n\nThe SDK is published to npm under the package name `e2b` and includes both ESM and CommonJS formats for maximum compatibility. 资料来源：[packages/js-sdk/README.md]()\n\n```json\n{\n \"name\": \"e2b\",\n \"version\": \"^2.19.3\",\n \"main\": \"./dist/index.js\",\n \"module\": \"./dist/index.mjs\",\n \"types\": \"./dist/index.d.ts\"\n}\n```\n\n## Architecture Overview\n\nThe SDK architecture follows a modular design pattern with distinct layers for API communication, sandbox management, and utility functions. 资料来源：[packages/js-sdk/src/index.ts]()\n\n```mermaid\ngraph TD\n A[Client Application] --> B[SDK Entry Point
packages/js-sdk/src/index.ts]\n B --> C[Sandbox Manager
sandbox/index.ts]\n B --> D[Connection Config
connectionConfig.ts]\n B --> E[Error Handling
errors.ts]\n C --> F[Filesystem API
filesystem/index.ts]\n C --> G[Commands API
commands/index.ts]\n C --> H[Network API
network.ts]\n C --> I[Volume API
volume/index.ts]\n D --> J[E2B API Server]\n J --> K[Sandbox Instances]\n```\n\n### Core Components\n\n| Component | File Location | Purpose |\n|-----------|---------------|---------|\n| Entry Point | `src/index.ts` | Exports all public APIs |\n| Sandbox Manager | `src/sandbox/index.ts` | Manages sandbox lifecycle |\n| Connection Config | `src/connectionConfig.ts` | Handles API configuration and authentication |\n| Error Handling | `src/errors.ts` | Defines SDK-specific error types |\n| Filesystem | `src/sandbox/filesystem/index.ts` | File operations within sandboxes |\n| Commands | `src/sandbox/commands/index.ts` | Execute commands in sandboxes |\n| Network | `src/sandbox/network.ts` | Network configuration and proxies |\n| Volume | `src/volume/index.ts` | Persistent storage management |\n\n## Installation and Setup\n\n### Prerequisites\n\n- Node.js 18 or higher\n- An E2B API key\n\n### Installation\n\n```bash\nnpm install e2b\n```\n\n### Environment Configuration\n\nThe SDK automatically reads the `E2B_API_KEY` environment variable for authentication. You can also configure the API key programmatically through the connection configuration. 资料来源：[packages/js-sdk/src/api/metadata.ts]()\n\n```typescript\nimport { E2B } from 'e2b'\n\n// SDK automatically reads E2B_API_KEY from environment\nconst client = new E2B()\n```\n\n### Runtime Detection\n\nThe SDK detects the runtime environment and sets appropriate headers for API requests. It supports Node.js, Deno, and browser environments. 资料来源：[packages/js-sdk/src/api/metadata.ts]()\n\n```typescript\n// Runtime detection in metadata.ts\nexport const defaultHeaders = {\n browser: (typeof window !== 'undefined' && platform.name) || 'unknown',\n lang: 'js',\n lang_version: runtimeVersion,\n package_version: version,\n publisher: 'e2b',\n sdk_runtime: runtime,\n system: platform.os?.family || 'unknown',\n}\n```\n\n## Sandbox Management\n\nThe Sandbox class is the primary interface for interacting with E2B sandboxes. It provides methods for lifecycle management, file operations, command execution, and network configuration. 资料来源：[packages/js-sdk/src/sandbox/index.ts]()\n\n### Creating a Sandbox\n\n```typescript\nimport { E2B } from 'e2b'\n\nconst client = new E2B()\n\n// Create a sandbox from a template\nconst sandbox = await client.createSandbox({\n template: 'base',\n metadata: { userId: '12345' }\n})\n\nconsole.log('Sandbox ID:', sandbox.id)\nconsole.log('Sandbox URL:', sandbox.url)\n```\n\n### Sandbox Configuration\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `template` | `string` | Template ID to use for the sandbox |\n| `timeout` | `number` | Timeout in milliseconds |\n| `metadata` | `Record` | Custom metadata for filtering |\n| `aliases` | `string[]` | Alternative names for the sandbox |\n\n### Sandbox Lifecycle\n\n```mermaid\nstateDiagram-v2\n [*] --> Created: client.createSandbox()\n Created --> Starting: sandbox.start()\n Starting --> Running: sandbox ready\n Running --> Stopping: sandbox.kill() or timeout\n Stopping --> Stopped: cleanup complete\n Stopped --> [*]\n \n Running --> Error: exception\n Error --> [*]\n```\n\n### Stopping a Sandbox\n\nAlways ensure proper cleanup by stopping sandboxes when they are no longer needed:\n\n```typescript\ntry {\n const sandbox = await client.createSandbox({ template: 'base' })\n \n // Perform operations...\n \n await sandbox.kill()\n} finally {\n // Sandbox is now terminated\n}\n```\n\n## Filesystem Operations\n\nThe SDK provides comprehensive filesystem operations through the filesystem module, enabling reading, writing, and managing files within sandboxes. 资料来源：[packages/js-sdk/src/sandbox/filesystem/index.ts]()\n\n### File Operations\n\n| Method | Description |\n|--------|-------------|\n| `write(path, content)` | Write content to a file |\n| `read(path)` | Read file content |\n| `list(path)` | List directory contents |\n| `mkdir(path)` | Create a directory |\n| `remove(path)` | Remove a file or directory |\n| `exists(path)` | Check if path exists |\n\n### Reading Files\n\n```typescript\nconst content = await sandbox.filesystem.read('/app/data.json')\nconsole.log('File content:', content)\n```\n\n### Writing Files\n\n```typescript\nawait sandbox.filesystem.write('/app/output.txt', 'Hello, E2B!')\n```\n\n### Listing Directory Contents\n\n```typescript\nconst files = await sandbox.filesystem.list('/app')\nconsole.log('Files:', files)\n```\n\n## Command Execution\n\nExecute shell commands within the sandbox environment using the commands API. This is essential for running build scripts, installing packages, and performing system operations. 资料来源：[packages/js-sdk/src/sandbox/commands/index.ts]()\n\n### Running Commands\n\n```typescript\nconst result = await sandbox.commands.run('ls -la /app')\n\nconsole.log('Exit code:', result.exitCode)\nconsole.log('Stdout:', result.stdout)\nconsole.log('Stderr:', result.stderr)\n```\n\n### Command Options\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `timeout` | `number` | Command timeout in milliseconds |\n| `envVars` | `Record` | Environment variables |\n| `user` | `string` | User to run command as |\n\n### Streaming Command Output\n\nFor long-running commands, you can stream output:\n\n```typescript\nconst process = sandbox.commands.runStreaming('npm install')\n\nprocess.stdout.on('data', (data) => {\n console.log('Output:', data.toString())\n})\n\nconst exitCode = await process.exitCode\n```\n\n## Network Configuration\n\nThe network module provides configuration for network proxies, DNS settings, and sandbox connectivity options. 资料来源：[packages/js-sdk/src/sandbox/network.ts]()\n\n### Network Settings\n\n```typescript\nconst sandbox = await client.createSandbox({\n template: 'base',\n network: true // Enable networking\n})\n```\n\n### Available Network Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `network` | `boolean` | `true` | Enable/disable network access |\n| `dns` | `string[]` | System DNS | Custom DNS servers |\n\n## Volume Management\n\nVolumes provide persistent storage that survives sandbox restarts. They are useful for maintaining state across sandbox sessions. 资料来源：[packages/js-sdk/src/volume/index.ts]()\n\n### Creating and Mounting Volumes\n\n```typescript\n// Create a volume\nconst volume = await client.volumes.create({\n name: 'my-data-volume'\n})\n\n// Mount volume to sandbox\nconst sandbox = await client.createSandbox({\n template: 'base',\n volumes: [\n { volumeId: volume.id, mountPath: '/data' }\n ]\n})\n```\n\n### Volume Operations\n\n| Method | Description |\n|--------|-------------|\n| `create(config)` | Create a new volume |\n| `delete(volumeId)` | Delete a volume |\n| `list()` | List all volumes |\n\n## Error Handling\n\nThe SDK defines custom error types for different failure scenarios, making it easier to handle errors appropriately in your application. 资料来源：[packages/js-sdk/src/errors.ts]()\n\n### Error Types\n\n| Error Type | Description |\n|------------|-------------|\n| `AuthenticationError` | Invalid or missing API key |\n| `TimeoutError` | Operation exceeded timeout |\n| `SandboxError` | Sandbox creation or operation failure |\n| `RateLimitError` | API rate limit exceeded |\n| `ValidationError` | Invalid parameters or configuration |\n\n### Error Handling Pattern\n\n```typescript\nimport { E2B, AuthenticationError, TimeoutError } from 'e2b'\n\ntry {\n const sandbox = await client.createSandbox({ template: 'base' })\n await sandbox.filesystem.read('/app/data.json')\n} catch (error) {\n if (error instanceof AuthenticationError) {\n console.error('Please check your API key')\n } else if (error instanceof TimeoutError) {\n console.error('Operation timed out')\n } else {\n throw error\n }\n}\n```\n\n## API Client Configuration\n\nThe connection configuration allows customization of the API client behavior, including custom base URLs, headers, and authentication. 资料来源：[packages/js-sdk/src/connectionConfig.ts]()\n\n### Configuration Options\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `apiKey` | `string` | E2B API key |\n| `baseUrl` | `string` | Custom API base URL |\n| `timeout` | `number` | Default request timeout |\n| `headers` | `Record` | Custom HTTP headers |\n\n### Custom Configuration Example\n\n```typescript\nimport { E2B } from 'e2b'\n\nconst client = new E2B({\n apiKey: process.env.E2B_API_KEY,\n baseUrl: 'https://api.e2b.dev/v1',\n timeout: 30000\n})\n```\n\n## Build Configuration\n\nThe SDK is built using tsup, a TypeScript bundler that produces optimized output for both ESM and CommonJS formats. 资料来源：[packages/js-sdk/tsup.config.js]()\n\n### Build Output Configuration\n\n```javascript\nexport default defineConfig({\n minify: false,\n target: ['es2017'],\n sourcemap: true,\n dts: true,\n format: ['esm', 'cjs'],\n clean: true,\n entry: {\n index: './src/index.ts',\n },\n esbuildOptions: (options) => {\n options.legalComments = 'none'\n return options\n },\n})\n```\n\n### Supported Platforms\n\n| Platform | Format | Target |\n|----------|--------|--------|\n| Node.js | CommonJS | `node18` |\n| Browser | ESM | `es2017` |\n\n## API Reference\n\n### E2B Client\n\n```typescript\nclass E2B {\n constructor(config?: ConnectionConfig)\n \n // Sandboxes\n sandboxes: Sandboxes\n \n // Volumes\n volumes: Volumes\n \n // Templates\n templates: Templates\n \n // Close the client\n close(): void\n}\n```\n\n### Sandbox Instance\n\n```typescript\nclass Sandbox {\n id: string\n url: string\n startedAt: Date\n \n // Properties\n filesystem: Filesystem\n commands: Commands\n network: Network\n \n // Methods\n kill(): Promise\n restart(): Promise\n}\n```\n\n## Best Practices\n\n### Resource Management\n\nAlways properly terminate sandboxes when they are no longer needed to avoid unnecessary resource consumption and costs:\n\n```typescript\n// Recommended pattern with try/finally\nconst sandbox = await client.createSandbox({ template: 'base' })\ntry {\n // Perform operations\n} finally {\n await sandbox.kill()\n}\n```\n\n### Error Handling\n\nImplement comprehensive error handling to gracefully manage API failures, timeouts, and sandbox errors:\n\n```typescript\nasync function withSandbox(\n fn: (sandbox: Sandbox) => Promise\n): Promise {\n const sandbox = await client.createSandbox({ template: 'base' })\n try {\n return await fn(sandbox)\n } catch (error) {\n if (error instanceof RateLimitError) {\n await new Promise(r => setTimeout(r, 1000))\n return withSandbox(fn)\n }\n throw error\n } finally {\n await sandbox.kill()\n }\n}\n```\n\n### Timeout Configuration\n\nSet appropriate timeouts for long-running operations:\n\n```typescript\nconst sandbox = await client.createSandbox({\n template: 'base',\n timeout: 60000 // 60 seconds\n})\n```\n\n## Dependencies\n\nThe SDK relies on several key dependencies for its functionality:\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `@connectrpc/connect` | `2.0.0-rc.3` | RPC communication |\n| `@connectrpc/connect-web` | `2.0.0-rc.3` | Web RPC transport |\n| `openapi-fetch` | `0.14.1` | REST API client |\n| `platform` | `1.3.6` | Runtime detection |\n| `chalk` | `5.3.0` | Terminal styling |\n| `tar` | `7.5.11` | Archive handling |\n\n## CLI Integration\n\nThe SDK also integrates with the E2B CLI for template management. Template commands allow building, creating, and migrating sandbox templates across different languages. 资料来源：[packages/cli/src/commands/template/build.ts]()\n资料来源：[packages/cli/src/commands/template/init.ts]()\n\n## Related Documentation\n\nFor more information, refer to:\n\n- [Python SDK](../python-sdk/README.md) - Python client library\n- [CLI Documentation](./cli) - Command-line interface\n- [API Reference](./api) - REST API documentation\n- [Template Development](./templates) - Creating custom templates\n\n---\n\n\n\n## Python SDK\n\n### 相关页面\n\n相关主题：[JavaScript/TypeScript SDK](#js-sdk), [CLI Tool](#cli-tool), [Sandbox Usage](#sandbox-usage)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/python-sdk/e2b/__init__.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/__init__.py)\n- [packages/python-sdk/e2b/sandbox/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox/main.py)\n- [packages/python-sdk/e2b/sandbox_async/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_async/main.py)\n- [packages/python-sdk/e2b/sandbox_sync/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_sync/main.py)\n- [packages/python-sdk/e2b/sandbox/sandbox_api.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox/sandbox_api.py)\n- [packages/python-sdk/e2b/sandbox_async/sandbox_api.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_async/sandbox_api.py)\n- [packages/python-sdk/e2b/sandbox_sync/sandbox_api.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_sync/sandbox_api.py)\n- [packages/python-sdk/e2b/envd/api.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/envd/api.py)\n- [packages/python-sdk/e2b/exceptions.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/exceptions.py)\n- [packages/python-sdk/e2b/api/client/client.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/api/client/client.py)\n \n\n# Python SDK\n\nThe E2B Python SDK provides a programmatic interface for creating and managing secure cloud sandboxes that execute AI-generated code in isolated environments. The SDK enables developers to spawn sandbox instances, execute shell commands, manage filesystem operations, and build reusable sandbox templates.\n\n## Overview\n\nE2B (Execution-to-Brain) is an open-source infrastructure platform that allows developers to run AI-generated code in secure, isolated sandboxes hosted in the cloud. The Python SDK serves as the primary client library for Python developers to interact with the E2B infrastructure.\n\n**Key capabilities:**\n\n- Create and manage sandboxed execution environments\n- Execute arbitrary shell commands within sandboxes\n- Build and deploy custom sandbox templates\n- Access filesystem operations (upload, download, file management)\n- Configure sandbox resources (CPU, memory)\n- Support for both synchronous and asynchronous programming patterns\n\n**Package information:**\n\n```python\n# SDK metadata captured from package\npackage_version = metadata.version(\"e2b\")\n\ndefault_headers = {\n \"lang\": \"python\",\n \"lang_version\": platform.python_version(),\n \"package_version\": metadata.version(\"e2b\"),\n \"publisher\": \"e2b\",\n \"sdk_runtime\": \"python\",\n \"system\": platform.system(),\n}\n```\n\n资料来源：[e2b/api/metadata.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/api/metadata.py)\n\n## Installation and Setup\n\n### Install the SDK\n\n```bash\npip install e2b\n```\n\n### Configure API Credentials\n\nObtain your API key from the [E2B Dashboard](https://e2b.dev/dashboard?tab=keys) and set it as an environment variable:\n\n```bash\nexport E2B_API_KEY=e2b_***\n```\n\n### Quick Start Example\n\n```python\nfrom e2b import Sandbox\n\nwith Sandbox.create() as sandbox:\n result = sandbox.commands.run('echo \"Hello from E2B!\"')\n print(result.stdout) # Hello from E2B!\n```\n\n## Architecture\n\nThe Python SDK is structured around several key modules that provide different functionality layers.\n\n```mermaid\ngraph TD\n A[User Code] --> B[Python SDK]\n B --> C[Sandbox API Client]\n B --> D[Template API Client]\n C --> E[E2B Backend API]\n D --> E\n E --> F[Sandbox Instances]\n E --> G[Template Registry]\n F --> H[envd Runtime]\n H --> I[Isolated Execution Environment]\n```\n\n### Module Structure\n\n| Module | Purpose |\n|--------|---------|\n| `e2b.sandbox` | Core sandbox functionality |\n| `e2b.sandbox_async` | Async sandbox implementation |\n| `e2b.sandbox_sync` | Synchronous sandbox implementation |\n| `e2b.template` | Template builder functionality |\n| `e2b.envd` | Environment daemon API |\n| `e2b.api` | HTTP API client layer |\n| `e2b.exceptions` | Custom exception types |\n\n## Sandbox Class\n\nThe `Sandbox` class is the primary entry point for creating and interacting with sandboxed execution environments. The SDK provides both context manager support and manual lifecycle management.\n\n### Creating a Sandbox\n\n```python\nfrom e2b import Sandbox\n\n# Using context manager (recommended)\nwith Sandbox.create() as sandbox:\n result = sandbox.commands.run('echo \"Hello\"')\n print(result.stdout)\n```\n\n### Sandbox Lifecycle\n\n```mermaid\nstateDiagram-v2\n [*] --> Created: Sandbox.create()\n Created --> Running: __enter__()\n Running --> Stopped: __exit__() / close()\n Stopped --> [*]\n Created --> Stopped: close()\n```\n\n### Key Sandbox Methods\n\n| Method | Description |\n|--------|-------------|\n| `Sandbox.create()` | Static factory method to create a new sandbox instance |\n| `sandbox.close()` | Manually terminate the sandbox |\n| `sandbox.commands.run(cmd)` | Execute a shell command |\n| `sandbox.filesystem` | Access filesystem operations |\n| `sandbox.upload(src, dest)` | Upload files to sandbox |\n| `sandbox.download(src, dest)` | Download files from sandbox |\n\n资料来源：[e2b/sandbox/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox/main.py)\n\n## Synchronous vs Asynchronous APIs\n\nThe Python SDK provides both synchronous and asynchronous interfaces to accommodate different programming patterns.\n\n### Synchronous API\n\n```python\nfrom e2b.sandbox_sync import Sandbox\n\nsandbox = Sandbox.create()\nresult = sandbox.commands.run('echo \"sync\"')\nsandbox.close()\n```\n\nThe synchronous API uses blocking I/O operations and is suitable for scripts and applications where concurrency is not a primary concern.\n\n### Asynchronous API\n\n```python\nimport asyncio\nfrom e2b.sandbox_async import Sandbox\n\nasync def main():\n async with Sandbox.create() as sandbox:\n result = await sandbox.commands.run('echo \"async\"')\n print(result.stdout)\n\nasyncio.run(main())\n```\n\nThe async API is designed for web applications, async frameworks, and scenarios requiring concurrent sandbox operations.\n\n| Feature | Sync API | Async API |\n|---------|----------|-----------|\n| Import | `from e2b import Sandbox` | `from e2b.sandbox_async import Sandbox` |\n| I/O Model | Blocking | Non-blocking |\n| Use Case | Scripts, CLI tools | Web servers, async frameworks |\n| Connection | `e2b.sandbox_sync.sandbox_api` | `e2b.sandbox_async.sandbox_api` |\n\n资料来源：[e2b/sandbox_sync/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_sync/main.py)，[e2b/sandbox_async/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_async/main.py)\n\n## Template Builder\n\nTemplates define the base image and configuration for sandbox environments. The Template Builder API allows programmatic creation of custom sandbox templates.\n\n### Creating a Template\n\n```python\nfrom e2b import Template\n\ntemplate = (\n Template()\n .from_python_image('3')\n .copy('requirements.txt', '/home/user/')\n .run_cmd('pip install -r /home/user/requirements.txt')\n)\n\n# Build and deploy\nTemplate.build(template, 'my-python-env:v1.0')\n```\n\n### Available Base Images\n\n| Method | Base Image |\n|--------|------------|\n| `fromPythonImage(version)` | Python Docker image |\n| `fromNodeImage(variant)` | Node.js Docker image |\n| `fromBunImage(variant)` | Bun Docker image |\n| `fromDebianImage(variant)` | Debian Docker image |\n| `fromUbuntuImage(variant)` | Ubuntu Docker image |\n| `fromTemplate(name)` | E2B template |\n| `fromDockerfile(content)` | Custom Dockerfile |\n\n### Template Builder Methods\n\n| Method | Description |\n|--------|-------------|\n| `run_cmd(cmd, user)` | Execute a shell command during build |\n| `copy(src, dest)` | Copy files into the template |\n| `apt_install(packages)` | Install system packages |\n| `bun_install(packages)` | Install npm/bun packages |\n| `set_envs(envs)` | Set environment variables |\n| `set_start_cmd(cmd, ready_cmd)` | Configure startup command |\n| `skip_cache()` | Force rebuild ignoring cache |\n\n资料来源：[e2b/template/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template/main.py)\n\n### Async Template Operations\n\n```python\nfrom e2b import AsyncTemplate\n\ntemplate = (\n AsyncTemplate()\n .from_python_image('3')\n .run_cmd('pip install numpy')\n)\n\n# Build with progress callback\nasync def on_logs(log):\n print(log.message)\n\nawait AsyncTemplate.build(\n template, \n 'my-template:v1.0',\n on_build_logs=on_logs\n)\n```\n\n## Connection Configuration\n\nThe SDK uses `ConnectionConfig` to manage API connection parameters including authentication, endpoints, and timeouts.\n\n### Configuration Parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `api_key` | str | `E2B_API_KEY` env | API authentication key |\n| `access_token` | str | `E2B_ACCESS_TOKEN` env | Alternative auth token |\n| `base_url` | str | E2B API | Custom API endpoint |\n| `timeout` | int | 60 | Request timeout in seconds |\n\n### Custom Configuration\n\n```python\nfrom e2b import Sandbox\nfrom e2b.constants import ConnectionConfig\n\nconfig = ConnectionConfig(\n api_key='e2b_***',\n timeout=120\n)\n\nwith Sandbox.create(**config) as sandbox:\n result = sandbox.commands.run('echo \"configured\"')\n```\n\n## Command Execution\n\n### Running Commands\n\n```python\nsandbox = Sandbox.create()\n\n# Basic command\nresult = sandbox.commands.run('ls -la')\n\n# With working directory\nresult = sandbox.commands.run('pwd', cwd='/home/user')\n\n# With timeout\nresult = sandbox.commands.run('sleep 10', timeout=5)\n```\n\n### Command Result Properties\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `stdout` | str | Standard output |\n| `stderr` | str | Standard error |\n| `exit_code` | int | Process exit code |\n| `stdout_lines` | List[str] | Output as line array |\n\n## Error Handling\n\nThe SDK defines custom exception types for different error scenarios.\n\n### Exception Types\n\n| Exception | Description |\n|-----------|-------------|\n| `SandboxException` | Base exception for sandbox errors |\n| `AuthenticationException` | API key/authentication failures |\n| `TimeoutException` | Operation timeout exceeded |\n| `NotFoundException` | Resource not found |\n| `RateLimitException` | API rate limit exceeded |\n\n### Handling Errors\n\n```python\nfrom e2b import Sandbox\nfrom e2b.exceptions import TimeoutException, SandboxException\n\ntry:\n sandbox = Sandbox.create(timeout=30)\n result = sandbox.commands.run('long-running-command', timeout=5)\nexcept TimeoutException:\n print(\"Command timed out\")\nexcept SandboxException as e:\n print(f\"Sandbox error: {e}\")\nfinally:\n sandbox.close()\n```\n\n资料来源：[e2b/exceptions.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/exceptions.py)\n\n## envd API\n\nThe `envd` module provides access to the environment daemon running inside each sandbox, enabling advanced operations and introspection.\n\n### Available Operations\n\n```python\nsandbox = Sandbox.create()\n\n# Get environment info\ninfo = sandbox.envd.info()\n\n# Check service status\nstatus = sandbox.envd.is_process_running('nginx')\n\n# Wait for port to be ready\nsandbox.envd.wait_for_port(3000)\n```\n\n资料来源：[e2b/envd/api.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/envd/api.py)\n\n## API Client Layer\n\nThe HTTP API client handles low-level communication with the E2B backend.\n\n```mermaid\ngraph LR\n A[SDK Classes] --> B[SandboxAPI Client]\n B --> C[HTTP Requests]\n C --> D[E2B REST API]\n D --> E[Response Handling]\n E --> F[SDK Data Models]\n```\n\n### Client Configuration\n\n```python\nfrom e2b.api.client.client import APIClient\n\nclient = APIClient(\n base_url=\"https://api.e2b.dev\",\n timeout=60,\n headers={\n \"X-Custom-Header\": \"value\"\n }\n)\n```\n\n资料来源：[e2b/api/client/client.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/api/client/client.py)\n\n## Complete Usage Example\n\n```python\nfrom e2b import Sandbox, Template\n\n# Create and configure a template\ntemplate = (\n Template()\n .from_python_image('3.11')\n .apt_install(['git', 'curl'])\n .run_cmd('pip install fastapi uvicorn')\n .set_envs({'APP_ENV': 'production'})\n .set_start_cmd('uvicorn main:app', 'curl http://localhost:8000/health')\n)\n\n# Build template (run once)\nTemplate.build(template, 'my-fastapi:v1.0')\n\n# Use the template in sandboxes\nwith Sandbox.create(template='my-fastapi:v1.0') as sandbox:\n # Upload application code\n sandbox.upload('./app', '/home/user/app')\n \n # Run a command\n result = sandbox.commands.run('cd /home/user/app && python main.py')\n print(result.stdout)\n```\n\n## See Also\n\n- [JavaScript SDK](../js-sdk) - TypeScript/JavaScript implementation\n- [CLI](../cli) - Command-line interface\n- [Code Interpreter](https://github.com/e2b-dev/code-interpreter) - Code execution SDK\n- [E2B Documentation](https://e2b.dev/docs) - Official documentation\n- [Cookbook](https://github.com/e2b-dev/e2b-cookbook) - Usage examples\n\n---\n\n\n\n## CLI Tool\n\n### 相关页面\n\n相关主题：[JavaScript/TypeScript SDK](#js-sdk), [Python SDK](#python-sdk), [Template System](#template-system)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/cli/README.md](https://github.com/e2b-dev/E2B/blob/main/packages/cli/README.md)\n- [packages/cli/src/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/index.ts)\n- [packages/cli/src/commands/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/index.ts)\n- [packages/cli/src/commands/auth/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/auth/index.ts)\n- [packages/cli/src/commands/sandbox/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/sandbox/index.ts)\n- [packages/cli/src/commands/template/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/template/index.ts)\n- [packages/cli/src/commands/template/create.ts](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/template/create.ts)\n- [packages/cli/src/commands/template/build.ts](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/template/build.ts)\n \n\n# CLI Tool\n\nThe E2B CLI (Command Line Interface) is a Node.js-based command-line tool that enables developers to build, manage, and interact with E2B sandbox templates and running sandboxes directly from the terminal. It provides a unified interface for authentication, template management, and sandbox operations without requiring direct API integration.\n\n## Overview\n\nThe E2B CLI serves as the primary management interface for E2B infrastructure. It allows users to authenticate with the E2B platform, create and build sandbox templates, manage running sandboxes, and configure their development environment for AI-generated code execution.\n\n**Key capabilities include:**\n\n- User authentication and token management\n- Sandbox template creation and building\n- Running sandbox lifecycle management\n- Support for multiple package managers and base images\n- Environment variable configuration during build\n- Dockerfile integration for custom sandbox definitions\n\n资料来源：[packages/cli/README.md:1-20]()\n\n## Installation\n\n### System Requirements\n\n| Requirement | Version/Details |\n|------------|-----------------|\n| Node.js | v14.0.0 or higher |\n| npm | v6.0.0 or higher |\n| Operating System | macOS, Linux, Windows |\n\n### Installation Methods\n\n#### Using Homebrew (macOS/Linux)\n\n```bash\nbrew install e2b\n```\n\n#### Using NPM\n\n```bash\nnpm install -g @e2b/cli\n```\n\n资料来源：[packages/cli/README.md:13-20]()\n\n## Authentication\n\nBefore using the CLI, you must authenticate with your E2B account. The CLI supports two authentication methods.\n\n### Interactive Login\n\n```bash\ne2b auth login\n```\n\nThis command opens a browser window for the user to complete the OAuth authentication flow.\n\n### Token-Based Authentication\n\nFor non-interactive environments (CI/CD pipelines, remote servers), provide the access token directly:\n\n```bash\nE2B_ACCESS_TOKEN=sk_e2b_... e2b template build\n```\n\n**Important:** Note the distinction between `E2B_ACCESS_TOKEN` and `E2B_API_KEY`. The CLI uses `E2B_ACCESS_TOKEN`, which can be found in Account Settings under the Team selector at [e2b.dev/dashboard](https://e2b.dev/dashboard).\n\n资料来源：[packages/cli/README.md:22-32]()\n\n## Command Structure\n\nThe CLI organizes commands hierarchically under the `e2b` namespace:\n\n```mermaid\ngraph TD\n A[e2b] --> B[auth]\n A --> C[template]\n A --> D[sandbox]\n \n B --> B1[login]\n \n C --> C1[create]\n C --> C2[build]\n C --> C3[list]\n C --> C4[delete]\n \n D --> D1[start]\n D --> D2[stop]\n D --> D3[list]\n D --> D4[logs]\n```\n\n### Global Flags\n\n| Flag | Description | Example |\n|------|-------------|---------|\n| `--help, -h` | Display help information | `e2b --help` |\n| `--version, -v` | Display CLI version | `e2b --version` |\n| `--debug` | Enable debug output | `e2b --debug template build` |\n\n## Template Commands\n\nTemplates define the sandbox environment including base images, installed packages, environment variables, and startup commands.\n\n### Template Create\n\nCreates a new sandbox template from a directory containing a `e2b.toml` configuration file or a Dockerfile.\n\n```bash\ne2b template create \n```\n\n**Example workflow:**\n\n```bash\n# Navigate to your template directory\ncd my-sandbox-template\n\n# Create the template\ne2b template create my-python-env\n```\n\nThe command reads the template configuration, builds the Docker image, and uploads it to E2B infrastructure.\n\n资料来源：[packages/cli/src/commands/template/create.ts:1-20]()\n\n### Template Build\n\nBuilds a sandbox template and uploads it to E2B infrastructure.\n\n```bash\ne2b template build [options]\n```\n\n**Options:**\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `--alias, -a` | Template alias/name | Required |\n| `--tag` | Additional tags for the build | None |\n| `--file, -f` | Path to Dockerfile | `./Dockerfile` |\n| `--timeout` | Build timeout in seconds | 600 |\n\n**Build Process Flow:**\n\n```mermaid\ngraph LR\n A[Start Build] --> B{Config File?}\n B -->|Dockerfile| C[Load Dockerfile]\n B -->|e2b.toml| D[Parse Configuration]\n C --> E[Build Docker Image]\n D --> F[Generate Dockerfile]\n E --> G[Upload to Registry]\n F --> E\n G --> H[Create Template]\n H --> I[Build Complete]\n```\n\n**Example usage:**\n\n```bash\n# Build with auto-generated name\ne2b template build --alias my-template\n\n# Build with custom Dockerfile\ne2b template build --alias my-template --file ./custom.Dockerfile\n\n# Build with tags\ne2b template build --alias my-template --tag v1.0 --tag stable\n```\n\n资料来源：[packages/cli/src/commands/template/build.ts:1-50]()\n\n### Template Configuration\n\nTemplates can be configured using either a `e2b.toml` file or a `Dockerfile`.\n\n#### Using e2b.toml\n\n```toml\nname = \"my-template\"\nruntime = \"dockerfile\"\n\n[env]\nNODE_ENV = \"production\"\n\n[start]\ncommand = \"npm start\"\nready = \"curl http://localhost:3000/health\"\n```\n\n#### Using Dockerfile\n\nThe CLI automatically detects and uses a `Dockerfile` in the template directory:\n\n```dockerfile\nFROM python:3.11-slim\n\nRUN pip install numpy pandas flask\n\nENV PORT=8080\n\nENTRYPOINT [\"python\", \"app.py\"]\n```\n\nThe CLI loads the Dockerfile content using the `getDockerfile()` function:\n\n```typescript\nfunction getDockerfile(root: string, file?: string) {\n // Check if user specified custom Dockerfile exists\n if (file) {\n const dockerfilePath = path.join(root, file)\n const dockerfileContent = loadFile(dockerfilePath)\n const dockerfileRelativePath = path.relative(root, dockerfilePath)\n \n // Returns { dockerfilePath, dockerfileContent, dockerfileRelativePath }\n }\n}\n```\n\n资料来源：[packages/cli/src/commands/template/build.ts:80-100]()\n\n### Template Build Output\n\nUpon successful build completion, the CLI displays:\n\n```\n✅ Building sandbox template finished.\n\nExample usage:\n\nPython SDK\n from e2b import Sandbox\n sandbox = Sandbox.create(template=\"\")\n result = sandbox.commands.run('echo \"Hello from E2B!\"')\n\nJS SDK\n import Sandbox from 'e2b'\n const sandbox = await Sandbox.create({ template: '' })\n const result = await sandbox.commands.run('echo \"Hello from E2B!\"')\n```\n\n资料来源：[packages/cli/src/commands/template/build.ts:35-45]()\n\n### Error Handling\n\nBuild errors are reported with detailed context:\n\n```\n❌ Building sandbox template failed.\nCheck the logs above for more details or contact us (https://e2b.dev/docs/support) to get help.\n```\n\n资料来源：[packages/cli/src/commands/template/build.ts:50-58]()\n\n## Sandbox Commands\n\nSandbox commands allow you to manage running sandbox instances.\n\n### Available Sandbox Operations\n\n| Command | Description |\n|---------|-------------|\n| `e2b sandbox start` | Start a new sandbox instance |\n| `e2b sandbox stop` | Stop a running sandbox |\n| `e2b sandbox list` | List all running sandboxes |\n| `e2b sandbox logs` | View sandbox logs |\n\n### Sandbox Lifecycle\n\n```mermaid\ngraph TD\n A[Create Sandbox] --> B[Initialize]\n B --> C[Run Ready Command]\n C --> D{Ready?}\n D -->|Yes| E[Sandbox Active]\n D -->|No| F[Retry/Timeout]\n E --> G[Execute Commands]\n G --> H[Stop Sandbox]\n H --> I[Cleanup]\n```\n\n资料来源：[packages/cli/src/commands/sandbox/index.ts:1-30]()\n\n## Environment Variables\n\n### CLI Environment Variables\n\n| Variable | Description | Required |\n|----------|-------------|----------|\n| `E2B_ACCESS_TOKEN` | CLI authentication token | Yes (non-interactive) |\n| `E2B_API_KEY` | API key for SDK operations | For SDK usage |\n\n### Template Environment Variables\n\nDuring template build, environment variables can be set in the configuration:\n\n```toml\n[env]\nNODE_ENV = \"production\"\nPORT = \"8080\"\nDATABASE_URL = \"postgres://...\"\n```\n\n资料来源：[packages/cli/README.md:28-30]()\n\n## Architecture\n\n### CLI Entry Point\n\nThe CLI entry point at `packages/cli/src/index.ts` initializes the command infrastructure and registers all available commands:\n\n```typescript\n// Main CLI entry point\n// Registers: auth, template, sandbox commands\n// Handles global flags and configuration\n```\n\n### Command Registration\n\nCommands are registered in `packages/cli/src/commands/index.ts` which serves as the command router:\n\n```mermaid\ngraph TD\n A[index.ts] --> B[commands/index.ts]\n B --> C[auth/index.ts]\n B --> D[template/index.ts]\n B --> E[sandbox/index.ts]\n \n D --> D1[create.ts]\n D --> D2[build.ts]\n \n C --> C1[login.ts]\n C --> C2[logout.ts]\n```\n\n### Build System\n\nThe CLI is built using [tsup](https://github.com/egoist/tsup), a TypeScript bundler built on top of esbuild. The build configuration in `tsup.config.js` handles:\n\n- TypeScript compilation\n- Module resolution\n- Output format (CJS/ESM)\n- External dependencies\n\n```javascript\n// packages/cli/tsup.config.js\n// Configures CLI bundling for distribution\n```\n\n## Integration with SDKs\n\nThe CLI works in conjunction with the JavaScript and Python SDKs:\n\n```mermaid\ngraph LR\n A[CLI] --> B[Manage Templates]\n A --> C[Authenticate]\n \n D[JS SDK/Python SDK] --> E[Sandbox Runtime]\n E --> F[Execute Code]\n \n B --> G[E2B Cloud]\n C --> G\n```\n\n### Template Usage with SDKs\n\nAfter building a template with the CLI, use it with the SDKs:\n\n**Python SDK:**\n\n```python\nfrom e2b import Sandbox\n\nsandbox = Sandbox.create(template=\"my-template\")\nresult = sandbox.commands.run('echo \"Hello from E2B!\"')\nprint(result.stdout)\n```\n\n**JavaScript SDK:**\n\n```typescript\nimport Sandbox from 'e2b'\n\nconst sandbox = await Sandbox.create({ template: 'my-template' })\nconst result = await sandbox.commands.run('echo \"Hello from E2B!\"')\nconsole.log(result.stdout)\n```\n\n资料来源：[packages/cli/src/commands/template/create.ts:5-15]()\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Solution |\n|-------|----------|\n| Authentication failed | Ensure `E2B_ACCESS_TOKEN` is valid and not expired |\n| Build timeout | Increase timeout with `--timeout` flag or optimize Dockerfile |\n| Dockerfile not found | Verify the file exists or specify path with `--file` flag |\n| Permission denied | Ensure npm global install permissions are correct |\n\n### Debug Mode\n\nEnable debug output for detailed logging:\n\n```bash\ne2b --debug template build --alias my-template\n```\n\n### Getting Help\n\n```bash\n# General help\ne2b --help\n\n# Command-specific help\ne2b template --help\ne2b template build --help\ne2b sandbox --help\n```\n\n## See Also\n\n- [E2B Documentation](https://e2b.dev/docs)\n- [JavaScript SDK](../js-sdk/README.md)\n- [Python SDK](../python-sdk/README.md)\n- [E2B Cookbook](https://github.com/e2b-dev/e2b-cookbook)\n\n---\n\n\n\n## Sandbox Management\n\n### 相关页面\n\n相关主题：[Sandbox Usage](#sandbox-usage), [Network Configuration](#network-config)\n\n\nRelevant Source Files
\n\nThe following source files were used to generate this documentation page:\n\n- [packages/js-sdk/src/sandbox/sandboxApi.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/sandboxApi.ts)\n- [packages/js-sdk/src/sandbox/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/index.ts)\n- [packages/python-sdk/e2b/sandbox_async/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_async/main.py)\n- [packages/python-sdk/e2b/sandbox_sync/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_sync/main.py)\n- [packages/python-sdk/e2b/sandbox_async/sandbox_api.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_async/sandbox_api.py)\n- [packages/cli/src/commands/sandbox/info.ts](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/sandbox/info.ts)\n- [packages/cli/src/commands/template/create.ts](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/template/create.ts)\n- [packages/cli/src/commands/template/build.ts](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/template/build.ts)\n \n\n# Sandbox Management\n\n## Overview\n\nSandbox Management is the core system in E2B that enables the creation, control, and lifecycle management of secure, isolated cloud environments for running AI-generated code. Sandboxes provide ephemeral compute instances that can be spawned on-demand, configured with specific templates, and terminated when no longer needed.\n\nThe sandbox system abstracts away infrastructure complexity, allowing developers to work with a simple high-level API while E2B handles container orchestration, network isolation, and resource allocation behind the scenes.\n\n资料来源：[packages/js-sdk/src/sandbox/sandboxApi.ts:1-50]()\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n A[Developer Application] --> B[SDK Client]\n B --> C[Sandbox API]\n C --> D[E2B Infrastructure]\n D --> E[Isolated Sandbox Container]\n \n F[Template Definition] --> C\n G[CLI Commands] --> C\n \n H[Sandbox Instance] --> I[Commands Execution]\n H --> J[File System Access]\n H --> K[Network Resources]\n```\n\nThe architecture consists of three primary layers:\n\n| Layer | Description | Components |\n|-------|-------------|------------|\n| **Client SDK** | High-level language bindings | JavaScript SDK, Python SDK |\n| **API Gateway** | REST API for sandbox operations | Template management, sandbox lifecycle |\n| **Infrastructure** | Container orchestration | Docker containers, isolated networking |\n\n资料来源：[packages/js-sdk/src/sandbox/index.ts:1-60]()\n\n## Sandbox Lifecycle\n\nSandboxes follow a well-defined state machine with transitions controlled by the platform.\n\n```mermaid\nstateDiagram-v2\n [*] --> Starting\n Starting --> Running : API returns sandbox info\n Running --> Paused : Pause request\n Running --> Stopped : Timeout or kill\n Paused --> Running : Resume request\n Paused --> Stopped : Kill\n Stopped --> [*]\n \n Running --> Error : Infrastructure failure\n Error --> [*]\n```\n\n### Lifecycle Configuration\n\nThe sandbox lifecycle behavior can be configured at creation time:\n\n```python\nlifecycle = {\n \"on_timeout\": \"pause\", # \"kill\" (default) or \"pause\"\n \"auto_resume\": True # Only when on_timeout=\"pause\"\n}\n```\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `on_timeout` | `str` | `\"kill\"` | Action when sandbox timeout is reached |\n| `auto_resume` | `bool` | `False` | Whether to auto-resume paused sandbox |\n\n资料来源：[packages/js-sdk/src/sandbox/sandboxApi.ts:60-80]()\n\n## Creating a Sandbox\n\n### JavaScript SDK\n\nThe JavaScript SDK provides both stable and beta creation methods.\n\n**Stable Creation:**\n\n```typescript\nimport Sandbox from 'e2b'\n\nconst sandbox = await Sandbox.create('my-template', {\n timeoutMs: 60000,\n metadata: { userId: '123' },\n envs: { NODE_ENV: 'production' }\n})\n```\n\n**Beta Creation (with MCP support):**\n\n```typescript\nconst sandbox = await Sandbox.betaCreate('my-template', {\n mcp: { servers: ['exa', 'firecrawl'] }\n})\n```\n\nThe SDK automatically handles:\n- Template resolution (defaults to `base` or `mcp-gateway`)\n- Connection configuration\n- Debug mode fallback\n\n资料来源：[packages/js-sdk/src/sandbox/index.ts:60-120]()\n\n### Python SDK\n\n**Async Sandbox:**\n\n```python\nfrom e2b import AsyncSandbox\n\nasync with await AsyncSandbox.create(\n template='my-template',\n timeout=60_000,\n metadata={'userId': '123'},\n envs={'PYTHON_ENV': 'production'}\n) as sandbox:\n result = await sandbox.commands.run('echo \"Hello\"')\n```\n\n**Sync Sandbox:**\n\n```python\nfrom e2b import Sandbox\n\nwith Sandbox.create(\n template='my-template',\n timeout=60_000\n) as sandbox:\n result = sandbox.commands.run('echo \"Hello\"')\n```\n\n资料来源：[packages/python-sdk/e2b/sandbox_async/main.py:1-80]()\n资料来源：[packages/python-sdk/e2b/sandbox_sync/main.py:1-70]()\n\n## Sandbox Options and Configuration\n\n### Core Options\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `template` | `string` | No | `\"base\"` | Sandbox template name or ID |\n| `timeoutMs` | `number` | No | Varies by plan | Maximum sandbox lifetime in milliseconds |\n| `metadata` | `Record` | No | `{}` | Custom metadata for the sandbox |\n| `envs` | `Record` | No | `{}` | Environment variables |\n| `mcp` | `MCPConfig` | No | - | MCP server configuration |\n| `network` | `boolean` | No | `true` | Network isolation setting |\n| `allowInternetAccess` | `boolean` | No | `true` | Internet access in sandbox |\n\n### Resource Configuration\n\n```typescript\nconst sandbox = await Sandbox.create('my-template', {\n // CPU and memory can be specified via CLI\n // SDK uses template defaults\n})\n```\n\n**CLI Resource Options:**\n\n| Flag | Default | Description |\n|------|---------|-------------|\n| `--cpu-count` | `2` | Number of vCPUs |\n| `--memory-mb` | `512` | RAM in megabytes (must be even) |\n\n资料来源：[packages/js-sdk/src/sandbox/sandboxApi.ts:80-150]()\n资料来源：[packages/cli/src/commands/template/create.ts:40-80]()\n\n## Volume Mounts\n\nSandboxes support attaching persistent volumes for data storage across sessions.\n\n```python\nfrom e2b import AsyncSandbox, AsyncVolume\n\nvolume = await AsyncVolume.create('my-data-volume')\n\nasync with AsyncSandbox.create(\n volume_mounts={\n '/data': volume\n }\n) as sandbox:\n # Files in /data persist across sandbox instances\n await sandbox.commands.run('echo \"data\" > /data/file.txt')\n```\n\nVolume mount transformation:\n\n```python\ntransformed_mounts = [\n SandboxVolumeMountAPI(\n name=vol.name if isinstance(vol, AsyncVolume) else vol,\n path=path,\n )\n for path, vol in volume_mounts.items()\n]\n```\n\n资料来源：[packages/python-sdk/e2b/sandbox_async/main.py:30-60]()\n\n## Sandbox API Methods\n\n### Creation Response\n\nWhen a sandbox is created, the API returns a response containing connection details:\n\n```python\nSandboxCreateResponse(\n sandbox_id=\"sbox_xxxxx\",\n sandbox_domain=\"sbox-xxxxx.e2b.dev\",\n envd_version=\"0.1.0\",\n envd_access_token=\"token_xxxxx\",\n traffic_access_token=\"traffic_xxxxx\"\n)\n```\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `sandbox_id` | `string` | Unique sandbox identifier |\n| `sandbox_domain` | `string` or `null` | Public domain for the sandbox |\n| `envd_version` | `string` | Version of the envd agent |\n| `envd_access_token` | `string` or `null` | Token for envd authentication |\n| `traffic_access_token` | `string` or `null` | Token for traffic encryption |\n\n### Version Compatibility Check\n\nThe SDK validates that the template's envd version meets minimum requirements:\n\n```python\nif Version(res.parsed.envd_version) < Version(\"0.1.0\"):\n await SandboxApi._cls_kill(res.parsed.sandbox_id)\n raise TemplateException(\n \"You need to update the template to use the new SDK. \"\n \"You can do this by running `e2b template build`\"\n )\n```\n\n资料来源：[packages/python-sdk/e2b/sandbox_async/sandbox_api.py:50-80]()\n\n## CLI Sandbox Management\n\n### Viewing Sandbox Information\n\n```bash\ne2b sandbox info \n```\n\n**Output Fields:**\n\n| Field | Label | Description |\n|-------|-------|-------------|\n| `sandboxId` | Sandbox ID | Unique identifier |\n| `templateId` | Template ID | Template used |\n| `name` | Alias | User-assigned name |\n| `state` | State | Current sandbox state |\n| `startedAt` | Started at | Creation timestamp |\n| `endAt` | End at | Scheduled termination |\n| `cpuCount` | vCPUs | CPU allocation |\n| `memoryMB` | RAM MiB | Memory allocation |\n| `envdVersion` | Envd version | Agent version |\n| `allowInternetAccess` | Internet access | Network setting |\n| `lifecycle` | Lifecycle | Timeout behavior |\n| `network` | Network | Network configuration |\n| `sandboxDomain` | Sandbox domain | Public endpoint |\n| `metadata` | Metadata | Custom metadata |\n\n```bash\n# JSON output\ne2b sandbox info --format json\n\n# Pretty output (default)\ne2b sandbox info --format pretty\n```\n\n资料来源：[packages/cli/src/commands/sandbox/info.ts:1-60]()\n\n## Template-Based Sandbox Creation\n\nTemplates define the base environment for sandboxes. They can be built and managed via CLI.\n\n### Building Templates\n\n```bash\ne2b template build \n```\n\n**Options:**\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--path ` | `-p` | Template directory path |\n| `--dockerfile ` | `-d` | Custom Dockerfile name |\n| `--cmd ` | `-c` | Command executed on sandbox start |\n| `--ready-cmd ` | - | Command that must exit 0 for ready state |\n| `--cpu-count ` | - | vCPUs (default: 2) |\n| `--memory-mb ` | - | RAM in MB, even number (default: 512) |\n| `--no-cache` | - | Skip build cache |\n\n```bash\ne2b template build my-template \\\n --path ./templates/my-app \\\n --cmd \"python app.py\" \\\n --ready-cmd \"curl -f http://localhost:3000/health\" \\\n --cpu-count 4 \\\n --memory-mb 1024\n```\n\n### Template Validation\n\nTemplate names must follow strict naming conventions:\n\n```typescript\nif (!/^[a-z0-9-_]+$/.test(templateName)) {\n console.error(\n `Template name ${templateName} is not valid. ` +\n `Template name can only contain lowercase letters, numbers, dashes and underscores.`\n )\n}\n```\n\n资料来源：[packages/cli/src/commands/template/create.ts:50-90]()\n资料来源：[packages/cli/src/commands/template/build.ts:1-50]()\n\n## Debug Mode\n\nThe SDK supports a debug mode for local development:\n\n```typescript\nconst config = new ConnectionConfig(sandboxOpts)\nif (config.debug) {\n return new this({\n sandboxId: 'debug_sandbox_id',\n envdVersion: ENVD_DEBUG_FALLBACK,\n ...config,\n })\n}\n```\n\nIn debug mode, the sandbox uses a fallback environment instead of connecting to real infrastructure, enabling local testing of sandbox code without cloud resources.\n\n资料来源：[packages/js-sdk/src/sandbox/index.ts:80-100]()\n\n## Error Handling\n\n### Template Exceptions\n\nWhen a template is incompatible with the current SDK version:\n\n```python\nraise TemplateException(\n \"You need to update the template to use the new SDK. \"\n \"You can do this by running `e2b template build` in the directory with the template.\"\n)\n```\n\n### API Error Handling\n\n```python\nif res.status_code >= 300:\n raise handle_api_exception(res)\n\nif isinstance(res.parsed, Error):\n raise SandboxException(f\"{res.parsed.message}: Request failed\")\n```\n\n资料来源：[packages/python-sdk/e2b/sandbox_async/sandbox_api.py:40-60]()\n\n## Complete Workflow Diagram\n\n```mermaid\ngraph LR\n A[Define Template] --> B[Build Template]\n B --> C[Create Sandbox]\n C --> D[Execute Commands]\n D --> E{More Work?}\n E -->|Yes| D\n E -->|No| F[Terminate Sandbox]\n F --> G[Clean Up]\n \n H[CLI Commands] -.->|Manage| C\n I[SDK API] -.->|Programmatic| D\n```\n\n## See Also\n\n- [Template Building Guide](./template-building.md)\n- [JavaScript SDK Reference](../js-sdk/README.md)\n- [Python SDK Reference](../python-sdk/README.md)\n- [MCP Server Integration](./mcp-integration.md)\n\n---\n\n\n\n## Template System\n\n### 相关页面\n\n相关主题：[CLI Tool](#cli-tool)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/js-sdk/src/template/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/template/index.ts)\n- [packages/js-sdk/src/template/types.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/template/types.ts)\n- [packages/js-sdk/src/template/readycmd.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/template/readycmd.ts)\n- [packages/python-sdk/e2b/template/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template/main.py)\n- [packages/python-sdk/e2b/template/types.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template/types.py)\n- [packages/python-sdk/e2b/template_async/build_api.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template_async/build_api.py)\n- [packages/python-sdk/e2b/template_sync/build_api.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template_sync/build_api.py)\n- [packages/cli/src/commands/template/build.ts](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/template/build.ts)\n- [packages/cli/src/commands/template/create.ts](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/template/create.ts)\n \n\n# Template System\n\n## Overview\n\nThe Template System is a core component of the E2B infrastructure that enables developers to create reproducible, pre-configured sandbox environments for running AI-generated code. Templates define the base image, system packages, environment variables, files, and startup commands needed for a sandbox instance.\n\nTemplates follow a **fluent builder pattern** where developers chain method calls to configure the environment, then invoke `build()` to compile the template into a deployable sandbox image. The system supports both synchronous and asynchronous operations, with full SDK coverage for JavaScript/TypeScript and Python.\n\n资料来源：[packages/js-sdk/src/template/index.ts:1-50]()\n\n## Architecture\n\nThe Template System is organized across multiple layers:\n\n```mermaid\ngraph TD\n subgraph \"User Layer\"\n User[Developer]\n end\n \n subgraph \"SDK Layer\"\n JS_SDK[JS/TS SDK
TemplateBuilder]\n PY_SDK[Python SDK
TemplateBuilder]\n end\n \n subgraph \"API Layer\"\n BuildAPI[Build API]\n SandboxAPI[Sandbox API]\n end\n \n subgraph \"Infrastructure Layer\"\n Docker[Docker Build]\n Registry[Container Registry]\n Sandbox[Sandbox Runtime]\n end\n \n User -->|define template| JS_SDK\n User -->|define template| PY_SDK\n JS_SDK --> BuildAPI\n PY_SDK --> BuildAPI\n BuildAPI --> Docker\n Docker --> Registry\n Registry --> Sandbox\n```\n\n### Package Structure\n\n| Package | Language | Purpose |\n|---------|----------|---------|\n| `packages/js-sdk` | TypeScript | JS/TS SDK with Template support |\n| `packages/python-sdk` | Python | Python SDK with Template support |\n| `packages/cli` | TypeScript | Command-line template management |\n\n## Template Builder Pattern\n\nTemplates use a fluent builder API that enforces a valid state machine. The builder progresses through distinct states:\n\n```mermaid\nstateDiagram-v2\n [*] --> TemplateBuilder: instantiate Template()\n TemplateBuilder --> TemplateBuilder: add instructions\n TemplateBuilder --> TemplateBuilder: set env vars\n TemplateBuilder --> TemplateBuilder: copy files\n TemplateBuilder --> TemplateFinal: setStartCmd()\n TemplateFinal --> [*]: build()\n```\n\n### JavaScript SDK Usage\n\n```typescript\nimport { Template } from 'e2b'\n\nconst template = Template()\n .fromPythonImage('3')\n .runCmd('pip install flask')\n .copy('./app', '/app')\n .setEnvs({ FLASK_ENV: 'production' })\n .setStartCmd(\n 'python /app/main.py',\n 'curl -s http://localhost:8000/health'\n )\n\nconst buildInfo = await Template.build(template, 'my-flask-app:v1.0')\n```\n\n资料来源：[packages/js-sdk/src/template/index.ts:200-280]()\n\n### Python SDK Usage\n\n```python\nfrom e2b import Template\n\ntemplate = (\n Template()\n .from_python_image(\"3\")\n .run_cmd(\"pip install flask\")\n .copy(\"./app\", \"/app\")\n .set_envs({\"FLASK_ENV\": \"production\"})\n .set_start_cmd(\"python /app/main.py\", \"curl -s http://localhost:8000/health\")\n)\n\nbuild_info = template.build(\"my-flask-app:v1.0\")\n```\n\n资料来源：[packages/python-sdk/e2b/template/main.py:1-100]()\n\n## Base Images\n\nThe Template System provides convenience methods for common base images, along with support for custom images and registries.\n\n### Supported Base Images\n\n| Method | Image | Default Variant |\n|--------|-------|-----------------|\n| `fromBaseImage()` | `e2bdev/base:latest` | - |\n| `fromPythonImage()` | `python:{version}` | `3` |\n| `fromNodeImage()` | `node:{variant}` | `lts` |\n| `fromBunImage()` | `oven/bun:{variant}` | `latest` |\n| `fromDebianImage()` | `debian:{variant}` | `stable` |\n| `fromUbuntuImage()` | `ubuntu:{variant}` | `latest` |\n| `fromImage()` | Custom image | Required |\n\n```typescript\n// JavaScript SDK base image examples\nTemplate().fromPythonImage('3.12')\nTemplate().fromNodeImage('20')\nTemplate().fromBunImage('1.3')\n```\n\n```python\n# Python SDK base image examples\nTemplate().from_python_image(\"3.12\")\nTemplate().from_node_image(\"20\")\nTemplate().from_bun_image(\"1.3\")\n```\n\n资料来源：[packages/js-sdk/src/template/types.ts:100-180]()\n\n### Custom Registries\n\nFor private images, configure registry authentication:\n\n```typescript\nimport { Template, GenericDockerRegistry } from 'e2b'\n\nconst registry: GenericDockerRegistry = {\n type: 'registry',\n username: 'myuser',\n password: 'mypassword'\n}\n\nconst template = Template()\n .fromImage('my-private-registry.com/my-image:latest', {\n registries: [registry]\n })\n```\n\n## Build Instructions\n\nTemplates support multiple instruction types that translate directly to Dockerfile commands.\n\n### Instruction Types\n\n| Type | Dockerfile Equivalent | Description |\n|------|----------------------|-------------|\n| `RUN` | `RUN` | Execute shell commands |\n| `COPY` | `COPY` | Copy files into sandbox |\n| `ENV` | `ENV` | Set environment variables |\n| `WORKDIR` | `WORKDIR` | Set working directory |\n| `USER` | `USER` | Set current user |\n\n### Common Instructions\n\n#### Environment Variables\n\n```typescript\ntemplate.setEnvs({ NODE_ENV: 'production', PORT: '8080' })\n```\n\n```python\ntemplate.set_envs({\"NODE_ENV\": \"production\", \"PORT\": \"8080\"})\n```\n\n资料来源：[packages/js-sdk/src/template/types.ts:200-230]()\n\n#### File Operations\n\n```typescript\ntemplate.copy('./local/path', '/remote/path')\ntemplate.copy('./config', '/app/config')\n```\n\n#### Shell Commands\n\n```typescript\ntemplate.runCmd('apt-get update && apt-get install -y vim')\n```\n\n#### Skip Cache\n\nForce rebuild of subsequent layers:\n\n```typescript\ntemplate.skipCache().runCmd('apt-get update')\n```\n\n资料来源：[packages/python-sdk/e2b/template/main.py:150-200]()\n\n## Ready Commands\n\nReady commands verify that the sandbox is fully initialized before accepting connections.\n\n### ReadyCmd Helpers\n\n| Function | Use Case | Implementation |\n|----------|----------|----------------|\n| `waitForPort(port)` | Service listening on port | `nc -z localhost {port}` |\n| `waitForURL(url, statusCode)` | HTTP endpoint availability | `curl` with status check |\n| `waitForProcess(name)` | Daemon process running | `pgrep {name}` |\n| `waitForFile(path)` | File exists in filesystem | `test -f {path}` |\n\n```typescript\nimport { Template, waitForPort, waitForURL, waitForProcess, waitForFile } from 'e2b'\n\nconst template = Template()\n .fromNodeImage()\n .runCmd('npm start')\n .setStartCmd('npm start', waitForPort(3000))\n\nconst template2 = Template()\n .fromPythonImage()\n .setStartCmd('python server.py', waitForURL('http://localhost:8000/health', 200))\n```\n\n资料来源：[packages/js-sdk/src/template/readycmd.ts:1-80]()\n\n## Build Process\n\n### Build Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant TemplateBuilder\n participant BuildAPI\n participant DockerBuild\n participant Registry\n \n User->>TemplateBuilder: Define template\n User->>TemplateBuilder: build(name, options)\n TemplateBuilder->>BuildAPI: POST /templates/build\n BuildAPI->>DockerBuild: Start build\n DockerBuild->>DockerBuild: Build layers\n DockerBuild->>Registry: Push image\n Registry-->>BuildAPI: Build complete\n BuildAPI-->>TemplateBuilder: BuildInfo\n TemplateBuilder-->>User: Template deployed\n```\n\n### Build API Integration\n\nThe JavaScript SDK normalizes build arguments for different calling patterns:\n\n```typescript\n// New pattern - name as parameter\nawait Template.build(template, 'my-template:v1.0')\n\n// Legacy pattern - alias in options\nawait Template.build(template, { alias: 'my-template' })\n```\n\nThe SDK internally calls the E2B Build API which:\n1. Validates the template specification\n2. Initiates Docker build with caching\n3. Monitors build status until completion\n4. Pushes the resulting image to the registry\n\n资料来源：[packages/js-sdk/src/template/index.ts:250-350]()\n\n### Build Options\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `alias` | `string` | Template alias (deprecated) |\n| `tags` | `string[]` | Additional image tags |\n| `timeoutMs` | `number` | Build timeout in milliseconds |\n| `metadata` | `Record` | Custom metadata |\n\n## CLI Integration\n\nThe E2B CLI provides command-line access to template operations.\n\n### Available Commands\n\n| Command | Description |\n|---------|-------------|\n| `e2b template create` | Create a new template from Dockerfile |\n| `e2b template build` | Build and deploy a template |\n| `e2b template publish` | Publish template to registry |\n\n### Build Command\n\n```bash\ne2b template build --name my-template:v1.0\n```\n\nThe CLI reads Dockerfile content and handles:\n- Custom Dockerfile paths\n- Template validation\n- Build polling and status display\n- Error reporting with support links\n\n资料来源：[packages/cli/src/commands/template/build.ts:1-100]()\n\n### Create Command\n\n```bash\ne2b template create my-template\n```\n\nThe create command:\n1. Uploads local template files\n2. Initiates template creation\n3. Polls for completion\n4. Displays example usage code\n\n资料来源：[packages/cli/src/commands/template/create.ts:1-50]()\n\n## State Management\n\nThe template builder enforces valid state transitions through the `TemplateBuilder` and `TemplateFinal` interfaces.\n\n### State Interface Hierarchy\n\n```mermaid\nclassDiagram\n class TemplateBuilder {\n +fromImage(image)\n +runCmd(cmd)\n +copy(src, dest)\n +setEnvs(envs)\n +setStartCmd(start, ready)\n }\n \n class TemplateFinal {\n <>\n }\n \n TemplateBuilder --|> TemplateFinal : after setStartCmd()\n```\n\n### TypeScript Interfaces\n\n```typescript\nexport interface TemplateBuilder {\n fromImage(image: string, options?: FromImageOptions): TemplateBuilder\n runCmd(cmd: string, user?: string): TemplateBuilder\n copy(src: string, dest: string): TemplateBuilder\n setEnvs(envs: Record): TemplateBuilder\n skipCache(): this\n setStartCmd(startCommand: string, readyCommand: string): TemplateFinal\n}\n```\n\nThe `TemplateFinal` interface is an empty marker type that signals the builder is complete and ready for `build()`.\n\n资料来源：[packages/js-sdk/src/template/types.ts:50-150]()\n\n## Dockerfile Generation\n\nTemplates internally generate equivalent Dockerfile instructions:\n\n```typescript\ngenerateDockerfile(): string {\n let dockerfile = `FROM ${this.baseImage}\\n`\n \n for (const instruction of this.instructions) {\n switch (instruction.type) {\n case InstructionType.RUN:\n dockerfile += `RUN ${instruction.args[0]}\\n`\n case InstructionType.COPY:\n dockerfile += `COPY ${instruction.args[0]} ${instruction.args[1]}\\n`\n case InstructionType.ENV:\n const values = instruction.args.map((v, i) => \n i % 2 === 0 ? `${instruction.args[i]}=${instruction.args[i+1]}` : null\n ).filter(Boolean)\n dockerfile += `ENV ${values.join(' ')}\\n`\n }\n }\n \n if (this.startCmd) {\n dockerfile += `ENTRYPOINT ${this.startCmd}\\n`\n }\n \n return dockerfile\n}\n```\n\n资料来源：[packages/js-sdk/src/template/index.ts:350-400]()\n\n## Error Handling\n\nBuild errors are caught and reported with actionable guidance:\n\n```typescript\ncase 'error':\n throw new Error(\n `❌ Building sandbox template ${templateName} failed.\nCheck the logs above for more details or contact us (https://e2b.dev/docs/support) to get help.`\n )\n```\n\n## SDK Configuration\n\nTemplates inherit connection configuration for API communication:\n\n```typescript\nconst config = new ConnectionConfig(sandboxOpts)\nconst client = new ApiClient(config)\n```\n\nConfiguration includes:\n- API key authentication\n- Request timeouts\n- Debug mode for local development\n- Signal handling for cancellation\n\n资料来源：[packages/js-sdk/src/sandbox/index.ts:100-150]()\n\n## Summary\n\nThe E2B Template System provides a unified, fluent API for defining sandbox environments across JavaScript and Python SDKs. Key capabilities include:\n\n- **Base image selection** with convenience methods for common runtimes\n- **Instruction composition** using familiar Dockerfile semantics\n- **Ready command validation** ensuring sandboxes are fully initialized\n- **Build API integration** for remote Docker builds and registry deployment\n- **CLI tooling** for command-line workflow integration\n- **State machine enforcement** preventing invalid template configurations\n\n---\n\n\n\n## Filesystem and Git Operations\n\n### 相关页面\n\n相关主题：[Sandbox Usage](#sandbox-usage)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/js-sdk/src/sandbox/filesystem/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/filesystem/index.ts)\n- [packages/js-sdk/src/sandbox/filesystem/watchHandle.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/filesystem/watchHandle.ts)\n- [packages/js-sdk/src/sandbox/git/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/git/index.ts)\n- [packages/python-sdk/e2b/sandbox/filesystem/filesystem.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox/filesystem/filesystem.py)\n- [packages/python-sdk/e2b/sandbox_async/filesystem/filesystem.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_async/filesystem/filesystem.py)\n- [packages/python-sdk/e2b/sandbox_sync/filesystem/filesystem.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_sync/filesystem/filesystem.py)\n- [packages/python-sdk/e2b/sandbox/git.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox/git.py)\n- [packages/python-sdk/e2b/sandbox_async/git.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_async/git.py)\n- [packages/python-sdk/e2b/sandbox_sync/git.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_sync/git.py)\n- [packages/python-sdk/e2b/sandbox/_git/__init__.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox/_git/__init__.py)\n- [packages/python-sdk/e2b/sandbox/_git/args.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox/_git/args.py)\n- [packages/python-sdk/e2b/sandbox/_git/auth.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox/_git/auth.py)\n \n\n# Filesystem and Git Operations\n\n## Overview\n\nThe E2B SDK provides comprehensive filesystem and Git operations for interacting with sandbox environments. These operations allow developers to read, write, and watch files within isolated sandboxes, as well as perform Git operations including repository cloning with various authentication methods.\n\nFilesystem operations are available through dedicated filesystem classes that handle file I/O with support for multiple data formats (text, bytes, blob, stream), compression, and user-specific permissions. Git operations provide a fluent API for cloning repositories using SSH keys, tokens, or username/password authentication. 资料来源：[packages/js-sdk/src/sandbox/filesystem/index.ts:1-100]()\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n A[Sandbox Instance] --> B[Filesystem API]\n A --> C[Git API]\n \n B --> D[envd API - /files endpoint]\n B --> E[Volume API - /volumecontent endpoint]\n \n C --> F[envd API - git operations]\n C --> G[SSH Key Management]\n C --> H[Token Auth]\n C --> I[Username/Password Auth]\n \n J[Read Operations] --> K[text | bytes | blob | stream]\n L[Write Operations] --> M[multipart/form-data | application/octet-stream]\n N[Watch Operations] --> O[FilesystemEvent stream]\n```\n\n## Filesystem Operations\n\n### Core Components\n\nThe filesystem module is implemented separately in both JavaScript and Python SDKs with consistent functionality across both platforms.\n\n#### JavaScript SDK\n\nThe JavaScript SDK exposes filesystem operations through the `Sandbox.filesystem` property, providing type-safe methods for file operations. 资料来源：[packages/js-sdk/src/sandbox/filesystem/index.ts:1-50]()\n\n#### Python SDK\n\nThe Python SDK provides filesystem access through both synchronous (`sandbox_sync`) and asynchronous (`sandbox_async`) implementations, allowing developers to choose the appropriate model for their application. 资料来源：[packages/python-sdk/e2b/sandbox_sync/filesystem/filesystem.py:1-50]()\n\n### Reading Files\n\n#### Supported Formats\n\n| Format | Return Type | Description |\n|--------|-------------|-------------|\n| `text` | `string` | File content as plain text (default) |\n| `bytes` | `Uint8Array` / `bytes` | Raw binary content |\n| `blob` | `Blob` | Web API Blob object |\n| `stream` | `ReadableStream` | Streaming response |\n\nThe `read` method automatically handles user version compatibility by checking the envd API version. If the sandbox's envd version is below the default user version threshold, it falls back to a default username for authentication. 资料来源：[packages/js-sdk/src/sandbox/filesystem/index.ts:60-80]()\n\n#### Read Options\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `format` | `'text' \\| 'bytes' \\| 'blob' \\| 'stream'` | `'text'` | Output format |\n| `gzip` | `boolean` | `false` | Request gzip-compressed response |\n| `user` | `string` | `undefined` | Run as specific user |\n| `signal` | `AbortSignal` | `undefined` | Cancellation signal |\n| `requestTimeoutMs` | `number` | `undefined` | Request timeout |\n\n#### JavaScript SDK Example\n\n```typescript\n// Read as text\nconst content = await sandbox.filesystem.read('/path/to/file.txt')\n\n// Read as bytes\nconst bytes = await sandbox.filesystem.read('/path/to/file.bin', { format: 'bytes' })\n\n// Read with gzip compression\nconst compressed = await sandbox.filesystem.read('/path/to/large.txt', { gzip: true })\n```\n\n#### Python SDK Example\n\n```python\n# Read as text\ncontent = sandbox.filesystem.read('/path/to/file.txt')\n\n# Read as bytes\nbytes_data = sandbox.filesystem.read('/path/to/file.bin', format='bytes')\n\n# Async version\ncontent = await sandbox.filesystem.read('/path/to/file.txt')\n```\n\n### Writing Files\n\nThe write operation supports multiple files in a single call and creates necessary parent directories automatically. 资料来源：[packages/python-sdk/e2b/sandbox_sync/filesystem/filesystem.py:40-70]()\n\n#### Write Options\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `files` | `WriteEntry[]` | Required | List of files to write |\n| `user` | `string` | `undefined` | Run as specific user |\n| `gzip` | `boolean` | `false` | Use gzip compression |\n| `use_octet_stream` | `boolean` | `false` | Use octet-stream upload (requires envd 0.5.7+) |\n| `request_timeout` | `number` | `undefined` | Request timeout |\n\n#### WriteEntry Structure\n\n```typescript\ninterface WriteEntry {\n path: string // Destination path in sandbox\n data: string | Uint8Array // File content\n}\n```\n\n#### Upload Methods\n\nThe SDK supports two upload methods:\n\n1. **multipart/form-data** (default, universally supported)\n2. **application/octet-stream** (faster, requires envd 0.5.7+)\n\nWhen `use_octet_stream` is enabled and the envd version supports it, the upload uses `application/octet-stream` content type. Otherwise, it gracefully falls back to multipart form data. 资料来源：[packages/python-sdk/e2b/sandbox_sync/filesystem/filesystem.py:60-85]()\n\n#### Write Example\n\n```typescript\nawait sandbox.filesystem.write([\n { path: '/app/config.json', data: JSON.stringify(config) },\n { path: '/app/data.bin', data: binaryBuffer }\n])\n```\n\n### Directory Watching\n\nThe filesystem module provides directory watching capabilities through the `WatchHandle` class, allowing applications to monitor filesystem changes in real-time. 资料来源：[packages/js-sdk/src/sandbox/filesystem/watchHandle.ts:30-50]()\n\n#### WatchHandle Class\n\n```typescript\nclass WatchHandle {\n // Stop watching the directory\n async stop(): void\n \n // Event callback\n onEvent?: (event: FilesystemEvent) => void | Promise\n \n // Exit callback with optional error\n onExit?: (err?: Error) => void | Promise\n}\n```\n\n#### FilesystemEvent Structure\n\n```typescript\ninterface FilesystemEvent {\n name: string // Name of the changed file/directory\n type: FilesystemEventType // 'created' | 'modified' | 'deleted'\n}\n```\n\n#### Watch Flow\n\n```mermaid\nsequenceDiagram\n participant App as Application\n participant WH as WatchHandle\n participant API as envd API\n participant FS as Sandbox FS\n \n App->>WH: watch('/path')\n WH->>API: Subscribe to filesystem events\n FS->>API: File change detected\n API->>WH: Event stream\n WH->>App: onEvent callback\n App->>WH: stop()\n WH->>API: Unsubscribe\n```\n\n#### Watch Example\n\n```typescript\nconst handle = await sandbox.filesystem.watch('/app', {\n onEvent: (event) => {\n console.log(`File ${event.type}: ${event.name}`)\n },\n onExit: (err) => {\n if (err) console.error('Watch error:', err)\n }\n})\n\n// Later: stop watching\nawait handle.stop()\n```\n\n### File Information\n\nWhen writing files, the operation returns `WriteInfo` objects containing metadata about the created/modified files.\n\n#### WriteInfo Structure\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `name` | `string` | Name of the filesystem object |\n| `type` | `FileType` | Type of object (file, directory, symlink) |\n| `path` | `string` | Full path to the object |\n\n#### EntryInfo (for directory listings)\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `size` | `number` | Size in bytes |\n| `mode` | `number` | File mode and permission bits |\n| `permissions` | `string` | String representation (e.g., 'rwxr-xr-x') |\n| `owner` | `string` | Owner username |\n| `group` | `string` | Group owner |\n| `modifiedTime` | `Date` | Last modification time |\n| `symlinkTarget` | `string` | Target if symlink |\n\n## Git Operations\n\nGit operations provide a fluent API for cloning and managing Git repositories within sandboxes. The implementation supports multiple authentication methods and comprehensive git functionality. 资料来源：[packages/python-sdk/e2b/sandbox/git.py:1-80]()\n\n### Authentication Methods\n\nThe SDK supports three authentication methods for Git operations:\n\n| Method | Description | Use Case |\n|--------|-------------|----------|\n| SSH Key | Use predefined SSH key stored in E2B | Private repository access |\n| Token | Personal Access Token or GitHub Token | CI/CD scenarios |\n| Username/Password | Basic authentication | Legacy systems |\n\n#### Authentication Configuration\n\n```python\n# SSH Key authentication (most common)\ngit.auth.ssh_key('my-ssh-key-name')\n\n# Token authentication\ngit.auth.token('ghp_xxxxxxxxxxxx')\n\n# Username/Password\ngit.auth.username_password('user', 'password')\n```\n\n### Git Clone Operations\n\n#### Clone Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `url` | `string` | Yes | Repository URL |\n| `path` | `string` | No | Destination path (defaults to repo name) |\n| `branch` | `string` | No | Specific branch to clone |\n| `depth` | `number` | No | Clone depth for shallow clone |\n| `recursive` | `bool` | No | Clone submodules (default: true) |\n\n#### Clone Example\n\n```python\n# Basic clone\nsandbox.git.clone('https://github.com/user/repo.git')\n\n# Clone to specific path\nsandbox.git.clone('https://github.com/user/repo.git', '/workspace/project')\n\n# Clone specific branch\nsandbox.git.clone('https://github.com/user/repo.git', branch='develop')\n\n# Shallow clone\nsandbox.git.clone('https://github.com/user/repo.git', depth=1)\n\n# With authentication\nsandbox.git.auth.token('ghp_xxx').clone('https://github.com/user/private.git')\n```\n\n### Git Module Structure\n\nThe Python SDK organizes Git functionality across multiple modules:\n\n```mermaid\nclassDiagram\n class GitCore {\n +clone()\n +auth: GitAuth\n }\n class GitAuth {\n +ssh_key(name)\n +token(token)\n +username_password(user, pass)\n }\n class GitArgs {\n +build_clone_args()\n }\n \n GitCore --> GitAuth\n GitCore --> GitArgs\n```\n\n#### Module Responsibilities\n\n| Module | Purpose |\n|--------|---------|\n| `e2b/sandbox/_git/__init__.py` | Core git operations and command building |\n| `e2b/sandbox/_git/args.py` | Argument construction for git commands |\n| `e2b/sandbox/_git/auth.py` | Authentication configuration management |\n\n### JavaScript SDK Git Operations\n\nThe JavaScript SDK provides similar git functionality with a fluent builder pattern:\n\n```typescript\n// Clone repository\nawait sandbox.git.clone('https://github.com/user/repo.git')\n\n// Clone with options\nawait sandbox.git.clone('https://github.com/user/repo.git', {\n path: '/workspace/project',\n branch: 'main',\n depth: 1\n})\n\n// With authentication\nawait sandbox.git.auth.sshKey('my-key')\nawait sandbox.git.clone('git@github.com:user/private.git')\n```\n\n## Error Handling\n\n### Filesystem Errors\n\nThe SDK provides specific error types for filesystem operations:\n\n| Error Type | Condition |\n|------------|-----------|\n| `FileNotFoundError` | File or directory does not exist |\n| `NotFoundError` | Volume path not found |\n| `SandboxError` | General sandbox communication error |\n| `CommandExitError` | Command execution failed |\n\n#### Error Mapping\n\n```mermaid\ngraph LR\n A[HTTP/RPC Error] --> B{Error Code}\n B -->|404| C[FileNotFoundError]\n B -->|Default| D[SandboxError]\n \n E[API Response] --> F{Status Code}\n F -->|404| G[NotFoundError]\n F -->|Default| H[Generic Error]\n```\n\n### Error Handling Example\n\n```typescript\ntry {\n const content = await sandbox.filesystem.read('/path/to/file')\n} catch (error) {\n if (error instanceof FileNotFoundError) {\n console.log('File does not exist')\n } else if (error instanceof SandboxError) {\n console.log('Sandbox communication error:', error.message)\n }\n}\n```\n\n## Version Compatibility\n\n### envd Version Requirements\n\n| Feature | Minimum envd Version |\n|---------|---------------------|\n| Basic filesystem read/write | 0.1.0 |\n| Default user handling | Automatic fallback for older versions |\n| Octet-stream upload | 0.5.7 |\n| Gzip compression | All versions |\n\n### Version Checking\n\nThe SDK automatically checks the envd version during sandbox initialization and adjusts behavior accordingly:\n\n```typescript\n// Automatic version check in read operation\nif (user == undefined && compareVersions(envdVersion, ENVD_DEFAULT_USER) < 0) {\n user = defaultUsername\n}\n```\n\n## Best Practices\n\n1. **Use Appropriate Formats**: Choose `stream` for large files to avoid memory issues\n2. **Enable Compression**: Use gzip for text-based files larger than 1KB\n3. **Use Octet-Stream**: Enable for faster uploads when targeting envd 0.5.7+\n4. **Handle Errors**: Always catch specific error types for better error handling\n5. **Set Timeouts**: Configure appropriate request timeouts for network operations\n6. **Watch Cleanup**: Always call `stop()` on WatchHandle when done\n\n## Summary\n\nThe Filesystem and Git Operations in E2B provide comprehensive tools for:\n\n- **Reading files** in multiple formats (text, bytes, blob, stream) with optional compression\n- **Writing files** with automatic directory creation and multiple upload methods\n- **Watching directories** for real-time filesystem event monitoring\n- **Git operations** with flexible authentication (SSH keys, tokens, username/password)\n- **Robust error handling** with specific error types and version compatibility\n\n---\n\n\n\n## Network Configuration\n\n### 相关页面\n\n相关主题：[Sandbox Usage](#sandbox-usage), [Sandbox Management](#sandbox-management)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/js-sdk/src/sandbox/network.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/network.ts)\n- [packages/python-sdk/e2b/sandbox/network.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox/network.py)\n- [packages/python-sdk/e2b/api/client/models/sandbox_network_config.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/api/client/models/sandbox_network_config.py)\n- [packages/js-sdk/src/connectionConfig.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/connectionConfig.ts)\n \n\n# Network Configuration\n\nE2B provides comprehensive network configuration capabilities for sandboxes, allowing users to control DNS resolution, port access rules, and VPN connectivity. This document describes the network configuration system across the JavaScript and Python SDKs.\n\n## Overview\n\nNetwork Configuration in E2B enables fine-grained control over how sandboxes communicate with external networks and how network traffic is managed. Each sandbox can be configured with custom DNS settings, port access policies, and optional VPN tunnel support.\n\n资料来源：[packages/js-sdk/src/sandbox/network.ts:1-50]()\n\n## Architecture\n\nThe network configuration system consists of three main components that work together to manage sandbox networking:\n\n```mermaid\ngraph TD\n A[Sandbox Creation] --> B[NetworkConfig]\n B --> C[DNS Configuration]\n B --> D[Port Rules]\n B --> E[VPN Settings]\n C --> F[Sandbox DNS Resolution]\n D --> G[Port Access Control]\n E --> H[VPN Tunnel]\n```\n\n### Data Flow\n\nWhen creating a sandbox, the network configuration is serialized and sent to the E2B API as part of the sandbox creation request. The API validates and stores the configuration, which is then applied when the sandbox environment initializes.\n\n资料来源：[packages/python-sdk/e2b/api/client/models/sandbox_network_config.py:1-100]()\n\n## JavaScript SDK Implementation\n\n### NetworkConfig Interface\n\nThe JavaScript SDK provides a `NetworkConfig` interface located in `packages/js-sdk/src/sandbox/network.ts`:\n\n```typescript\ninterface NetworkConfig {\n dns?: DNSConfig\n ports?: PortConfig[]\n vpn?: VPNConfig\n}\n```\n\n#### DNS Configuration\n\nControls how the sandbox resolves domain names:\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `customServers` | `string[]` | List of custom DNS server IPs |\n| `blockAutoDetect` | `boolean` | Whether to block auto-detected DNS |\n\n资料来源：[packages/js-sdk/src/sandbox/network.ts:10-30]()\n\n#### Port Configuration\n\nManages inbound and outbound port access:\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `port` | `number` | The port number to configure |\n| `protocol` | `'tcp' \\| 'udp'` | Network protocol |\n| `access` | `'allow' \\| 'deny'` | Access rule for the port |\n| `description` | `string` | Optional description |\n\n资料来源：[packages/js-sdk/src/sandbox/network.ts:35-45]()\n\n#### VPN Configuration\n\nProvides VPN tunnel support:\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `enabled` | `boolean` | Enable/disable VPN tunnel |\n| `config` | `VPNConfig` | VPN configuration object |\n\n资料来源：[packages/js-sdk/src/sandbox/network.ts:50-60]()\n\n### Usage Example\n\n```typescript\nimport { Sandbox, NetworkConfig } from 'e2b'\n\nconst networkConfig: NetworkConfig = {\n dns: {\n customServers: ['8.8.8.8', '1.1.1.1'],\n blockAutoDetect: true\n },\n ports: [\n { port: 80, protocol: 'tcp', access: 'allow', description: 'HTTP' },\n { port: 443, protocol: 'tcp', access: 'allow', description: 'HTTPS' },\n { port: 22, protocol: 'tcp', access: 'deny', description: 'SSH disabled' }\n ],\n vpn: {\n enabled: true\n }\n}\n\nconst sandbox = await Sandbox.create('my-template', {\n network: networkConfig\n})\n```\n\n资料来源：[packages/js-sdk/src/sandbox/sandboxApi.ts:1-50]()\n\n## Python SDK Implementation\n\n### NetworkConfig Class\n\nThe Python SDK provides a fluent API for network configuration in `packages/python-sdk/e2b/sandbox/network.py`:\n\n```python\nclass NetworkConfig:\n def __init__(self) -> None:\n self._dns: Optional[DNSConfig] = None\n self._ports: List[PortRule] = []\n self._vpn: Optional[VPNConfig] = None\n```\n\n#### DNS Configuration\n\n```python\nclass DNSConfig:\n custom_servers: Optional[List[str]] = None\n block_auto_detect: bool = False\n```\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `custom_servers` | `List[str]` | `None` | Custom DNS server IPs |\n| `block_auto_detect` | `bool` | `False` | Block auto-detected DNS |\n\n资料来源：[packages/python-sdk/e2b/sandbox/network.py:1-80]()\n\n#### Port Rules\n\n```python\nclass PortRule:\n port: int\n protocol: str # 'tcp' or 'udp'\n access: str # 'allow' or 'deny'\n description: Optional[str] = None\n```\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `port` | `int` | Yes | Port number |\n| `protocol` | `str` | Yes | Network protocol |\n| `access` | `str` | Yes | Access rule |\n| `description` | `str` | No | Rule description |\n\n资料来源：[packages/python-sdk/e2b/sandbox/network.py:80-150]()\n\n### Fluent API Methods\n\nThe Python SDK provides a fluent interface for building network configurations:\n\n#### DNS Configuration\n\n```python\ndef dns(self, servers: List[str], block_auto_detect: bool = False) -> \"NetworkConfig\":\n \"\"\"Configure custom DNS servers.\"\"\"\n self._dns = DNSConfig(\n custom_servers=servers,\n block_auto_detect=block_auto_detect\n )\n return self\n```\n\n#### Port Management\n\n```python\ndef allow_port(self, port: int, protocol: str = \"tcp\", description: str = None) -> \"NetworkConfig\":\n \"\"\"Allow traffic on specified port.\"\"\"\n self._ports.append(PortRule(\n port=port,\n protocol=protocol,\n access=\"allow\",\n description=description\n ))\n return self\n\ndef deny_port(self, port: int, protocol: str = \"tcp\", description: str = None) -> \"NetworkConfig\":\n \"\"\"Deny traffic on specified port.\"\"\"\n self._ports.append(PortRule(\n port=port,\n protocol=protocol,\n access=\"deny\",\n description=description\n ))\n return self\n```\n\n#### VPN Configuration\n\n```python\ndef enable_vpn(self) -> \"NetworkConfig\":\n \"\"\"Enable VPN tunnel for the sandbox.\"\"\"\n self._vpn = VPNConfig(enabled=True)\n return self\n```\n\n资料来源：[packages/python-sdk/e2b/sandbox/network.py:150-250]()\n\n### Python Usage Example\n\n```python\nfrom e2b import Sandbox, NetworkConfig\n\nnetwork = (\n NetworkConfig()\n .dns(servers=['8.8.8.8', '1.1.1.1'], block_auto_detect=True)\n .allow_port(80, protocol='tcp', description='HTTP traffic')\n .allow_port(443, protocol='tcp', description='HTTPS traffic')\n .allow_port(5432, protocol='tcp', description='PostgreSQL')\n .deny_port(22, protocol='tcp', description='SSH disabled')\n .enable_vpn()\n)\n\nsandbox = await Sandbox.create(\n template='my-template',\n network=network\n)\n```\n\n资料来源：[packages/python-sdk/e2b/sandbox_async/main.py:1-80]()\n\n## API Model\n\nThe backend API uses a standardized `SandboxNetworkConfig` model defined in OpenAPI format:\n\n```python\nclass SandboxNetworkConfig:\n dns: Optional[DNSConfig] = None\n ports: Optional[List[PortRule]] = None\n vpn: Optional[VPNConfig] = None\n```\n\n资料来源：[packages/python-sdk/e2b/api/client/models/sandbox_network_config.py:1-100]()\n\n### Serialization\n\nThe configuration is serialized to JSON when sent to the API:\n\n```json\n{\n \"dns\": {\n \"customServers\": [\"8.8.8.8\", \"1.1.1.1\"],\n \"blockAutoDetect\": true\n },\n \"ports\": [\n {\"port\": 80, \"protocol\": \"tcp\", \"access\": \"allow\"},\n {\"port\": 443, \"protocol\": \"tcp\", \"access\": \"allow\"}\n ],\n \"vpn\": {\"enabled\": true}\n}\n```\n\n资料来源：[packages/js-sdk/src/sandbox/sandboxApi.ts:50-70]()\n\n## Sandbox Creation Integration\n\nNetwork configuration is passed during sandbox creation through the `network` option:\n\n### JavaScript\n\n```typescript\nconst sandboxInfo = await SandboxApi.createSandbox(\n template,\n timeoutMs,\n {\n network: networkConfig,\n // ... other options\n }\n)\n```\n\n### Python\n\n```python\nsandbox = await cls._create(\n template=template,\n timeout=timeout,\n network=network,\n # ... other options\n)\n```\n\n资料来源：[packages/js-sdk/src/sandbox/sandboxApi.ts:1-50]()\n资料来源：[packages/python-sdk/e2b/sandbox_async/main.py:1-60]()\n\n## Default Behavior\n\nWhen no network configuration is provided, the sandbox uses default network settings:\n\n| Setting | Default Value |\n|---------|---------------|\n| DNS | Auto-detected system DNS |\n| Ports | All ports allowed |\n| VPN | Disabled |\n\nInternet access is enabled by default unless explicitly disabled via `allow_internet_access: false`.\n\n资料来源：[packages/js-sdk/src/sandbox/sandboxApi.ts:20-40]()\n\n## Best Practices\n\n1. **Explicit Port Rules**: Always explicitly define port access rules rather than relying on defaults for production workloads.\n\n2. **DNS Configuration**: Use specific DNS servers when you need consistent resolution behavior across sandbox instances.\n\n3. **VPN for Sensitive Workloads**: Enable VPN when handling sensitive data that requires encrypted tunnel communication.\n\n4. **Protocol Specificity**: Specify both port and protocol to avoid unintended access.\n\n## Related Documentation\n\n- [Sandbox API Reference](packages/js-sdk/src/sandbox/sandboxApi.ts)\n- [Connection Configuration](packages/js-sdk/src/connectionConfig.ts)\n- [Template Building](packages/cli/src/commands/template/build.ts)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：e2b-dev/E2B\n\n摘要：发现 20 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：配置坑 - 来源证据：process was not killed when auto paused。\n\n## 1. 配置坑 · 来源证据：process was not killed when auto paused\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：process was not killed when auto paused\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_66994844a2ec44a784ad5b80307d82e9 | https://github.com/e2b-dev/E2B/issues/1031 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 安装坑 · 来源证据：Closed Port Error\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Closed Port Error\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_33133a8885a44301a7f98b23844205cc | https://github.com/e2b-dev/E2B/issues/907 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：Please add skills to use with any ai agent to use e2b in our project\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Please add skills to use with any ai agent to use e2b in our project\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8cebd572dbd2485ab6cdbc13733fdee0 | https://github.com/e2b-dev/E2B/issues/1138 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 安装坑 · 来源证据：[Bug]: Incorrect info about webhooks in docs and dashboard\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: Incorrect info about webhooks in docs and dashboard\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8b25841679fd4eaea5d759a33dfad3b1 | https://github.com/e2b-dev/E2B/issues/1103 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 5. 安装坑 · 来源证据：[Bug]: Sandbox create fails from template, but succeeds without template\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: Sandbox create fails from template, but succeeds without template\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3ae274a17e7e420ca9f2cd6e7c6105bd | https://github.com/e2b-dev/E2B/issues/1130 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 安装坑 · 来源证据：build status polling timed out\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：build status polling timed out\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_88fc7403d6a44edb8b8d4c9deaff0279 | https://github.com/e2b-dev/E2B/issues/1009 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 7. 配置坑 · 来源证据：Paused sandbox is not persisting the file changes / addition after second time resumed and onward\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Paused sandbox is not persisting the file changes / addition after second time resumed and onward\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2fc5340254c94ae2931673fede53e25b | https://github.com/e2b-dev/E2B/issues/884 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 8. 配置坑 · 社区讨论暴露的待验证问题：[Bug]: torch.compile fails for Gemma3n on pytorch 2.8\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：[Bug]: torch.compile fails for Gemma3n on pytorch 2.8 ### Your current environment The output of python collect_env.py
```text Your output of `python collect_env.py` here ``` ### 🐛 Describe the bug run ``` vllm serve google/gemma-3n-E2B-it -tp 1 ``` on torch==2.8.0:…\n- 对用户的影响：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。\n- 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。\n- 证据：social_signal:github | ssig_3c3209f718cd4d108c88e3bf9d35db24 | https://github.com/vllm-project/vllm/issues/24547 | [Bug]: torch.compile fails for Gemma3n on pytorch 2.8\n\n## 9. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:609539715 | https://github.com/e2b-dev/E2B | README/documentation is current enough for a first validation pass.\n\n## 10. 维护坑 · 来源证据：When using autoPause in sandbox creation, connect overrides this when resuming the sandbox again\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：When using autoPause in sandbox creation, connect overrides this when resuming the sandbox again\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3002fb1e72dd4aa2ab6baed80425d7b2 | https://github.com/e2b-dev/E2B/issues/875 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 11. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:609539715 | https://github.com/e2b-dev/E2B | last_activity_observed missing\n\n## 12. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:609539715 | https://github.com/e2b-dev/E2B | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:609539715 | https://github.com/e2b-dev/E2B | no_demo; severity=medium\n\n## 14. 安全/权限坑 · 来源证据：(feature request) Run-scoped messaging for multi-sandbox agent workflows\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：(feature request) Run-scoped messaging for multi-sandbox agent workflows\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a6ad64f1b6d54498906e63b880471ac4 | https://github.com/e2b-dev/E2B/issues/1330 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 15. 安全/权限坑 · 来源证据：AuthenticationError: Unauthorized, please check your credentials. - Invalid API key\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：AuthenticationError: Unauthorized, please check your credentials. - Invalid API key\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c6225e71e02943b7a367a36c86c96b65 | https://github.com/e2b-dev/E2B/issues/980 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 16. 安全/权限坑 · 来源证据：Docker Build Secrets Support\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Docker Build Secrets Support\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6d5e325b8d00480b8ac7acf0b5b01379 | https://github.com/e2b-dev/E2B/issues/815 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 17. 安全/权限坑 · 来源证据：How to use the file that I uploaded when I create template\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：How to use the file that I uploaded when I create template\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_57466d7f984143c1bb2ae3fb20b9b4f0 | https://github.com/e2b-dev/E2B/issues/1049 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：Template Build Fails with \"syncing took too long\" Error\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Template Build Fails with \"syncing took too long\" Error\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4c757d3a005b45989cf3f2e3a6f4433b | https://github.com/e2b-dev/E2B/issues/996 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 19. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:609539715 | https://github.com/e2b-dev/E2B | issue_or_pr_quality=unknown\n\n## 20. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:609539715 | https://github.com/e2b-dev/E2B | release_recency=unknown\n\n\n",
"markdown_key": "e2b",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:609539715",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/e2b-dev/E2B"
},
{
"evidence_id": "art_49c083e4950344c48d9f0a6a3182e45f",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/e2b-dev/E2B#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "E2B 说明书",
"toc": [
"https://github.com/e2b-dev/E2B 项目说明书",
"目录",
"Overview",
"What is E2B?",
"Architecture Overview",
"SDKs Overview",
"Template Builder System",
"File System Operations",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "2ac5de2edf6768b9bc93e87762e67b6a44328c99",
"repo_inspection_error": null,
"repo_inspection_files": [
"pnpm-lock.yaml",
"package.json",
"README.md",
"packages/cli/vitest.config.ts",
"packages/cli/package.json",
"packages/cli/README.md",
"packages/cli/tsconfig.json",
"packages/cli/tsup.config.js",
"packages/connect-python/pyproject.toml",
"packages/connect-python/README.md",
"packages/python-sdk/pyproject.toml",
"packages/python-sdk/package.json",
"packages/python-sdk/README.md",
"packages/python-sdk/example.py",
"packages/js-sdk/package.json",
"packages/js-sdk/README.md",
"packages/js-sdk/tsconfig.json",
"packages/js-sdk/tsup.config.js",
"packages/cli/src/terminal.ts",
"packages/cli/src/user.ts",
"packages/cli/src/index.ts",
"packages/cli/src/api.ts",
"packages/cli/src/options.ts",
"packages/cli/tests/setup.ts",
"packages/cli/src/config/index.ts",
"packages/cli/src/utils/templatePrompt.ts",
"packages/cli/src/utils/errors.ts",
"packages/cli/src/utils/confirm.ts",
"packages/cli/src/utils/commands2md.ts",
"packages/cli/src/utils/signal.ts",
"packages/cli/src/utils/wait.ts",
"packages/cli/src/utils/templateSort.ts",
"packages/cli/src/utils/urls.ts",
"packages/cli/src/utils/format.ts",
"packages/cli/src/utils/filesystem.ts",
"packages/cli/src/docker/constants.ts",
"packages/cli/src/commands/index.ts",
"packages/cli/src/commands/template/migrate.ts",
"packages/cli/src/commands/template/build.ts",
"packages/cli/src/commands/template/list.ts"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# e2b - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 e2b 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **想在安装前理解开源项目价值和边界的用户**：当前证据主要来自项目文档。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md`, `packages/cli/README.md`, `packages/js-sdk/README.md`, `packages/python-sdk/README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `npm i e2b` 证据：`README.md` Claim：`clm_0003` supported 0.86, `clm_0005` supported 0.86, `clm_0008` supported 0.86\n- `pip install e2b` 证据：`README.md` Claim：`clm_0004` supported 0.86, `clm_0006` supported 0.86, `clm_0009` supported 0.86\n- `npm i @e2b/code-interpreter # JavaScript/TypeScript` 证据：`README.md` Claim：`clm_0005` supported 0.86\n- `pip install e2b-code-interpreter # Python` 证据：`README.md` Claim：`clm_0006` supported 0.86\n- `npm install -g @e2b/cli` 证据：`packages/cli/README.md` Claim：`clm_0007` supported 0.86\n- `npm i @e2b/code-interpreter` 证据：`packages/js-sdk/README.md` Claim：`clm_0005` supported 0.86, `clm_0008` supported 0.86\n- `pip install e2b-code-interpreter` 证据：`packages/python-sdk/README.md` Claim：`clm_0006` supported 0.86, `clm_0009` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：需要管理员/安全审批\n- **为什么**：继续前可能涉及密钥、账号、外部服务或敏感上下文，建议先经过管理员或安全审批。\n\n### 30 秒判断\n\n- **现在怎么做**：需要管理员/安全审批\n- **最小安全下一步**：先跑 Prompt Preview；若涉及凭证或企业环境，先审批再试装\n- **先别相信**：真实输出质量不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：想在安装前理解开源项目价值和边界的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md`, `packages/cli/README.md`, `packages/js-sdk/README.md`, `packages/python-sdk/README.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86, `clm_0005` supported 0.86, `clm_0008` supported 0.86\n\n### 现在还不能相信\n\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`CLAUDE.md`\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`, `packages/cli/README.md`, `packages/js-sdk/README.md`, `packages/python-sdk/README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`CLAUDE.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`, `packages/cli/README.md`, `packages/js-sdk/README.md`, `packages/python-sdk/README.md`\n- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`README.md`, `packages/cli/README.md`, `packages/cli/src/api.ts`, `packages/cli/src/commands/auth/login.ts` 等\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **不要使用真实生产凭证**：环境变量/API key 一旦进入宿主或工具链，可能产生账号和合规风险。（适用：出现 API、TOKEN、KEY、SECRET 等环境线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **准备撤销测试 API key 或 token**：测试凭证泄露或误用时，可以快速止损。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0010` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md`, `packages/cli/README.md`, `packages/js-sdk/README.md`, `packages/python-sdk/README.md` Claim：`clm_0011` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md`, `packages/cli/README.md`, `packages/js-sdk/README.md`, `packages/python-sdk/README.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：711\n- 重要文件覆盖：40/711\n- 证据索引条目：44\n- 角色 / Skill 条目：12\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 e2b 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 e2b 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 e2b 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 12 个角色 / Skill / 项目文档条目。\n\n- **Changesets**（project_doc）：in the root of the project. This will create a new changeset in the .changeset folder. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/README.md`\n- **Claude**（project_doc）：Use pnpm for node and poetry for python to install and update dependencies. Run pnpm run format , pnpm run lint and pnpm run typecheck before committing changes. To re-generate the API client run make codegen in the repository root. Run tests on affected codepaths using pnpm run test . Generate changesets after updating packages/cli, packages/js-sdk, packages/python-sdk. Default credentials are stored in .env.local… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CLAUDE.md`\n- **What is E2B?**（project_doc）：! E2B SDK Preview /readme-assets/e2b-sdk-light.png gh-light-mode-only ! E2B SDK Preview /readme-assets/e2b-sdk-dark.png gh-dark-mode-only 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **E2B CLI**（project_doc）：This CLI tool allows you to build manager your running E2B sandbox and sandbox templates. Learn more in our documentation https://e2b.dev/docs . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/cli/README.md`\n- **connect-python**（project_doc）：🚧 Currently pending an open RFC to be moved into the Connect RPC org https://github.com/connectrpc/connectrpc.com/pull/71 . Please show support. 🚧 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/connect-python/README.md`\n- **What is E2B?**（project_doc）：--- What is E2B? E2B https://www.e2b.dev/ is an open-source infrastructure that allows you to run AI-generated code in secure isolated sandboxes in the cloud. To start and control sandboxes, use our JavaScript SDK https://www.npmjs.com/package/e2b or Python SDK https://pypi.org/project/e2b . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/js-sdk/README.md`\n- **What is E2B?**（project_doc）：What is E2B? E2B https://www.e2b.dev/ is an open-source infrastructure that allows you to run AI-generated code in secure isolated sandboxes in the cloud. To start and control sandboxes, use our JavaScript SDK https://www.npmjs.com/package/e2b or Python SDK https://pypi.org/project/e2b . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/python-sdk/README.md`\n- **Contributing**（project_doc）：Contributing If you want to contribute, open a PR, issue, or start a discussion on our Discord https://discord.gg/dSBY3ms2Qr . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CONTRIBUTING.md`\n- **Integration test template**（project_doc）：$ e2b template build -c \"cd /basic-nextjs-app/ && sudo npm run dev\" 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/js-sdk/tests/integration/template/README.md`\n- **Abort Signal Support**（project_doc）：Add signal: AbortSignal option to JS SDK methods to support cancelling in-flight requests. The signal can be passed to Sandbox.create , Sandbox.connect , sandbox.commands.run , sandbox.files. , volume methods, and other request options. When the signal is aborted, the underlying fetch is aborted and the returned promise rejects with an AbortError . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/abort-signal-support.md`\n- **Releasing e2b cli**（project_doc）：to create a changeset run pnpm run changeset 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`DEV.md`\n- **Feature request**（project_doc）：Is your feature request related to a problem? Please describe. A clear and concise description of what the problem is. Ex. I'm always frustrated when ... 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.github/ISSUE_TEMPLATE/feature_request.md`\n\n## 证据索引\n\n- 共索引 44 条证据。\n\n- **Changesets**（documentation）：in the root of the project. This will create a new changeset in the .changeset folder. 证据：`.changeset/README.md`\n- **Claude**（documentation）：Use pnpm for node and poetry for python to install and update dependencies. Run pnpm run format , pnpm run lint and pnpm run typecheck before committing changes. To re-generate the API client run make codegen in the repository root. Run tests on affected codepaths using pnpm run test . Generate changesets after updating packages/cli, packages/js-sdk, packages/python-sdk. Default credentials are stored in .env.local in the repository root or inside ~/.e2b/config.json. 证据：`CLAUDE.md`\n- **What is E2B?**（documentation）：! E2B SDK Preview /readme-assets/e2b-sdk-light.png gh-light-mode-only ! E2B SDK Preview /readme-assets/e2b-sdk-dark.png gh-dark-mode-only 证据：`README.md`\n- **E2B CLI**（documentation）：This CLI tool allows you to build manager your running E2B sandbox and sandbox templates. Learn more in our documentation https://e2b.dev/docs . 证据：`packages/cli/README.md`\n- **connect-python**（documentation）：🚧 Currently pending an open RFC to be moved into the Connect RPC org https://github.com/connectrpc/connectrpc.com/pull/71 . Please show support. 🚧 证据：`packages/connect-python/README.md`\n- **What is E2B?**（documentation）：--- What is E2B? E2B https://www.e2b.dev/ is an open-source infrastructure that allows you to run AI-generated code in secure isolated sandboxes in the cloud. To start and control sandboxes, use our JavaScript SDK https://www.npmjs.com/package/e2b or Python SDK https://pypi.org/project/e2b . 证据：`packages/js-sdk/README.md`\n- **What is E2B?**（documentation）：What is E2B? E2B https://www.e2b.dev/ is an open-source infrastructure that allows you to run AI-generated code in secure isolated sandboxes in the cloud. To start and control sandboxes, use our JavaScript SDK https://www.npmjs.com/package/e2b or Python SDK https://pypi.org/project/e2b . 证据：`packages/python-sdk/README.md`\n- **Package**（package_manifest）：{ \"name\": \"e2b\", \"private\": true, \"scripts\": { \"version\": \"pnpm changeset version && pnpm run -r postVersion\", \"publish\": \"pnpm changeset publish && pnpm run -r postPublish\", \"test\": \"pnpm test --recursive --if-present\", \"rm-node-modules\": \"find . -name 'node modules' -type d -prune -exec rm -rf '{}' +\", \"pnpm-install-hack\": \"cd packages/js-sdk && sed -i '' 's/\\\"version\\\": \\\". \\\"/\\\"version\\\": \\\"9.9.9\\\"/g' package.json && cd ../.. && pnpm i && git checkout -- packages/js-sdk/package.json\", \"lint\": \"pnpm --if-present --recursive run lint\", \"typecheck\": \"pnpm --if-present --recursive run typecheck\", \"format\": \"pnpm --if-present --recursive run format\", \"changeset\": \"pnpm dlx @changesets/cli\" }… 证据：`package.json`\n- **Contributing**（documentation）：Contributing If you want to contribute, open a PR, issue, or start a discussion on our Discord https://discord.gg/dSBY3ms2Qr . 证据：`CONTRIBUTING.md`\n- **Package**（package_manifest）：{ \"name\": \"@e2b/cli\", \"version\": \"2.10.1\", \"description\": \"CLI for managing e2b sandbox templates\", \"homepage\": \"https://e2b.dev\", \"license\": \"MIT\", \"author\": { \"name\": \"FoundryLabs, Inc.\", \"email\": \"hello@e2b.dev\", \"url\": \"https://e2b.dev\" }, \"bugs\": \"https://github.com/e2b-dev/e2b/issues\", \"repository\": { \"type\": \"git\", \"url\": \"https://github.com/e2b-dev/e2b\", \"directory\": \"packages/cli\" }, \"publishConfig\": { \"access\": \"public\" }, \"keywords\": \"e2b\", \"ai-agents\", \"agents\", \"ai\", \"code-interpreter\", \"sandbox\", \"code\", \"cli\", \"runtime\", \"vm\", \"nodejs\", \"javascript\", \"typescript\" , \"sideEffects\": false, \"scripts\": { \"prepublishOnly\": \"pnpm build\", \"build\": \"tsc --noEmit --skipLibCheck && tsup… 证据：`packages/cli/package.json`\n- **Package**（package_manifest）：{ \"name\": \"e2b\", \"version\": \"2.20.1\", \"description\": \"E2B SDK that give agents cloud environments\", \"homepage\": \"https://e2b.dev\", \"license\": \"MIT\", \"author\": { \"name\": \"FoundryLabs, Inc.\", \"email\": \"hello@e2b.dev\", \"url\": \"https://e2b.dev\" }, \"bugs\": \"https://github.com/e2b-dev/e2b/issues\", \"repository\": { \"type\": \"git\", \"url\": \"https://github.com/e2b-dev/e2b\", \"directory\": \"packages/js-sdk\" }, \"publishConfig\": { \"access\": \"public\" }, \"sideEffects\": false, \"main\": \"dist/index.js\", \"module\": \"dist/index.mjs\", \"types\": \"dist/index.d.ts\", \"scripts\": { \"prepublishOnly\": \"pnpm build\", \"build\": \"tsc --noEmit && tsup\", \"dev\": \"tsup --watch\", \"example\": \"tsx example.mts\", \"test\": \"vitest run\", \"ge… 证据：`packages/js-sdk/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@e2b/python-sdk\", \"private\": true, \"version\": \"2.21.1\", \"scripts\": { \"example\": \"poetry run python example.py\", \"test\": \"poetry run pytest -n 4 --verbose -x\", \"postVersion\": \"poetry version $ pnpm pkg get version --workspaces=false tr -d \\\\\\\" \", \"postPublish\": \"poetry build && poetry config pypi-token.pypi ${PYPI TOKEN} && poetry publish --skip-existing\", \"pretest\": \"poetry install\", \"typecheck\": \"poetry run make typecheck\", \"lint\": \"poetry run make lint\", \"format\": \"poetry run make format\" } } 证据：`packages/python-sdk/package.json`\n- **Integration test template**（documentation）：$ e2b template build -c \"cd /basic-nextjs-app/ && sudo npm run dev\" 证据：`packages/js-sdk/tests/integration/template/README.md`\n- **Package**（package_manifest）：{ \"dependencies\": { \"date-fns\": \"^2.30.0\" } } 证据：`packages/cli/testground/demo-basic/package.json`\n- **License**（source_file）：Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ 证据：`LICENSE`\n- **License**（source_file）：Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files the \"Software\" , to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 证据：`packages/cli/LICENSE`\n- **License**（source_file）：Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ 证据：`packages/connect-python/LICENSE`\n- **License**（source_file）：Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files the \"Software\" , to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 证据：`packages/js-sdk/LICENSE`\n- **License**（source_file）：Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files the \"Software\" , to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 证据：`packages/python-sdk/LICENSE`\n- **Abort Signal Support**（documentation）：Add signal: AbortSignal option to JS SDK methods to support cancelling in-flight requests. The signal can be passed to Sandbox.create , Sandbox.connect , sandbox.commands.run , sandbox.files. , volume methods, and other request options. When the signal is aborted, the underlying fetch is aborted and the returned promise rejects with an AbortError . 证据：`.changeset/abort-signal-support.md`\n- **Releasing e2b cli**（documentation）：to create a changeset run pnpm run changeset 证据：`DEV.md`\n- **Feature Request**（documentation）：Is your feature request related to a problem? Please describe. A clear and concise description of what the problem is. Ex. I'm always frustrated when ... 证据：`.github/ISSUE_TEMPLATE/feature_request.md`\n- **Config**（structured_config）：{ \"$schema\": \"https://unpkg.com/@changesets/config@2.3.1/schema.json\", \"changelog\": \"@changesets/cli/changelog\", \"commit\": false, \"fixed\": , \"ignore\": , \"linked\": , \"access\": \"public\", \"baseBranch\": \"main\", \"updateInternalDependencies\": \"patch\", \"privatePackages\": { \"version\": true, \"tag\": true } } 证据：`.changeset/config.json`\n- **Mcp Server**（structured_config）：{ \"additionalProperties\": false, \"properties\": { \"airtable\": { \"title\": \"Airtable MCP Server\", \"description\": \"Provides AI assistants with direct access to Airtable bases, allowing them to read schemas, query records, and interact with your Airtable data. Supports listing bases, retrieving table structures, and searching through records to help automate workflows and answer questions about your organized data.\", \"required\": \"airtableApiKey\", \"nodeenv\" , \"additionalProperties\": false, \"properties\": { \"airtableApiKey\": { \"type\": \"string\" }, \"nodeenv\": { \"type\": \"string\" } }, \"type\": \"object\", \"x-dockerHubUrl\": \"https://hub.docker.com/mcp/server/airtable-mcp-server/overview\" }, \"aks\": { \"title… 证据：`spec/mcp-server.json`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"target\": \"es2022\", \"module\": \"es2022\", \"lib\": \"es2022\", \"dom\", \"dom.iterable\" , \"allowJs\": true, \"declaration\": true, \"declarationMap\": true, \"moduleResolution\": \"node\", \"sourceMap\": true, \"strict\": true, \"strictNullChecks\": true, \"strictFunctionTypes\": true, \"strictBindCallApply\": true, \"strictPropertyInitialization\": true, \"noImplicitThis\": true, \"alwaysStrict\": true, \"esModuleInterop\": true, \"preserveSymlinks\": true, \"downlevelIteration\": true, \"resolveJsonModule\": true, \"forceConsistentCasingInFileNames\": true, \"allowSyntheticDefaultImports\": true, \"outDir\": \"dist\", \"baseUrl\": \".\", \"rootDirs\": \"src\" , \"paths\": { \"e2b\": \"../js-sdk/src\" } } } 证据：`packages/cli/tsconfig.json`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"outDir\": \"dist\", \"target\": \"es6\", \"lib\": \"dom\", \"ESNext\" , \"sourceMap\": true, \"allowJs\": true, \"skipLibCheck\": true, \"esModuleInterop\": true, \"allowSyntheticDefaultImports\": true, \"strict\": true, \"forceConsistentCasingInFileNames\": true, \"noFallthroughCasesInSwitch\": true, \"moduleResolution\": \"node\", \"resolveJsonModule\": true, \"isolatedModules\": true, \"declaration\": true, }, \"include\": \"src\" , \"exclude\": \"dist\", \"node modules\", \"tsup.config.js\" } 证据：`packages/js-sdk/tsconfig.json`\n- **.editorconfig**（source_file）：root = true .py indent size = 4 证据：`.editorconfig`\n- **.Eslintrc**（source_file）：module.exports = { env: { node: true, browser: true, es6: true, }, extends: 'eslint:recommended', 'plugin:@typescript-eslint/recommended' , parser: '@typescript-eslint/parser', parserOptions: { ecmaVersion: 'latest', sourceType: 'module', }, ignorePatterns: 'dist/', 'node modules/', ' .gen.ts' , plugins: '@typescript-eslint', 'unused-imports' , rules: { '@typescript-eslint/member-ordering': 'error', '@typescript-eslint/ban-ts-comment': 'off', // \"move fast\" mode '@typescript-eslint/no-explicit-any': 'off', // \"move fast\" mode 'linebreak-style': 'error', 'unix' , 'unused-imports/no-unused-imports': 'error', // No double quotes quotes: 'error', 'single', { avoidEscape: true } , // No extra se… 证据：`.eslintrc.cjs`\n- **.gitattributes**（source_file）：packages/python-sdk/e2b/api/client/ linguist-generated=true packages/python-sdk/e2b/envd/filesystem/ linguist-generated=true packages/python-sdk/e2b/envd/process/ linguist-generated=true / .gen.ts linguist-generated=true 证据：`.gitattributes`\n- **Logs**（source_file）：vale-styles .vercel .vscode .DS Store 证据：`.gitignore`\n- **.npmrc**（source_file）：enable-pre-post-scripts=true auto-install-peers=true exclude-links-from-lockfile=true prefer-workspace-packages=false link-workspace-packages=false engine-strict=true 证据：`.npmrc`\n- **imporatant to keep // $HighlightLine comments at the end of the line**（source_file）：imporatant to keep // $HighlightLine comments at the end of the line apps/web/src/code/ 证据：`.prettierignore`\n- **.prettierrc**（source_file）：{ \"singleQuote\": true, \"semi\": false, \"trailingComma\": \"es5\" } 证据：`.prettierrc`\n- **.tool-versions**（source_file）：deno 1.46.3 nodejs 20.19.5 pnpm 9.15.5 python 3.10 poetry 2.1.1 证据：`.tool-versions`\n- **.Vale**（source_file）：Packages = Microsoft, proselint, write-good, alex, Readability, Joblint, Google 证据：`.vale.ini`\n- **These owners will be the default owners for everything in**（source_file）：These owners will be the default owners for everything in the repo. Unless a later match takes precedence. @jakubno @ValentaTomas 证据：`CODEOWNERS`\n- **Makefile**（source_file）：.PHONY: codegen codegen: @echo \"Building codegen image\" docker build -q -t codegen-env . -f codegen.Dockerfile @echo \"Generating code\" docker run -v $$PWD:/workspace codegen-env make generate 证据：`Makefile`\n- **Install Golang deps**（source_file）：Install Golang deps RUN go install github.com/bufbuild/buf/cmd/buf@v1.50.1 && \\ go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.28.1 && \\ go install connectrpc.com/connect/cmd/protoc-gen-connect-go@v1.18.1 证据：`codegen.Dockerfile`\n- **Pnpm Workspace**（source_file）：packages: - packages/ 证据：`pnpm-workspace.yaml`\n- **Openapi Volumecontent**（source_file）：openapi: 3.0.0 info: version: 0.1.0 title: E2B API 证据：`spec/openapi-volumecontent.yml`\n- **Generated code uses security schemas in the alphabetical order.**（source_file）：openapi: 3.0.0 info: version: 0.1.0 title: E2B API 证据：`spec/openapi.yml`\n- **Get directory of this script**（source_file）：Get directory of this script directory = os.path.dirname os.path.abspath file path = os.path.join directory, \"openapi.yml\" 证据：`spec/remove_extra_tags.py`\n- **Supabase**（source_file）：Supabase .branches .temp 证据：`supabase/.gitignore`\n- **A string used to distinguish different Supabase projects on the same host. Defaults to the working**（source_file）：A string used to distinguish different Supabase projects on the same host. Defaults to the working directory name when running supabase init . project id = \"workspace\" 证据：`supabase/config.toml`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`.changeset/README.md`, `CLAUDE.md`, `README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`.changeset/README.md`, `CLAUDE.md`, `README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **Overview**：importance `high`\n - source_paths: README.md, CLAUDE.md, packages/js-sdk/src/index.ts, packages/python-sdk/e2b/__init__.py\n- **Installation**：importance `high`\n - source_paths: packages/js-sdk/package.json, packages/python-sdk/pyproject.toml, packages/cli/package.json\n- **Sandbox Usage**：importance `high`\n - source_paths: packages/js-sdk/src/sandbox/index.ts, packages/js-sdk/src/sandbox/sandboxApi.ts, packages/python-sdk/e2b/sandbox/main.py, packages/python-sdk/e2b/sandbox/sandbox_api.py, packages/python-sdk/e2b/sandbox_async/main.py\n- **JavaScript/TypeScript SDK**：importance `high`\n - source_paths: packages/js-sdk/src/index.ts, packages/js-sdk/src/sandbox/index.ts, packages/js-sdk/src/connectionConfig.ts, packages/js-sdk/src/errors.ts, packages/js-sdk/src/sandbox/commands/index.ts\n- **Python SDK**：importance `high`\n - source_paths: packages/python-sdk/e2b/__init__.py, packages/python-sdk/e2b/sandbox/main.py, packages/python-sdk/e2b/sandbox_async/main.py, packages/python-sdk/e2b/sandbox_sync/main.py, packages/python-sdk/e2b/sandbox/sandbox_api.py\n- **CLI Tool**：importance `medium`\n - source_paths: packages/cli/src/index.ts, packages/cli/src/commands/index.ts, packages/cli/src/commands/auth/index.ts, packages/cli/src/commands/sandbox/index.ts, packages/cli/src/commands/template/index.ts\n- **Sandbox Management**：importance `high`\n - source_paths: packages/js-sdk/src/sandbox/sandboxApi.ts, packages/python-sdk/e2b/sandbox/sandbox_api.py, packages/python-sdk/e2b/api/client/api/sandboxes/post_sandboxes.py, packages/python-sdk/e2b/api/client/api/sandboxes/post_sandboxes_sandbox_id_pause.py, packages/python-sdk/e2b/api/client/api/sandboxes/post_sandboxes_sandbox_id_resume.py\n- **Template System**：importance `high`\n - source_paths: packages/js-sdk/src/template/index.ts, packages/js-sdk/src/template/buildApi.ts, packages/js-sdk/src/template/types.ts, packages/js-sdk/src/template/dockerfileParser.ts, packages/python-sdk/e2b/template/main.py\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `2ac5de2edf6768b9bc93e87762e67b6a44328c99`\n- inspected_files: `pnpm-lock.yaml`, `package.json`, `README.md`, `packages/cli/vitest.config.ts`, `packages/cli/package.json`, `packages/cli/README.md`, `packages/cli/tsconfig.json`, `packages/cli/tsup.config.js`, `packages/connect-python/pyproject.toml`, `packages/connect-python/README.md`, `packages/python-sdk/pyproject.toml`, `packages/python-sdk/package.json`, `packages/python-sdk/README.md`, `packages/python-sdk/example.py`, `packages/js-sdk/package.json`, `packages/js-sdk/README.md`, `packages/js-sdk/tsconfig.json`, `packages/js-sdk/tsup.config.js`, `packages/cli/src/terminal.ts`, `packages/cli/src/user.ts`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：process was not killed when auto paused\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：process was not killed when auto paused\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_66994844a2ec44a784ad5b80307d82e9 | https://github.com/e2b-dev/E2B/issues/1031 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：Closed Port Error\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Closed Port Error\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_33133a8885a44301a7f98b23844205cc | https://github.com/e2b-dev/E2B/issues/907 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：Please add skills to use with any ai agent to use e2b in our project\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Please add skills to use with any ai agent to use e2b in our project\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_8cebd572dbd2485ab6cdbc13733fdee0 | https://github.com/e2b-dev/E2B/issues/1138 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：[Bug]: Incorrect info about webhooks in docs and dashboard\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: Incorrect info about webhooks in docs and dashboard\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_8b25841679fd4eaea5d759a33dfad3b1 | https://github.com/e2b-dev/E2B/issues/1103 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：[Bug]: Sandbox create fails from template, but succeeds without template\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: Sandbox create fails from template, but succeeds without template\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_3ae274a17e7e420ca9f2cd6e7c6105bd | https://github.com/e2b-dev/E2B/issues/1130 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：build status polling timed out\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：build status polling timed out\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_88fc7403d6a44edb8b8d4c9deaff0279 | https://github.com/e2b-dev/E2B/issues/1009 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：Paused sandbox is not persisting the file changes / addition after second time resumed and onward\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Paused sandbox is not persisting the file changes / addition after second time resumed and onward\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_2fc5340254c94ae2931673fede53e25b | https://github.com/e2b-dev/E2B/issues/884 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 社区讨论暴露的待验证问题：[Bug]: torch.compile fails for Gemma3n on pytorch 2.8\n\n- Trigger: [Bug]: torch.compile fails for Gemma3n on pytorch 2.8 ### Your current environment The output of python collect_env.py
```text Your output of `python collect_env.py` here ``` ### 🐛 Describe the bug run ``` vllm serve google/gemma-3n-E2B-it -tp 1 ``` on torch==2.8.0:…\n- Host AI rule: Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。\n- Why it matters: 这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。\n- Evidence: social_signal:github | ssig_3c3209f718cd4d108c88e3bf9d35db24 | https://github.com/vllm-project/vllm/issues/24547 | [Bug]: torch.compile fails for Gemma3n on pytorch 2.8\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:609539715 | https://github.com/e2b-dev/E2B | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 来源证据：When using autoPause in sandbox creation, connect overrides this when resuming the sandbox again\n\n- Trigger: GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：When using autoPause in sandbox creation, connect overrides this when resuming the sandbox again\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_3002fb1e72dd4aa2ab6baed80425d7b2 | https://github.com/e2b-dev/E2B/issues/875 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：e2b-dev/E2B\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：local_cli\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：process was not killed when auto paused（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Closed Port Error（medium）：可能阻塞安装或首次运行。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：Please add skills to use with any ai agent to use e2b in our project（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：[Bug]: Incorrect info about webhooks in docs and dashboard（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：[Bug]: Sandbox create fails from template, but succeeds without template（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/e2b-dev/E2B 项目说明书\n\n生成时间：2026-05-18 03:19:07 UTC\n\n## 目录\n\n- [Overview](#overview)\n- [Installation](#installation)\n- [Sandbox Usage](#sandbox-usage)\n- [JavaScript/TypeScript SDK](#js-sdk)\n- [Python SDK](#python-sdk)\n- [CLI Tool](#cli-tool)\n- [Sandbox Management](#sandbox-management)\n- [Template System](#template-system)\n- [Filesystem and Git Operations](#filesystem-git)\n- [Network Configuration](#network-config)\n\n\n\n## Overview\n\n### 相关页面\n\n相关主题：[Sandbox Usage](#sandbox-usage), [JavaScript/TypeScript SDK](#js-sdk), [Python SDK](#python-sdk)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/e2b-dev/E2B/blob/main/README.md)\n- [packages/js-sdk/README.md](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/README.md)\n- [packages/python-sdk/README.md](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/README.md)\n- [packages/js-sdk/src/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/index.ts)\n- [packages/python-sdk/e2b/__init__.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/__init__.py)\n- [packages/js-sdk/src/template/types.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/template/types.ts)\n- [packages/js-sdk/src/sandbox/sandboxApi.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/sandboxApi.ts)\n- [packages/js-sdk/src/template/readycmd.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/template/readycmd.ts)\n \n\n# Overview\n\nE2B is an open-source infrastructure platform that enables developers to run AI-generated code in secure, isolated cloud-based sandboxes. It provides a unified API layer across multiple programming languages, allowing seamless integration of sandboxed code execution into AI applications, agents, and workflows.\n\n## What is E2B?\n\nE2B addresses the fundamental challenge of safely executing code generated by Large Language Models (LLMs) and AI agents. When AI systems produce code, executing that code directly in production environments poses significant security risks. E2B creates isolated execution environments where AI-generated code can be run safely without affecting the host system.\n\n资料来源：[README.md:1]()\n\n### Core Capabilities\n\n| Capability | Description |\n|------------|-------------|\n| **Secure Sandboxes** | Isolated cloud environments for safe code execution |\n| **Multi-Language SDKs** | Official JavaScript/TypeScript and Python SDKs |\n| **Template System** | Customizable sandbox environments with Dockerfile-like syntax |\n| **Code Interpreter** | Dedicated SDK for AI code execution use cases |\n| **MCP Server Support** | Integration with Model Context Protocol servers |\n| **Volume Management** | Persistent storage and file system operations |\n\n## Architecture Overview\n\nE2B's architecture consists of several interconnected components that work together to provide secure code execution.\n\n```mermaid\ngraph TD\n A[Client Application] --> B[E2B SDK]\n B --> C[API Gateway]\n C --> D[Sandbox Manager]\n D --> E[Isolated Sandbox]\n D --> F[Template Registry]\n E --> G[envd Runtime]\n F --> H[Docker Images]\n \n I[Volume Storage] <--> E\n J[MCP Gateway] --> C\n```\n\n### Key Components\n\n#### Sandboxes\n\nSandboxes are the core execution units in E2B. Each sandbox is an isolated environment based on a template that defines the base image, installed packages, environment variables, and startup commands.\n\n```mermaid\ngraph LR\n A[Sandbox Instance] --> B[Filesystem]\n A --> C[Process Execution]\n A --> D[Network Access]\n A --> E[Volume Mounts]\n```\n\nSandbox configuration options control the execution environment behavior:\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `templateID` | string | required | Template identifier to base the sandbox on |\n| `timeout` | number | 300000ms | Maximum execution time before auto-termination |\n| `secure` | boolean | `true` | Enable security restrictions |\n| `allowInternetAccess` | boolean | `true` | Control network connectivity |\n| `metadata` | object | `{}` | User-defined metadata for the sandbox |\n| `envs` | Record | `{}` | Environment variables to inject |\n\n资料来源：[packages/js-sdk/src/sandbox/sandboxApi.ts:1]()\n\n#### Templates\n\nTemplates define the configuration for sandbox environments. They use a fluent builder pattern to construct sandbox definitions that are then built and deployed to E2B infrastructure.\n\nSupported base images include:\n\n| Method | Description |\n|--------|-------------|\n| `fromBaseImage()` | E2B's default base image (e2bdev/base:latest) |\n| `fromDebianImage(variant?)` | Debian-based image |\n| `fromUbuntuImage(variant?)` | Ubuntu-based image |\n| `fromPythonImage(version?)` | Python runtime image |\n| `fromNodeImage(variant?)` | Node.js runtime image |\n| `fromBunImage(variant?)` | Bun runtime image |\n\n资料来源：[packages/js-sdk/src/template/types.ts:1]()\n\n## SDKs Overview\n\nE2B provides official SDKs for two major programming languages, both offering equivalent functionality through idiomatic API designs.\n\n### JavaScript/TypeScript SDK\n\nThe JavaScript SDK is available on npm and supports both CommonJS and ES modules.\n\n```bash\nnpm install e2b\n```\n\n资料来源：[packages/js-sdk/README.md:1]()\n\n**Installation and Quick Start:**\n\n```typescript\nimport Sandbox from 'e2b'\n\nconst sandbox = await Sandbox.create()\nconst result = await sandbox.commands.run('echo \"Hello from E2B!\"')\nconsole.log(result.stdout) // Hello from E2B!\n```\n\n### Python SDK\n\nThe Python SDK is available on PyPI and supports Python 3.8+.\n\n```bash\npip install e2b\n```\n\n资料来源：[packages/python-sdk/README.md:1]()\n\n**Installation and Quick Start:**\n\n```python\nfrom e2b import Sandbox\n\nwith Sandbox.create() as sandbox:\n result = sandbox.commands.run('echo \"Hello from E2B!\"')\n print(result.stdout) # Hello from E2B!\n```\n\n### Code Interpreter SDK\n\nFor AI applications requiring code execution capabilities (like REPLs or code agents), E2B provides a specialized Code Interpreter SDK.\n\n| SDK | Package | Use Case |\n|-----|---------|----------|\n| JS | `@e2b/code-interpreter` | AI agents, code generators |\n| Python | `e2b-code-interpreter` | AI agents, code generators |\n\n资料来源：[packages/js-sdk/README.md:1]()\n\n```typescript\nimport { Sandbox } from '@e2b/code-interpreter'\n\nconst sandbox = await Sandbox.create()\nconst execution = await sandbox.runCode('x = 1; x += 1; x')\nconsole.log(execution.text) // outputs 2\n```\n\n## Template Builder System\n\nTemplates in E2B use a fluent builder pattern that generates Dockerfile-like instructions. This approach provides flexibility while maintaining simplicity.\n\n### Instruction Types\n\n| Instruction | Description |\n|-------------|-------------|\n| `run_cmd()` / `RUN` | Execute shell commands during build |\n| `copy()` / `COPY` | Copy files into the sandbox |\n| `set_envs()` / `ENV` | Set environment variables |\n| `add_mcp_server()` | Install MCP servers via mcp-gateway |\n| `apt_install()` | Install APT packages |\n\n资料来源：[packages/python-sdk/e2b/template/main.py:1]()\n\n### Template Lifecycle\n\n```mermaid\nstateDiagram-v2\n [*] --> TemplateBuilder: Create Template\n TemplateBuilder --> TemplateBuilder: Add Instructions\n TemplateBuilder --> TemplateBuilder: Configure Start Command\n TemplateBuilder --> TemplateFinal: set_start_cmd()\n TemplateFinal --> Building: Template.build()\n Building --> BuildInfo: Success\n Building --> Error: Failure\n BuildInfo --> [*]\n Error --> [*]\n```\n\n### Ready Commands\n\nReady commands determine when a sandbox is considered fully initialized and ready to accept requests:\n\n| Function | Implementation | Use Case |\n|----------|---------------|----------|\n| `waitForURL(url, statusCode)` | `curl` + `grep` | HTTP service health checks |\n| `waitForProcess(name)` | `pgrep` | Daemon process verification |\n| `waitForFile(path)` | shell test | File system readiness |\n\n资料来源：[packages/js-sdk/src/template/readycmd.ts:1]()\n\n## File System Operations\n\nE2B provides comprehensive file system operations within sandboxes through the `Filesystem` API.\n\n### Supported Read Formats\n\n| Format | Return Type | Use Case |\n|--------|-------------|----------|\n| `text` (default) | `string` | Source code, configs |\n| `bytes` | `Uint8Array` | Binary files |\n| `blob` | `Blob` | Web-compatible binary |\n| `stream` | `ReadableStream` | Large file handling |\n\nFilesystem operations support gzip compression via the `gzip` option to reduce network transfer for large files.\n\n资料来源：[packages/js-sdk/src/sandbox/filesystem/index.ts:1]()\n\n## Command Execution\n\nCommands executed within sandboxes return structured results containing stdout, stderr, and exit codes.\n\n### Command Result Properties\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `stdout` | string | Standard output content |\n| `stderr` | string | Standard error content |\n| `exitCode` | number | Process exit code (0 = success) |\n| `error` | string | Error message if execution failed |\n\nThe `CommandHandle.wait()` method throws a `CommandExitError` when the exit code is non-zero, enabling automatic error propagation in async workflows.\n\n资料来源：[packages/js-sdk/src/sandbox/commands/commandHandle.ts:1]()\n\n## Volume System\n\nVolumes provide persistent storage that can be mounted into sandboxes. They are managed through the Volume API which supports CRUD operations on files and directories.\n\n### Volume Mount Configuration\n\n```typescript\nopts.volumeMounts = {\n '/mount/path': 'volume-name'\n}\n```\n\nEach mount maps a volume name to a path within the sandbox filesystem.\n\n资料来源：[packages/js-sdk/src/sandbox/sandboxApi.ts:1]()\n\n### Volume Read Operations\n\n| Format | API Method | Return Type |\n|--------|------------|-------------|\n| text | `readFile(path, { format: 'text' })` | `string` |\n| bytes | `readFile(path, { format: 'bytes' })` | `Uint8Array` |\n| blob | `readFile(path, { format: 'blob' })` | `Blob` |\n| stream | `readFile(path, { format: 'stream' })` | `ReadableStream` |\n\n资料来源：[packages/js-sdk/src/volume/index.ts:1]()\n\n## Authentication\n\nAll E2B SDKs require API key authentication. The API key should be set as an environment variable before initializing SDK clients.\n\n```bash\nexport E2B_API_KEY=e2b_your_api_key_here\n```\n\nAPI keys can be obtained from the E2B dashboard at https://e2b.dev/dashboard?tab=keys.\n\n## Next Steps\n\n| Resource | Description |\n|----------|-------------|\n| [JavaScript SDK Guide](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/README.md) | Detailed JS/TS SDK documentation |\n| [Python SDK Guide](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/README.md) | Detailed Python SDK documentation |\n| [E2B Cookbook](https://github.com/e2b-dev/e2b-cookbook) | Example projects with various LLMs |\n| [Official Documentation](https://www.e2b.dev/docs) | Full platform documentation |\n\n---\n\n\n\n## Installation\n\n### 相关页面\n\n相关主题：[JavaScript/TypeScript SDK](#js-sdk), [Python SDK](#python-sdk), [CLI Tool](#cli-tool)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/js-sdk/package.json](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/package.json)\n- [packages/python-sdk/pyproject.toml](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/pyproject.toml)\n- [packages/cli/package.json](https://github.com/e2b-dev/E2B/blob/main/packages/cli/package.json)\n- [packages/python-sdk/README.md](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/README.md)\n- [packages/js-sdk/README.md](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/README.md)\n \n\n# Installation\n\nThis guide covers how to install and configure the E2B SDKs for different programming languages. E2B provides two official SDKs: a Python SDK and a JavaScript/TypeScript SDK, both enabling developers to run AI-generated code in secure isolated sandboxes in the cloud.\n\n## Prerequisites\n\nBefore installing any E2B SDK, ensure you have:\n\n| Requirement | Description |\n|-------------|-------------|\n| **E2B Account** | Sign up at [e2b.dev](https://www.e2b.dev) |\n| **API Key** | Obtain from [E2B Dashboard](https://www.e2b.dev/dashboard?tab=keys) |\n| **Runtime** | Python 3.x or Node.js 18+ depending on SDK |\n\nYou must set the `E2B_API_KEY` environment variable with your API key before using the SDK:\n\n```bash\nexport E2B_API_KEY=e2b_***\n```\n\n## SDK Overview\n\nE2B provides multiple SDK packages depending on your use case:\n\n| SDK Package | Purpose | Language |\n|-------------|---------|----------|\n| `e2b` | Core sandbox functionality | Python |\n| `e2b` | Core sandbox functionality | JavaScript/TypeScript |\n| `@e2b/code-interpreter` | Code execution sandbox | Python |\n| `@e2b/code-interpreter` | Code execution sandbox | JavaScript/TypeScript |\n| `e2b` (CLI) | Command-line interface | Node.js |\n\n## Installing the Python SDK\n\n### Core SDK\n\nInstall the core E2B Python SDK using pip:\n\n```bash\npip install e2b\n```\n\nThe SDK is published to PyPI and can be installed in any Python environment with pip support. The package includes all necessary dependencies for sandbox management, command execution, and file operations.\n\n### Code Interpreter SDK\n\nFor running AI-generated code in a sandboxed environment:\n\n```bash\npip install e2b-code-interpreter\n```\n\nThis specialized SDK provides enhanced code execution capabilities with support for multiple programming languages and automatic dependency resolution.\n\n## Installing the JavaScript/TypeScript SDK\n\n### Core SDK\n\nInstall the E2B JavaScript SDK using npm:\n\n```bash\nnpm i e2b\n```\n\nThe JavaScript SDK supports both CommonJS and ESM module formats. It is written in TypeScript and includes full type definitions out of the box.\n\n### Code Interpreter SDK\n\nFor JavaScript-based code execution:\n\n```bash\nnpm i @e2b/code-interpreter\n```\n\n## Installing the CLI\n\nThe E2B CLI provides command-line access to template management and sandbox operations.\n\n### Installation via npm\n\n```bash\nnpm i e2b\n```\n\n### Installation via npx\n\nFor one-time usage without global installation:\n\n```bash\nnpx e2b \n```\n\n## Package Dependencies\n\n### Python SDK Dependencies\n\nThe Python SDK requires the following runtime dependencies:\n\n- `httpx` - HTTP client for API communication\n- Python 3.8+ compatible\n\n### JavaScript SDK Dependencies\n\nThe JavaScript SDK requires:\n\n- Node.js 18 or higher\n- Browser environment support (for client-side usage)\n\n## Verifying Installation\n\nAfter installation, verify that the SDK is correctly installed by checking the version or importing the package:\n\n### Python Verification\n\n```python\nimport e2b\nprint(e2b.__version__)\n```\n\n### JavaScript Verification\n\n```javascript\nimport Sandbox from 'e2b'\nconsole.log(Sandbox)\n```\n\n## Environment Configuration\n\n### Required Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `E2B_API_KEY` | Yes | Your E2B API key for authentication |\n\n### Optional Configuration\n\nThe SDKs support additional configuration options passed during client initialization:\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `timeout` | number | varies | Maximum request timeout in seconds |\n| `verify_ssl` | boolean | true | Whether to verify SSL certificates |\n| `follow_redirects` | boolean | false | Whether to follow HTTP redirects |\n| `base_url` | string | E2B API | Custom API endpoint URL |\n\n## Quick Start After Installation\n\nOnce installed, you can create and use sandboxes:\n\n### Python Example\n\n```python\nfrom e2b import Sandbox\n\nwith Sandbox.create() as sandbox:\n result = sandbox.commands.run('echo \"Hello from E2B!\"')\n print(result.stdout) # Hello from E2B!\n```\n\n### JavaScript/TypeScript Example\n\n```typescript\nimport Sandbox from 'e2b'\n\nconst sandbox = await Sandbox.create()\nconst result = await sandbox.commands.run('echo \"Hello from E2B!\"')\nconsole.log(result.stdout) // Hello from E2B!\n```\n\n### Code Interpreter Example (Python)\n\n```python\nfrom e2b_code_interpreter import Sandbox\n\nwith Sandbox.create() as sandbox:\n execution = sandbox.run_code(\"x = 1; x += 1; x\")\n print(execution.text) # outputs 2\n```\n\n## Installation from Source\n\nFor development or custom builds, you can install from source:\n\n```bash\n# Clone the repository\ngit clone https://github.com/e2b-dev/E2B.git\ncd E2B\n\n# Install Python SDK from source\ncd packages/python-sdk\npip install -e .\n\n# Install JavaScript SDK from source\ncd ../js-sdk\nnpm install\n```\n\n## Troubleshooting\n\n### Common Installation Issues\n\n| Issue | Solution |\n|-------|----------|\n| `ModuleNotFoundError` | Ensure pip/npm is updated and try reinstalling |\n| API key errors | Verify `E2B_API_KEY` environment variable is set correctly |\n| Network timeouts | Check firewall/proxy settings for outbound HTTPS connections |\n| Version conflicts | Use virtual environments or ensure Node.js version compatibility |\n\n### Getting Help\n\nIf installation issues persist:\n\n- Check [E2B Documentation](https://e2b.dev/docs)\n- Contact support at [https://e2b.dev/docs/support](https://e2b.dev/docs/support)\n- Visit the [E2B Cookbook](https://github.com/e2b-dev/e2b-cookbook) for examples\n\n---\n\n\n\n## Sandbox Usage\n\n### 相关页面\n\n相关主题：[Sandbox Management](#sandbox-management), [Filesystem and Git Operations](#filesystem-git), [Network Configuration](#network-config)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/js-sdk/src/sandbox/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/index.ts)\n- [packages/js-sdk/src/sandbox/sandboxApi.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/sandboxApi.ts)\n- [packages/js-sdk/src/api/schema.gen.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/api/schema.gen.ts)\n- [packages/python-sdk/e2b/sandbox_async/sandbox_api.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_async/sandbox_api.py)\n- [packages/python-sdk/e2b/sandbox_async/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_async/main.py)\n- [packages/python-sdk/e2b/sandbox_sync/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_sync/main.py)\n- [packages/python-sdk/e2b/template/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template/main.py)\n- [packages/cli/src/commands/sandbox/info.ts](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/sandbox/info.ts)\n- [README.md](https://github.com/e2b-dev/E2B/blob/main/README.md)\n \n\n# Sandbox Usage\n\n## Overview\n\nA **Sandbox** in E2B is a secure, isolated cloud environment that allows you to execute AI-generated code safely. Sandboxes provide a controlled runtime environment with configurable resources, network settings, and lifecycle management. They are created from **sandbox templates** that define the base configuration, installed dependencies, and startup behavior of the environment.\n\nSandboxes are the core execution unit in E2B, providing:\n- Isolated execution of untrusted code\n- Configurable CPU and memory resources\n- Network access control\n- File system operations\n- Terminal/PTY access\n- Git operations\n\n资料来源：[README.md:1-20](https://github.com/e2b-dev/E2B/blob/main/README.md)\n\n## Architecture\n\n```mermaid\ngraph TD\n A[Developer/AI Agent] -->|Creates Sandbox| B[E2B API]\n B -->|Template Config| C[Sandbox Instance]\n C -->|Provides| D[Filesystem API]\n C -->|Provides| E[Commands API]\n C -->|Provides| F[PTY/Terminal API]\n C -->|Provides| G[Git API]\n C -->|Manages| H[Lifecycle & Timeout]\n \n I[Template Definition] -->|Defines base image| C\n J[Resource Config] -->|CPU/Memory| C\n K[Network Config] -->|Internet access| C\n```\n\n## Creating a Sandbox\n\n### JavaScript/TypeScript SDK\n\n#### Create with default template\n\n```typescript\nimport Sandbox from 'e2b'\n\nconst sandbox = await Sandbox.create()\nconst result = await sandbox.commands.run('echo \"Hello from E2B!\"')\nconsole.log(result.stdout) // Hello from E2B!\n```\n\n资料来源：[packages/js-sdk/src/sandbox/index.ts:80-100](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/index.ts)\n\n#### Create with specific template\n\n```typescript\nconst sandbox = await Sandbox.create('my-custom-template')\n```\n\n#### Create with options\n\n```typescript\nconst sandbox = await Sandbox.create({\n template: 'my-template',\n metadata: { user: 'alice', app: 'production' },\n envs: { NODE_ENV: 'production' },\n timeoutMs: 60000,\n})\n```\n\n资料来源：[packages/js-sdk/src/sandbox/index.ts:95-130](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/index.ts)\n\n### Python SDK\n\n#### Async usage\n\n```python\nimport asyncio\nfrom e2b import Sandbox\n\nasync def main():\n sandbox = await Sandbox.create()\n result = sandbox.commands.run('echo \"Hello from E2B!\"')\n print(result.stdout) # Hello from E2B!\n\nasyncio.run(main())\n```\n\n#### Sync usage\n\n```python\nfrom e2b import Sandbox\n\nwith Sandbox.create() as sandbox:\n result = sandbox.commands.run('echo \"Hello from E2B!\"')\n print(result.stdout) # Hello from E2B!\n```\n\n资料来源：[README.md:30-50](https://github.com/e2b-dev/E2B/blob/main/README.md)\n\n## Sandbox Options\n\n### Configuration Parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `template` | `string` | `'base'` | Sandbox template name or ID. Use `'mcp-gateway'` when `mcp` option is set |\n| `metadata` | `Record` | `{}` | Custom metadata for the sandbox |\n| `envs` | `Record` | `{}` | Custom environment variables for the sandbox |\n| `timeoutMs` | `number` | varies | Timeout in milliseconds (max 24h for Pro, 1h for Hobby) |\n| `mcp` | `boolean` | `false` | Enable MCP gateway support |\n| `onTimeout` | `'pause' \\| 'kill'` | `'pause'` | Action on sandbox timeout |\n| `autoResume` | `boolean` | `false` | Auto-resume paused sandbox (requires `onTimeout: 'pause'`) |\n| `cpuCount` | `number` | `2` | Number of CPU cores |\n| `memoryMB` | `number` | `512` | Memory in MiB (must be even) |\n| `allowInternetAccess` | `boolean` | `true` | Enable/disable internet access |\n| `network` | `boolean \\| SandboxNetworkOpts` | `true` | Network configuration |\n| `volumeMounts` | `Array<{name, path}>` | `[]` | Volume mounts |\n\n资料来源：[packages/js-sdk/src/sandbox/sandboxApi.ts:50-120](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/sandboxApi.ts)\n资料来源：[packages/python-sdk/e2b/sandbox_async/sandbox_api.py:1-50](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_async/sandbox_api.py)\n\n### Network Configuration\n\n```typescript\nconst sandbox = await Sandbox.create({\n network: true, // Full network access (default)\n // Or with custom configuration:\n network: {\n timeoutMs: 30000,\n }\n})\n```\n\n### Resource Configuration\n\n```typescript\nconst sandbox = await Sandbox.create({\n cpuCount: 4, // Number of CPUs (default: 2)\n memoryMB: 1024, // Memory in MiB (default: 512, must be even)\n})\n```\n\n### Lifecycle Configuration\n\n```typescript\nconst sandbox = await Sandbox.create({\n timeoutMs: 3600000, // 1 hour max\n lifecycle: {\n onTimeout: 'pause', // Pause instead of kill\n autoResume: true, // Auto-resume when accessed\n }\n})\n```\n\n资料来源：[packages/js-sdk/src/sandbox/sandboxApi.ts:40-70](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/sandboxApi.ts)\n\n## Sandbox API Response\n\nWhen a sandbox is created, the API returns a `SandboxInfo` object containing:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `sandboxId` | `string` | Unique sandbox identifier |\n| `sandboxDomain` | `string` | Domain name for the sandbox |\n| `envdVersion` | `string` | Version of envd running in sandbox |\n| `envdAccessToken` | `string` | Token for envd API authentication |\n| `trafficAccessToken` | `string` | Token for traffic authentication |\n| `templateId` | `string` | ID of the template used |\n| `name` | `string` | Sandbox alias/name |\n| `startedAt` | `Date` | Sandbox start time |\n| `endAt` | `Date` | Sandbox expiration date |\n| `state` | `'running' \\| 'paused'` | Current sandbox state |\n| `cpuCount` | `number` | Number of CPUs allocated |\n| `memoryMB` | `number` | Memory allocated in MiB |\n| `metadata` | `Record` | Custom metadata |\n| `allowInternetAccess` | `boolean` | Internet access setting |\n| `lifecycle` | `SandboxInfoLifecycle` | Lifecycle configuration |\n| `volumeMounts` | `Array<{name, path}>` | Mounted volumes |\n\n资料来源：[packages/js-sdk/src/api/schema.gen.ts:1-80](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/api/schema.gen.ts)\n资料来源：[packages/js-sdk/src/sandbox/sandboxApi.ts:200-280](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/sandboxApi.ts)\n\n## Sandbox State Machine\n\n```mermaid\nstateDiagram-v2\n [*] --> Creating: Sandbox.create()\n Creating --> Running: Sandbox ready\n Running --> Paused: Timeout reached (if onTimeout: pause)\n Running --> Killed: Timeout reached (if onTimeout: kill)\n Paused --> Running: Sandbox accessed\n Paused --> Killed: Timeout reached\n Running --> [*]: sandbox.kill()\n Paused --> [*]: sandbox.kill()\n Killed --> [*]: Sandbox terminated\n```\n\n## Sandbox Instances\n\n### JavaScript SDK Instance\n\nThe `Sandbox` class provides the following APIs:\n\n| API | Description |\n|-----|-------------|\n| `sandbox.filesystem` | File system operations (upload, download, list, etc.) |\n| `sandbox.commands` | Execute shell commands |\n| `sandbox.pty` | Terminal/PTY access |\n| `sandbox.git` | Git operations |\n\n```typescript\nconst sandbox = await Sandbox.create()\n\n// File operations\nawait sandbox.filesystem.write('/app/main.py', 'print(\"hello\")')\nconst content = await sandbox.filesystem.read('/app/main.py')\n\n// Run commands\nconst result = await sandbox.commands.run('python /app/main.py')\n\n// Terminal access\nconst pty = await sandbox.pty.start({ cmd: 'bash' })\n```\n\n资料来源：[packages/js-sdk/src/sandbox/index.ts:130-180](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/index.ts)\n\n### Python SDK Instance\n\n```python\nsandbox = await Sandbox.create()\n\n# File operations\nawait sandbox.filesystem.write('/app/main.py', 'print(\"hello\")')\n\n# Run commands\nresult = sandbox.commands.run('python /app/main.py')\n\n# Cleanup\nawait sandbox.kill()\n```\n\nOr with sync context manager:\n\n```python\nwith Sandbox.create() as sandbox:\n result = sandbox.commands.run('echo \"Hello\"')\n```\n\n## Sandbox Metrics\n\nSandbox resource usage can be monitored through the metrics API:\n\n| Metric | Type | Description |\n|--------|------|-------------|\n| `timestamp` | `Date` | Timestamp of metrics |\n| `cpuUsedPct` | `number` | CPU usage percentage |\n| `cpuCount` | `number` | Number of CPU cores |\n| `memUsed` | `number` | Memory used in bytes |\n| `memTotal` | `number` | Total memory in bytes |\n| `diskUsed` | `number` | Used disk space in bytes |\n| `diskTotal` | `number` | Total disk space in bytes |\n\n资料来源：[packages/js-sdk/src/sandbox/sandboxApi.ts:250-300](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/sandboxApi.ts)\n\n## CLI Commands\n\n### List Sandboxes\n\n```bash\ne2b sandbox list\n```\n\n### Get Sandbox Info\n\n```bash\ne2b sandbox info \n# or\ne2b sandbox in \n```\n\nOptions:\n- `-f, --format ` - Output format (json, pretty)\n\nThe info command displays:\n\n| Field | Label |\n|-------|-------|\n| `sandboxId` | Sandbox ID |\n| `templateId` | Template ID |\n| `name` | Alias |\n| `startedAt` | Started at |\n| `endAt` | End at |\n| `state` | State |\n| `cpuCount` | vCPUs |\n| `memoryMB` | RAM MiB |\n| `envdVersion` | Envd version |\n| `allowInternetAccess` | Internet access |\n| `lifecycle` | Lifecycle |\n| `network` | Network |\n| `sandboxDomain` | Sandbox domain |\n| `metadata` | Metadata |\n\n资料来源：[packages/cli/src/commands/sandbox/info.ts:1-60](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/sandbox/info.ts)\n\n### Create Sandbox Template\n\n```bash\ne2b template create \n```\n\nOptions:\n- `-p, --path ` - Path to template directory\n- `-d, --dockerfile ` - Custom Dockerfile name\n- `-c, --cmd ` - Command executed when sandbox starts\n- `--ready-cmd ` - Command that must exit 0 for sandbox to be ready\n- `--cpu-count ` - Number of CPUs (default: 2)\n- `--memory-mb ` - Memory in MB (default: 512, must be even)\n- `--no-cache` - Skip cache when building\n\n### Build Sandbox Template\n\n```bash\ne2b template build [template-id]\n# or\ne2b template bd [template-id]\n```\n\nOptions:\n- `-p, --path ` - Path to template directory\n- `-d, --dockerfile ` - Custom Dockerfile name\n- `-n, --name ` - Template name\n- `-c, --cmd ` - Command executed when sandbox starts\n- `--ready-cmd ` - Command that must exit 0\n- `--cpu-count ` - Number of CPUs\n- `--memory-mb ` - Memory in MB\n- `--build-arg ` - Build arguments\n- `--no-cache` - Skip cache when building\n\n资料来源：[packages/cli/src/commands/template/create.ts:1-100](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/template/create.ts)\n资料来源：[packages/cli/src/commands/template/build.ts:1-100](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/template/build.ts)\n\n## Beta Features\n\n### MCP Gateway\n\nEnable MCP (Model Context Protocol) gateway support:\n\n```typescript\nconst sandbox = await Sandbox.betaCreate({\n mcp: true,\n // Uses 'mcp-gateway' template by default\n})\n```\n\n### Dev Container Support\n\nTemplates can use devcontainer configuration:\n\n```typescript\ntemplate\n .gitClone('https://myrepo.com/project.git', '/my-devcontainer')\n .betaDevContainerPrebuild('/my-devcontainer')\n .betaSetDevContainerStart('/my-devcontainer')\n```\n\n资料来源：[packages/js-sdk/src/sandbox/index.ts:40-80](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/index.ts)\n资料来源：[packages/js-sdk/src/template/types.ts:1-50](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/template/types.ts)\n\n## Timeout and Lifecycle Management\n\n### Maximum Timeout Limits\n\n| User Tier | Maximum Timeout |\n|-----------|-----------------|\n| Pro | 24 hours (86,400,000 ms) |\n| Hobby | 1 hour (3,600,000 ms) |\n\n### Lifecycle Options\n\n```typescript\n// Option 1: Pause sandbox on timeout\nconst sandbox = await Sandbox.create({\n timeoutMs: 3600000,\n lifecycle: {\n onTimeout: 'pause',\n autoResume: true, // Can auto-resume when accessed\n }\n})\n\n// Option 2: Kill sandbox on timeout\nconst sandbox = await Sandbox.create({\n timeoutMs: 3600000,\n lifecycle: {\n onTimeout: 'kill', // Sandbox is terminated\n }\n})\n```\n\nWhen a sandbox is paused, accessing it again will automatically resume it, allowing you to continue where you left off (with some limitations based on the template).\n\n资料来源：[packages/js-sdk/src/sandbox/sandboxApi.ts:20-60](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/sandboxApi.ts)\n\n## Best Practices\n\n1. **Always clean up resources**: Use context managers or explicitly call `kill()` to terminate sandboxes when done.\n\n2. **Set appropriate timeouts**: Match the timeout to your workload. Shorter timeouts are more cost-effective for quick tasks.\n\n3. **Use metadata for tracking**: Add meaningful metadata to easily identify sandboxes in listings.\n\n4. **Handle errors gracefully**: Catch exceptions for sandbox creation and command execution.\n\n5. **Use pause lifecycle for interactive sessions**: When you need to resume work later, use `onTimeout: 'pause'` with `autoResume: true`.\n\n6. **Configure resources appropriately**: Allocate CPU and memory based on your actual workload requirements.\n\n---\n\n\n\n## JavaScript/TypeScript SDK\n\n### 相关页面\n\n相关主题：[Python SDK](#python-sdk), [CLI Tool](#cli-tool), [Sandbox Usage](#sandbox-usage)\n\n\nRelated Source Files
\n\nThe following source files were used to generate this documentation:\n\n- [packages/js-sdk/src/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/index.ts)\n- [packages/js-sdk/src/sandbox/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/index.ts)\n- [packages/js-sdk/src/connectionConfig.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/connectionConfig.ts)\n- [packages/js-sdk/src/errors.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/errors.ts)\n- [packages/js-sdk/src/sandbox/commands/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/commands/index.ts)\n- [packages/js-sdk/src/sandbox/filesystem/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/filesystem/index.ts)\n- [packages/js-sdk/src/sandbox/network.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/network.ts)\n- [packages/js-sdk/src/volume/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/volume/index.ts)\n- [packages/js-sdk/tsup.config.js](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/tsup.config.js)\n \n\n# JavaScript/TypeScript SDK\n\n## Overview\n\nThe E2B JavaScript/TypeScript SDK (`e2b`) is an official client library that enables developers to interact with E2B's cloud-based sandbox infrastructure for running AI-generated code in secure, isolated environments. The SDK provides a programmatic interface to create, manage, and communicate with sandboxes, as well as to work with templates and volumes. 资料来源：[packages/js-sdk/README.md]()\n\n### Key Capabilities\n\nThe SDK supports multiple runtime environments including Node.js and browser applications, offering a unified API for sandbox operations. Developers can spawn isolated sandboxes, execute commands, manage files, handle network communications, and mount persistent storage volumes through a well-structured TypeScript interface. 资料来源：[packages/js-sdk/src/api/metadata.ts]()\n资料来源：[packages/js-sdk/tsup.config.js]()\n\n### Package Configuration\n\nThe SDK is published to npm under the package name `e2b` and includes both ESM and CommonJS formats for maximum compatibility. 资料来源：[packages/js-sdk/README.md]()\n\n```json\n{\n \"name\": \"e2b\",\n \"version\": \"^2.19.3\",\n \"main\": \"./dist/index.js\",\n \"module\": \"./dist/index.mjs\",\n \"types\": \"./dist/index.d.ts\"\n}\n```\n\n## Architecture Overview\n\nThe SDK architecture follows a modular design pattern with distinct layers for API communication, sandbox management, and utility functions. 资料来源：[packages/js-sdk/src/index.ts]()\n\n```mermaid\ngraph TD\n A[Client Application] --> B[SDK Entry Point
packages/js-sdk/src/index.ts]\n B --> C[Sandbox Manager
sandbox/index.ts]\n B --> D[Connection Config
connectionConfig.ts]\n B --> E[Error Handling
errors.ts]\n C --> F[Filesystem API
filesystem/index.ts]\n C --> G[Commands API
commands/index.ts]\n C --> H[Network API
network.ts]\n C --> I[Volume API
volume/index.ts]\n D --> J[E2B API Server]\n J --> K[Sandbox Instances]\n```\n\n### Core Components\n\n| Component | File Location | Purpose |\n|-----------|---------------|---------|\n| Entry Point | `src/index.ts` | Exports all public APIs |\n| Sandbox Manager | `src/sandbox/index.ts` | Manages sandbox lifecycle |\n| Connection Config | `src/connectionConfig.ts` | Handles API configuration and authentication |\n| Error Handling | `src/errors.ts` | Defines SDK-specific error types |\n| Filesystem | `src/sandbox/filesystem/index.ts` | File operations within sandboxes |\n| Commands | `src/sandbox/commands/index.ts` | Execute commands in sandboxes |\n| Network | `src/sandbox/network.ts` | Network configuration and proxies |\n| Volume | `src/volume/index.ts` | Persistent storage management |\n\n## Installation and Setup\n\n### Prerequisites\n\n- Node.js 18 or higher\n- An E2B API key\n\n### Installation\n\n```bash\nnpm install e2b\n```\n\n### Environment Configuration\n\nThe SDK automatically reads the `E2B_API_KEY` environment variable for authentication. You can also configure the API key programmatically through the connection configuration. 资料来源：[packages/js-sdk/src/api/metadata.ts]()\n\n```typescript\nimport { E2B } from 'e2b'\n\n// SDK automatically reads E2B_API_KEY from environment\nconst client = new E2B()\n```\n\n### Runtime Detection\n\nThe SDK detects the runtime environment and sets appropriate headers for API requests. It supports Node.js, Deno, and browser environments. 资料来源：[packages/js-sdk/src/api/metadata.ts]()\n\n```typescript\n// Runtime detection in metadata.ts\nexport const defaultHeaders = {\n browser: (typeof window !== 'undefined' && platform.name) || 'unknown',\n lang: 'js',\n lang_version: runtimeVersion,\n package_version: version,\n publisher: 'e2b',\n sdk_runtime: runtime,\n system: platform.os?.family || 'unknown',\n}\n```\n\n## Sandbox Management\n\nThe Sandbox class is the primary interface for interacting with E2B sandboxes. It provides methods for lifecycle management, file operations, command execution, and network configuration. 资料来源：[packages/js-sdk/src/sandbox/index.ts]()\n\n### Creating a Sandbox\n\n```typescript\nimport { E2B } from 'e2b'\n\nconst client = new E2B()\n\n// Create a sandbox from a template\nconst sandbox = await client.createSandbox({\n template: 'base',\n metadata: { userId: '12345' }\n})\n\nconsole.log('Sandbox ID:', sandbox.id)\nconsole.log('Sandbox URL:', sandbox.url)\n```\n\n### Sandbox Configuration\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `template` | `string` | Template ID to use for the sandbox |\n| `timeout` | `number` | Timeout in milliseconds |\n| `metadata` | `Record` | Custom metadata for filtering |\n| `aliases` | `string[]` | Alternative names for the sandbox |\n\n### Sandbox Lifecycle\n\n```mermaid\nstateDiagram-v2\n [*] --> Created: client.createSandbox()\n Created --> Starting: sandbox.start()\n Starting --> Running: sandbox ready\n Running --> Stopping: sandbox.kill() or timeout\n Stopping --> Stopped: cleanup complete\n Stopped --> [*]\n \n Running --> Error: exception\n Error --> [*]\n```\n\n### Stopping a Sandbox\n\nAlways ensure proper cleanup by stopping sandboxes when they are no longer needed:\n\n```typescript\ntry {\n const sandbox = await client.createSandbox({ template: 'base' })\n \n // Perform operations...\n \n await sandbox.kill()\n} finally {\n // Sandbox is now terminated\n}\n```\n\n## Filesystem Operations\n\nThe SDK provides comprehensive filesystem operations through the filesystem module, enabling reading, writing, and managing files within sandboxes. 资料来源：[packages/js-sdk/src/sandbox/filesystem/index.ts]()\n\n### File Operations\n\n| Method | Description |\n|--------|-------------|\n| `write(path, content)` | Write content to a file |\n| `read(path)` | Read file content |\n| `list(path)` | List directory contents |\n| `mkdir(path)` | Create a directory |\n| `remove(path)` | Remove a file or directory |\n| `exists(path)` | Check if path exists |\n\n### Reading Files\n\n```typescript\nconst content = await sandbox.filesystem.read('/app/data.json')\nconsole.log('File content:', content)\n```\n\n### Writing Files\n\n```typescript\nawait sandbox.filesystem.write('/app/output.txt', 'Hello, E2B!')\n```\n\n### Listing Directory Contents\n\n```typescript\nconst files = await sandbox.filesystem.list('/app')\nconsole.log('Files:', files)\n```\n\n## Command Execution\n\nExecute shell commands within the sandbox environment using the commands API. This is essential for running build scripts, installing packages, and performing system operations. 资料来源：[packages/js-sdk/src/sandbox/commands/index.ts]()\n\n### Running Commands\n\n```typescript\nconst result = await sandbox.commands.run('ls -la /app')\n\nconsole.log('Exit code:', result.exitCode)\nconsole.log('Stdout:', result.stdout)\nconsole.log('Stderr:', result.stderr)\n```\n\n### Command Options\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `timeout` | `number` | Command timeout in milliseconds |\n| `envVars` | `Record` | Environment variables |\n| `user` | `string` | User to run command as |\n\n### Streaming Command Output\n\nFor long-running commands, you can stream output:\n\n```typescript\nconst process = sandbox.commands.runStreaming('npm install')\n\nprocess.stdout.on('data', (data) => {\n console.log('Output:', data.toString())\n})\n\nconst exitCode = await process.exitCode\n```\n\n## Network Configuration\n\nThe network module provides configuration for network proxies, DNS settings, and sandbox connectivity options. 资料来源：[packages/js-sdk/src/sandbox/network.ts]()\n\n### Network Settings\n\n```typescript\nconst sandbox = await client.createSandbox({\n template: 'base',\n network: true // Enable networking\n})\n```\n\n### Available Network Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `network` | `boolean` | `true` | Enable/disable network access |\n| `dns` | `string[]` | System DNS | Custom DNS servers |\n\n## Volume Management\n\nVolumes provide persistent storage that survives sandbox restarts. They are useful for maintaining state across sandbox sessions. 资料来源：[packages/js-sdk/src/volume/index.ts]()\n\n### Creating and Mounting Volumes\n\n```typescript\n// Create a volume\nconst volume = await client.volumes.create({\n name: 'my-data-volume'\n})\n\n// Mount volume to sandbox\nconst sandbox = await client.createSandbox({\n template: 'base',\n volumes: [\n { volumeId: volume.id, mountPath: '/data' }\n ]\n})\n```\n\n### Volume Operations\n\n| Method | Description |\n|--------|-------------|\n| `create(config)` | Create a new volume |\n| `delete(volumeId)` | Delete a volume |\n| `list()` | List all volumes |\n\n## Error Handling\n\nThe SDK defines custom error types for different failure scenarios, making it easier to handle errors appropriately in your application. 资料来源：[packages/js-sdk/src/errors.ts]()\n\n### Error Types\n\n| Error Type | Description |\n|------------|-------------|\n| `AuthenticationError` | Invalid or missing API key |\n| `TimeoutError` | Operation exceeded timeout |\n| `SandboxError` | Sandbox creation or operation failure |\n| `RateLimitError` | API rate limit exceeded |\n| `ValidationError` | Invalid parameters or configuration |\n\n### Error Handling Pattern\n\n```typescript\nimport { E2B, AuthenticationError, TimeoutError } from 'e2b'\n\ntry {\n const sandbox = await client.createSandbox({ template: 'base' })\n await sandbox.filesystem.read('/app/data.json')\n} catch (error) {\n if (error instanceof AuthenticationError) {\n console.error('Please check your API key')\n } else if (error instanceof TimeoutError) {\n console.error('Operation timed out')\n } else {\n throw error\n }\n}\n```\n\n## API Client Configuration\n\nThe connection configuration allows customization of the API client behavior, including custom base URLs, headers, and authentication. 资料来源：[packages/js-sdk/src/connectionConfig.ts]()\n\n### Configuration Options\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `apiKey` | `string` | E2B API key |\n| `baseUrl` | `string` | Custom API base URL |\n| `timeout` | `number` | Default request timeout |\n| `headers` | `Record` | Custom HTTP headers |\n\n### Custom Configuration Example\n\n```typescript\nimport { E2B } from 'e2b'\n\nconst client = new E2B({\n apiKey: process.env.E2B_API_KEY,\n baseUrl: 'https://api.e2b.dev/v1',\n timeout: 30000\n})\n```\n\n## Build Configuration\n\nThe SDK is built using tsup, a TypeScript bundler that produces optimized output for both ESM and CommonJS formats. 资料来源：[packages/js-sdk/tsup.config.js]()\n\n### Build Output Configuration\n\n```javascript\nexport default defineConfig({\n minify: false,\n target: ['es2017'],\n sourcemap: true,\n dts: true,\n format: ['esm', 'cjs'],\n clean: true,\n entry: {\n index: './src/index.ts',\n },\n esbuildOptions: (options) => {\n options.legalComments = 'none'\n return options\n },\n})\n```\n\n### Supported Platforms\n\n| Platform | Format | Target |\n|----------|--------|--------|\n| Node.js | CommonJS | `node18` |\n| Browser | ESM | `es2017` |\n\n## API Reference\n\n### E2B Client\n\n```typescript\nclass E2B {\n constructor(config?: ConnectionConfig)\n \n // Sandboxes\n sandboxes: Sandboxes\n \n // Volumes\n volumes: Volumes\n \n // Templates\n templates: Templates\n \n // Close the client\n close(): void\n}\n```\n\n### Sandbox Instance\n\n```typescript\nclass Sandbox {\n id: string\n url: string\n startedAt: Date\n \n // Properties\n filesystem: Filesystem\n commands: Commands\n network: Network\n \n // Methods\n kill(): Promise\n restart(): Promise\n}\n```\n\n## Best Practices\n\n### Resource Management\n\nAlways properly terminate sandboxes when they are no longer needed to avoid unnecessary resource consumption and costs:\n\n```typescript\n// Recommended pattern with try/finally\nconst sandbox = await client.createSandbox({ template: 'base' })\ntry {\n // Perform operations\n} finally {\n await sandbox.kill()\n}\n```\n\n### Error Handling\n\nImplement comprehensive error handling to gracefully manage API failures, timeouts, and sandbox errors:\n\n```typescript\nasync function withSandbox(\n fn: (sandbox: Sandbox) => Promise\n): Promise {\n const sandbox = await client.createSandbox({ template: 'base' })\n try {\n return await fn(sandbox)\n } catch (error) {\n if (error instanceof RateLimitError) {\n await new Promise(r => setTimeout(r, 1000))\n return withSandbox(fn)\n }\n throw error\n } finally {\n await sandbox.kill()\n }\n}\n```\n\n### Timeout Configuration\n\nSet appropriate timeouts for long-running operations:\n\n```typescript\nconst sandbox = await client.createSandbox({\n template: 'base',\n timeout: 60000 // 60 seconds\n})\n```\n\n## Dependencies\n\nThe SDK relies on several key dependencies for its functionality:\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `@connectrpc/connect` | `2.0.0-rc.3` | RPC communication |\n| `@connectrpc/connect-web` | `2.0.0-rc.3` | Web RPC transport |\n| `openapi-fetch` | `0.14.1` | REST API client |\n| `platform` | `1.3.6` | Runtime detection |\n| `chalk` | `5.3.0` | Terminal styling |\n| `tar` | `7.5.11` | Archive handling |\n\n## CLI Integration\n\nThe SDK also integrates with the E2B CLI for template management. Template commands allow building, creating, and migrating sandbox templates across different languages. 资料来源：[packages/cli/src/commands/template/build.ts]()\n资料来源：[packages/cli/src/commands/template/init.ts]()\n\n## Related Documentation\n\nFor more information, refer to:\n\n- [Python SDK](../python-sdk/README.md) - Python client library\n- [CLI Documentation](./cli) - Command-line interface\n- [API Reference](./api) - REST API documentation\n- [Template Development](./templates) - Creating custom templates\n\n---\n\n\n\n## Python SDK\n\n### 相关页面\n\n相关主题：[JavaScript/TypeScript SDK](#js-sdk), [CLI Tool](#cli-tool), [Sandbox Usage](#sandbox-usage)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/python-sdk/e2b/__init__.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/__init__.py)\n- [packages/python-sdk/e2b/sandbox/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox/main.py)\n- [packages/python-sdk/e2b/sandbox_async/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_async/main.py)\n- [packages/python-sdk/e2b/sandbox_sync/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_sync/main.py)\n- [packages/python-sdk/e2b/sandbox/sandbox_api.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox/sandbox_api.py)\n- [packages/python-sdk/e2b/sandbox_async/sandbox_api.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_async/sandbox_api.py)\n- [packages/python-sdk/e2b/sandbox_sync/sandbox_api.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_sync/sandbox_api.py)\n- [packages/python-sdk/e2b/envd/api.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/envd/api.py)\n- [packages/python-sdk/e2b/exceptions.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/exceptions.py)\n- [packages/python-sdk/e2b/api/client/client.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/api/client/client.py)\n \n\n# Python SDK\n\nThe E2B Python SDK provides a programmatic interface for creating and managing secure cloud sandboxes that execute AI-generated code in isolated environments. The SDK enables developers to spawn sandbox instances, execute shell commands, manage filesystem operations, and build reusable sandbox templates.\n\n## Overview\n\nE2B (Execution-to-Brain) is an open-source infrastructure platform that allows developers to run AI-generated code in secure, isolated sandboxes hosted in the cloud. The Python SDK serves as the primary client library for Python developers to interact with the E2B infrastructure.\n\n**Key capabilities:**\n\n- Create and manage sandboxed execution environments\n- Execute arbitrary shell commands within sandboxes\n- Build and deploy custom sandbox templates\n- Access filesystem operations (upload, download, file management)\n- Configure sandbox resources (CPU, memory)\n- Support for both synchronous and asynchronous programming patterns\n\n**Package information:**\n\n```python\n# SDK metadata captured from package\npackage_version = metadata.version(\"e2b\")\n\ndefault_headers = {\n \"lang\": \"python\",\n \"lang_version\": platform.python_version(),\n \"package_version\": metadata.version(\"e2b\"),\n \"publisher\": \"e2b\",\n \"sdk_runtime\": \"python\",\n \"system\": platform.system(),\n}\n```\n\n资料来源：[e2b/api/metadata.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/api/metadata.py)\n\n## Installation and Setup\n\n### Install the SDK\n\n```bash\npip install e2b\n```\n\n### Configure API Credentials\n\nObtain your API key from the [E2B Dashboard](https://e2b.dev/dashboard?tab=keys) and set it as an environment variable:\n\n```bash\nexport E2B_API_KEY=e2b_***\n```\n\n### Quick Start Example\n\n```python\nfrom e2b import Sandbox\n\nwith Sandbox.create() as sandbox:\n result = sandbox.commands.run('echo \"Hello from E2B!\"')\n print(result.stdout) # Hello from E2B!\n```\n\n## Architecture\n\nThe Python SDK is structured around several key modules that provide different functionality layers.\n\n```mermaid\ngraph TD\n A[User Code] --> B[Python SDK]\n B --> C[Sandbox API Client]\n B --> D[Template API Client]\n C --> E[E2B Backend API]\n D --> E\n E --> F[Sandbox Instances]\n E --> G[Template Registry]\n F --> H[envd Runtime]\n H --> I[Isolated Execution Environment]\n```\n\n### Module Structure\n\n| Module | Purpose |\n|--------|---------|\n| `e2b.sandbox` | Core sandbox functionality |\n| `e2b.sandbox_async` | Async sandbox implementation |\n| `e2b.sandbox_sync` | Synchronous sandbox implementation |\n| `e2b.template` | Template builder functionality |\n| `e2b.envd` | Environment daemon API |\n| `e2b.api` | HTTP API client layer |\n| `e2b.exceptions` | Custom exception types |\n\n## Sandbox Class\n\nThe `Sandbox` class is the primary entry point for creating and interacting with sandboxed execution environments. The SDK provides both context manager support and manual lifecycle management.\n\n### Creating a Sandbox\n\n```python\nfrom e2b import Sandbox\n\n# Using context manager (recommended)\nwith Sandbox.create() as sandbox:\n result = sandbox.commands.run('echo \"Hello\"')\n print(result.stdout)\n```\n\n### Sandbox Lifecycle\n\n```mermaid\nstateDiagram-v2\n [*] --> Created: Sandbox.create()\n Created --> Running: __enter__()\n Running --> Stopped: __exit__() / close()\n Stopped --> [*]\n Created --> Stopped: close()\n```\n\n### Key Sandbox Methods\n\n| Method | Description |\n|--------|-------------|\n| `Sandbox.create()` | Static factory method to create a new sandbox instance |\n| `sandbox.close()` | Manually terminate the sandbox |\n| `sandbox.commands.run(cmd)` | Execute a shell command |\n| `sandbox.filesystem` | Access filesystem operations |\n| `sandbox.upload(src, dest)` | Upload files to sandbox |\n| `sandbox.download(src, dest)` | Download files from sandbox |\n\n资料来源：[e2b/sandbox/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox/main.py)\n\n## Synchronous vs Asynchronous APIs\n\nThe Python SDK provides both synchronous and asynchronous interfaces to accommodate different programming patterns.\n\n### Synchronous API\n\n```python\nfrom e2b.sandbox_sync import Sandbox\n\nsandbox = Sandbox.create()\nresult = sandbox.commands.run('echo \"sync\"')\nsandbox.close()\n```\n\nThe synchronous API uses blocking I/O operations and is suitable for scripts and applications where concurrency is not a primary concern.\n\n### Asynchronous API\n\n```python\nimport asyncio\nfrom e2b.sandbox_async import Sandbox\n\nasync def main():\n async with Sandbox.create() as sandbox:\n result = await sandbox.commands.run('echo \"async\"')\n print(result.stdout)\n\nasyncio.run(main())\n```\n\nThe async API is designed for web applications, async frameworks, and scenarios requiring concurrent sandbox operations.\n\n| Feature | Sync API | Async API |\n|---------|----------|-----------|\n| Import | `from e2b import Sandbox` | `from e2b.sandbox_async import Sandbox` |\n| I/O Model | Blocking | Non-blocking |\n| Use Case | Scripts, CLI tools | Web servers, async frameworks |\n| Connection | `e2b.sandbox_sync.sandbox_api` | `e2b.sandbox_async.sandbox_api` |\n\n资料来源：[e2b/sandbox_sync/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_sync/main.py)，[e2b/sandbox_async/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_async/main.py)\n\n## Template Builder\n\nTemplates define the base image and configuration for sandbox environments. The Template Builder API allows programmatic creation of custom sandbox templates.\n\n### Creating a Template\n\n```python\nfrom e2b import Template\n\ntemplate = (\n Template()\n .from_python_image('3')\n .copy('requirements.txt', '/home/user/')\n .run_cmd('pip install -r /home/user/requirements.txt')\n)\n\n# Build and deploy\nTemplate.build(template, 'my-python-env:v1.0')\n```\n\n### Available Base Images\n\n| Method | Base Image |\n|--------|------------|\n| `fromPythonImage(version)` | Python Docker image |\n| `fromNodeImage(variant)` | Node.js Docker image |\n| `fromBunImage(variant)` | Bun Docker image |\n| `fromDebianImage(variant)` | Debian Docker image |\n| `fromUbuntuImage(variant)` | Ubuntu Docker image |\n| `fromTemplate(name)` | E2B template |\n| `fromDockerfile(content)` | Custom Dockerfile |\n\n### Template Builder Methods\n\n| Method | Description |\n|--------|-------------|\n| `run_cmd(cmd, user)` | Execute a shell command during build |\n| `copy(src, dest)` | Copy files into the template |\n| `apt_install(packages)` | Install system packages |\n| `bun_install(packages)` | Install npm/bun packages |\n| `set_envs(envs)` | Set environment variables |\n| `set_start_cmd(cmd, ready_cmd)` | Configure startup command |\n| `skip_cache()` | Force rebuild ignoring cache |\n\n资料来源：[e2b/template/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template/main.py)\n\n### Async Template Operations\n\n```python\nfrom e2b import AsyncTemplate\n\ntemplate = (\n AsyncTemplate()\n .from_python_image('3')\n .run_cmd('pip install numpy')\n)\n\n# Build with progress callback\nasync def on_logs(log):\n print(log.message)\n\nawait AsyncTemplate.build(\n template, \n 'my-template:v1.0',\n on_build_logs=on_logs\n)\n```\n\n## Connection Configuration\n\nThe SDK uses `ConnectionConfig` to manage API connection parameters including authentication, endpoints, and timeouts.\n\n### Configuration Parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `api_key` | str | `E2B_API_KEY` env | API authentication key |\n| `access_token` | str | `E2B_ACCESS_TOKEN` env | Alternative auth token |\n| `base_url` | str | E2B API | Custom API endpoint |\n| `timeout` | int | 60 | Request timeout in seconds |\n\n### Custom Configuration\n\n```python\nfrom e2b import Sandbox\nfrom e2b.constants import ConnectionConfig\n\nconfig = ConnectionConfig(\n api_key='e2b_***',\n timeout=120\n)\n\nwith Sandbox.create(**config) as sandbox:\n result = sandbox.commands.run('echo \"configured\"')\n```\n\n## Command Execution\n\n### Running Commands\n\n```python\nsandbox = Sandbox.create()\n\n# Basic command\nresult = sandbox.commands.run('ls -la')\n\n# With working directory\nresult = sandbox.commands.run('pwd', cwd='/home/user')\n\n# With timeout\nresult = sandbox.commands.run('sleep 10', timeout=5)\n```\n\n### Command Result Properties\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `stdout` | str | Standard output |\n| `stderr` | str | Standard error |\n| `exit_code` | int | Process exit code |\n| `stdout_lines` | List[str] | Output as line array |\n\n## Error Handling\n\nThe SDK defines custom exception types for different error scenarios.\n\n### Exception Types\n\n| Exception | Description |\n|-----------|-------------|\n| `SandboxException` | Base exception for sandbox errors |\n| `AuthenticationException` | API key/authentication failures |\n| `TimeoutException` | Operation timeout exceeded |\n| `NotFoundException` | Resource not found |\n| `RateLimitException` | API rate limit exceeded |\n\n### Handling Errors\n\n```python\nfrom e2b import Sandbox\nfrom e2b.exceptions import TimeoutException, SandboxException\n\ntry:\n sandbox = Sandbox.create(timeout=30)\n result = sandbox.commands.run('long-running-command', timeout=5)\nexcept TimeoutException:\n print(\"Command timed out\")\nexcept SandboxException as e:\n print(f\"Sandbox error: {e}\")\nfinally:\n sandbox.close()\n```\n\n资料来源：[e2b/exceptions.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/exceptions.py)\n\n## envd API\n\nThe `envd` module provides access to the environment daemon running inside each sandbox, enabling advanced operations and introspection.\n\n### Available Operations\n\n```python\nsandbox = Sandbox.create()\n\n# Get environment info\ninfo = sandbox.envd.info()\n\n# Check service status\nstatus = sandbox.envd.is_process_running('nginx')\n\n# Wait for port to be ready\nsandbox.envd.wait_for_port(3000)\n```\n\n资料来源：[e2b/envd/api.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/envd/api.py)\n\n## API Client Layer\n\nThe HTTP API client handles low-level communication with the E2B backend.\n\n```mermaid\ngraph LR\n A[SDK Classes] --> B[SandboxAPI Client]\n B --> C[HTTP Requests]\n C --> D[E2B REST API]\n D --> E[Response Handling]\n E --> F[SDK Data Models]\n```\n\n### Client Configuration\n\n```python\nfrom e2b.api.client.client import APIClient\n\nclient = APIClient(\n base_url=\"https://api.e2b.dev\",\n timeout=60,\n headers={\n \"X-Custom-Header\": \"value\"\n }\n)\n```\n\n资料来源：[e2b/api/client/client.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/api/client/client.py)\n\n## Complete Usage Example\n\n```python\nfrom e2b import Sandbox, Template\n\n# Create and configure a template\ntemplate = (\n Template()\n .from_python_image('3.11')\n .apt_install(['git', 'curl'])\n .run_cmd('pip install fastapi uvicorn')\n .set_envs({'APP_ENV': 'production'})\n .set_start_cmd('uvicorn main:app', 'curl http://localhost:8000/health')\n)\n\n# Build template (run once)\nTemplate.build(template, 'my-fastapi:v1.0')\n\n# Use the template in sandboxes\nwith Sandbox.create(template='my-fastapi:v1.0') as sandbox:\n # Upload application code\n sandbox.upload('./app', '/home/user/app')\n \n # Run a command\n result = sandbox.commands.run('cd /home/user/app && python main.py')\n print(result.stdout)\n```\n\n## See Also\n\n- [JavaScript SDK](../js-sdk) - TypeScript/JavaScript implementation\n- [CLI](../cli) - Command-line interface\n- [Code Interpreter](https://github.com/e2b-dev/code-interpreter) - Code execution SDK\n- [E2B Documentation](https://e2b.dev/docs) - Official documentation\n- [Cookbook](https://github.com/e2b-dev/e2b-cookbook) - Usage examples\n\n---\n\n\n\n## CLI Tool\n\n### 相关页面\n\n相关主题：[JavaScript/TypeScript SDK](#js-sdk), [Python SDK](#python-sdk), [Template System](#template-system)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/cli/README.md](https://github.com/e2b-dev/E2B/blob/main/packages/cli/README.md)\n- [packages/cli/src/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/index.ts)\n- [packages/cli/src/commands/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/index.ts)\n- [packages/cli/src/commands/auth/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/auth/index.ts)\n- [packages/cli/src/commands/sandbox/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/sandbox/index.ts)\n- [packages/cli/src/commands/template/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/template/index.ts)\n- [packages/cli/src/commands/template/create.ts](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/template/create.ts)\n- [packages/cli/src/commands/template/build.ts](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/template/build.ts)\n \n\n# CLI Tool\n\nThe E2B CLI (Command Line Interface) is a Node.js-based command-line tool that enables developers to build, manage, and interact with E2B sandbox templates and running sandboxes directly from the terminal. It provides a unified interface for authentication, template management, and sandbox operations without requiring direct API integration.\n\n## Overview\n\nThe E2B CLI serves as the primary management interface for E2B infrastructure. It allows users to authenticate with the E2B platform, create and build sandbox templates, manage running sandboxes, and configure their development environment for AI-generated code execution.\n\n**Key capabilities include:**\n\n- User authentication and token management\n- Sandbox template creation and building\n- Running sandbox lifecycle management\n- Support for multiple package managers and base images\n- Environment variable configuration during build\n- Dockerfile integration for custom sandbox definitions\n\n资料来源：[packages/cli/README.md:1-20]()\n\n## Installation\n\n### System Requirements\n\n| Requirement | Version/Details |\n|------------|-----------------|\n| Node.js | v14.0.0 or higher |\n| npm | v6.0.0 or higher |\n| Operating System | macOS, Linux, Windows |\n\n### Installation Methods\n\n#### Using Homebrew (macOS/Linux)\n\n```bash\nbrew install e2b\n```\n\n#### Using NPM\n\n```bash\nnpm install -g @e2b/cli\n```\n\n资料来源：[packages/cli/README.md:13-20]()\n\n## Authentication\n\nBefore using the CLI, you must authenticate with your E2B account. The CLI supports two authentication methods.\n\n### Interactive Login\n\n```bash\ne2b auth login\n```\n\nThis command opens a browser window for the user to complete the OAuth authentication flow.\n\n### Token-Based Authentication\n\nFor non-interactive environments (CI/CD pipelines, remote servers), provide the access token directly:\n\n```bash\nE2B_ACCESS_TOKEN=sk_e2b_... e2b template build\n```\n\n**Important:** Note the distinction between `E2B_ACCESS_TOKEN` and `E2B_API_KEY`. The CLI uses `E2B_ACCESS_TOKEN`, which can be found in Account Settings under the Team selector at [e2b.dev/dashboard](https://e2b.dev/dashboard).\n\n资料来源：[packages/cli/README.md:22-32]()\n\n## Command Structure\n\nThe CLI organizes commands hierarchically under the `e2b` namespace:\n\n```mermaid\ngraph TD\n A[e2b] --> B[auth]\n A --> C[template]\n A --> D[sandbox]\n \n B --> B1[login]\n \n C --> C1[create]\n C --> C2[build]\n C --> C3[list]\n C --> C4[delete]\n \n D --> D1[start]\n D --> D2[stop]\n D --> D3[list]\n D --> D4[logs]\n```\n\n### Global Flags\n\n| Flag | Description | Example |\n|------|-------------|---------|\n| `--help, -h` | Display help information | `e2b --help` |\n| `--version, -v` | Display CLI version | `e2b --version` |\n| `--debug` | Enable debug output | `e2b --debug template build` |\n\n## Template Commands\n\nTemplates define the sandbox environment including base images, installed packages, environment variables, and startup commands.\n\n### Template Create\n\nCreates a new sandbox template from a directory containing a `e2b.toml` configuration file or a Dockerfile.\n\n```bash\ne2b template create \n```\n\n**Example workflow:**\n\n```bash\n# Navigate to your template directory\ncd my-sandbox-template\n\n# Create the template\ne2b template create my-python-env\n```\n\nThe command reads the template configuration, builds the Docker image, and uploads it to E2B infrastructure.\n\n资料来源：[packages/cli/src/commands/template/create.ts:1-20]()\n\n### Template Build\n\nBuilds a sandbox template and uploads it to E2B infrastructure.\n\n```bash\ne2b template build [options]\n```\n\n**Options:**\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `--alias, -a` | Template alias/name | Required |\n| `--tag` | Additional tags for the build | None |\n| `--file, -f` | Path to Dockerfile | `./Dockerfile` |\n| `--timeout` | Build timeout in seconds | 600 |\n\n**Build Process Flow:**\n\n```mermaid\ngraph LR\n A[Start Build] --> B{Config File?}\n B -->|Dockerfile| C[Load Dockerfile]\n B -->|e2b.toml| D[Parse Configuration]\n C --> E[Build Docker Image]\n D --> F[Generate Dockerfile]\n E --> G[Upload to Registry]\n F --> E\n G --> H[Create Template]\n H --> I[Build Complete]\n```\n\n**Example usage:**\n\n```bash\n# Build with auto-generated name\ne2b template build --alias my-template\n\n# Build with custom Dockerfile\ne2b template build --alias my-template --file ./custom.Dockerfile\n\n# Build with tags\ne2b template build --alias my-template --tag v1.0 --tag stable\n```\n\n资料来源：[packages/cli/src/commands/template/build.ts:1-50]()\n\n### Template Configuration\n\nTemplates can be configured using either a `e2b.toml` file or a `Dockerfile`.\n\n#### Using e2b.toml\n\n```toml\nname = \"my-template\"\nruntime = \"dockerfile\"\n\n[env]\nNODE_ENV = \"production\"\n\n[start]\ncommand = \"npm start\"\nready = \"curl http://localhost:3000/health\"\n```\n\n#### Using Dockerfile\n\nThe CLI automatically detects and uses a `Dockerfile` in the template directory:\n\n```dockerfile\nFROM python:3.11-slim\n\nRUN pip install numpy pandas flask\n\nENV PORT=8080\n\nENTRYPOINT [\"python\", \"app.py\"]\n```\n\nThe CLI loads the Dockerfile content using the `getDockerfile()` function:\n\n```typescript\nfunction getDockerfile(root: string, file?: string) {\n // Check if user specified custom Dockerfile exists\n if (file) {\n const dockerfilePath = path.join(root, file)\n const dockerfileContent = loadFile(dockerfilePath)\n const dockerfileRelativePath = path.relative(root, dockerfilePath)\n \n // Returns { dockerfilePath, dockerfileContent, dockerfileRelativePath }\n }\n}\n```\n\n资料来源：[packages/cli/src/commands/template/build.ts:80-100]()\n\n### Template Build Output\n\nUpon successful build completion, the CLI displays:\n\n```\n✅ Building sandbox template finished.\n\nExample usage:\n\nPython SDK\n from e2b import Sandbox\n sandbox = Sandbox.create(template=\"\")\n result = sandbox.commands.run('echo \"Hello from E2B!\"')\n\nJS SDK\n import Sandbox from 'e2b'\n const sandbox = await Sandbox.create({ template: '' })\n const result = await sandbox.commands.run('echo \"Hello from E2B!\"')\n```\n\n资料来源：[packages/cli/src/commands/template/build.ts:35-45]()\n\n### Error Handling\n\nBuild errors are reported with detailed context:\n\n```\n❌ Building sandbox template failed.\nCheck the logs above for more details or contact us (https://e2b.dev/docs/support) to get help.\n```\n\n资料来源：[packages/cli/src/commands/template/build.ts:50-58]()\n\n## Sandbox Commands\n\nSandbox commands allow you to manage running sandbox instances.\n\n### Available Sandbox Operations\n\n| Command | Description |\n|---------|-------------|\n| `e2b sandbox start` | Start a new sandbox instance |\n| `e2b sandbox stop` | Stop a running sandbox |\n| `e2b sandbox list` | List all running sandboxes |\n| `e2b sandbox logs` | View sandbox logs |\n\n### Sandbox Lifecycle\n\n```mermaid\ngraph TD\n A[Create Sandbox] --> B[Initialize]\n B --> C[Run Ready Command]\n C --> D{Ready?}\n D -->|Yes| E[Sandbox Active]\n D -->|No| F[Retry/Timeout]\n E --> G[Execute Commands]\n G --> H[Stop Sandbox]\n H --> I[Cleanup]\n```\n\n资料来源：[packages/cli/src/commands/sandbox/index.ts:1-30]()\n\n## Environment Variables\n\n### CLI Environment Variables\n\n| Variable | Description | Required |\n|----------|-------------|----------|\n| `E2B_ACCESS_TOKEN` | CLI authentication token | Yes (non-interactive) |\n| `E2B_API_KEY` | API key for SDK operations | For SDK usage |\n\n### Template Environment Variables\n\nDuring template build, environment variables can be set in the configuration:\n\n```toml\n[env]\nNODE_ENV = \"production\"\nPORT = \"8080\"\nDATABASE_URL = \"postgres://...\"\n```\n\n资料来源：[packages/cli/README.md:28-30]()\n\n## Architecture\n\n### CLI Entry Point\n\nThe CLI entry point at `packages/cli/src/index.ts` initializes the command infrastructure and registers all available commands:\n\n```typescript\n// Main CLI entry point\n// Registers: auth, template, sandbox commands\n// Handles global flags and configuration\n```\n\n### Command Registration\n\nCommands are registered in `packages/cli/src/commands/index.ts` which serves as the command router:\n\n```mermaid\ngraph TD\n A[index.ts] --> B[commands/index.ts]\n B --> C[auth/index.ts]\n B --> D[template/index.ts]\n B --> E[sandbox/index.ts]\n \n D --> D1[create.ts]\n D --> D2[build.ts]\n \n C --> C1[login.ts]\n C --> C2[logout.ts]\n```\n\n### Build System\n\nThe CLI is built using [tsup](https://github.com/egoist/tsup), a TypeScript bundler built on top of esbuild. The build configuration in `tsup.config.js` handles:\n\n- TypeScript compilation\n- Module resolution\n- Output format (CJS/ESM)\n- External dependencies\n\n```javascript\n// packages/cli/tsup.config.js\n// Configures CLI bundling for distribution\n```\n\n## Integration with SDKs\n\nThe CLI works in conjunction with the JavaScript and Python SDKs:\n\n```mermaid\ngraph LR\n A[CLI] --> B[Manage Templates]\n A --> C[Authenticate]\n \n D[JS SDK/Python SDK] --> E[Sandbox Runtime]\n E --> F[Execute Code]\n \n B --> G[E2B Cloud]\n C --> G\n```\n\n### Template Usage with SDKs\n\nAfter building a template with the CLI, use it with the SDKs:\n\n**Python SDK:**\n\n```python\nfrom e2b import Sandbox\n\nsandbox = Sandbox.create(template=\"my-template\")\nresult = sandbox.commands.run('echo \"Hello from E2B!\"')\nprint(result.stdout)\n```\n\n**JavaScript SDK:**\n\n```typescript\nimport Sandbox from 'e2b'\n\nconst sandbox = await Sandbox.create({ template: 'my-template' })\nconst result = await sandbox.commands.run('echo \"Hello from E2B!\"')\nconsole.log(result.stdout)\n```\n\n资料来源：[packages/cli/src/commands/template/create.ts:5-15]()\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Solution |\n|-------|----------|\n| Authentication failed | Ensure `E2B_ACCESS_TOKEN` is valid and not expired |\n| Build timeout | Increase timeout with `--timeout` flag or optimize Dockerfile |\n| Dockerfile not found | Verify the file exists or specify path with `--file` flag |\n| Permission denied | Ensure npm global install permissions are correct |\n\n### Debug Mode\n\nEnable debug output for detailed logging:\n\n```bash\ne2b --debug template build --alias my-template\n```\n\n### Getting Help\n\n```bash\n# General help\ne2b --help\n\n# Command-specific help\ne2b template --help\ne2b template build --help\ne2b sandbox --help\n```\n\n## See Also\n\n- [E2B Documentation](https://e2b.dev/docs)\n- [JavaScript SDK](../js-sdk/README.md)\n- [Python SDK](../python-sdk/README.md)\n- [E2B Cookbook](https://github.com/e2b-dev/e2b-cookbook)\n\n---\n\n\n\n## Sandbox Management\n\n### 相关页面\n\n相关主题：[Sandbox Usage](#sandbox-usage), [Network Configuration](#network-config)\n\n\nRelevant Source Files
\n\nThe following source files were used to generate this documentation page:\n\n- [packages/js-sdk/src/sandbox/sandboxApi.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/sandboxApi.ts)\n- [packages/js-sdk/src/sandbox/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/index.ts)\n- [packages/python-sdk/e2b/sandbox_async/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_async/main.py)\n- [packages/python-sdk/e2b/sandbox_sync/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_sync/main.py)\n- [packages/python-sdk/e2b/sandbox_async/sandbox_api.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_async/sandbox_api.py)\n- [packages/cli/src/commands/sandbox/info.ts](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/sandbox/info.ts)\n- [packages/cli/src/commands/template/create.ts](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/template/create.ts)\n- [packages/cli/src/commands/template/build.ts](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/template/build.ts)\n \n\n# Sandbox Management\n\n## Overview\n\nSandbox Management is the core system in E2B that enables the creation, control, and lifecycle management of secure, isolated cloud environments for running AI-generated code. Sandboxes provide ephemeral compute instances that can be spawned on-demand, configured with specific templates, and terminated when no longer needed.\n\nThe sandbox system abstracts away infrastructure complexity, allowing developers to work with a simple high-level API while E2B handles container orchestration, network isolation, and resource allocation behind the scenes.\n\n资料来源：[packages/js-sdk/src/sandbox/sandboxApi.ts:1-50]()\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n A[Developer Application] --> B[SDK Client]\n B --> C[Sandbox API]\n C --> D[E2B Infrastructure]\n D --> E[Isolated Sandbox Container]\n \n F[Template Definition] --> C\n G[CLI Commands] --> C\n \n H[Sandbox Instance] --> I[Commands Execution]\n H --> J[File System Access]\n H --> K[Network Resources]\n```\n\nThe architecture consists of three primary layers:\n\n| Layer | Description | Components |\n|-------|-------------|------------|\n| **Client SDK** | High-level language bindings | JavaScript SDK, Python SDK |\n| **API Gateway** | REST API for sandbox operations | Template management, sandbox lifecycle |\n| **Infrastructure** | Container orchestration | Docker containers, isolated networking |\n\n资料来源：[packages/js-sdk/src/sandbox/index.ts:1-60]()\n\n## Sandbox Lifecycle\n\nSandboxes follow a well-defined state machine with transitions controlled by the platform.\n\n```mermaid\nstateDiagram-v2\n [*] --> Starting\n Starting --> Running : API returns sandbox info\n Running --> Paused : Pause request\n Running --> Stopped : Timeout or kill\n Paused --> Running : Resume request\n Paused --> Stopped : Kill\n Stopped --> [*]\n \n Running --> Error : Infrastructure failure\n Error --> [*]\n```\n\n### Lifecycle Configuration\n\nThe sandbox lifecycle behavior can be configured at creation time:\n\n```python\nlifecycle = {\n \"on_timeout\": \"pause\", # \"kill\" (default) or \"pause\"\n \"auto_resume\": True # Only when on_timeout=\"pause\"\n}\n```\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `on_timeout` | `str` | `\"kill\"` | Action when sandbox timeout is reached |\n| `auto_resume` | `bool` | `False` | Whether to auto-resume paused sandbox |\n\n资料来源：[packages/js-sdk/src/sandbox/sandboxApi.ts:60-80]()\n\n## Creating a Sandbox\n\n### JavaScript SDK\n\nThe JavaScript SDK provides both stable and beta creation methods.\n\n**Stable Creation:**\n\n```typescript\nimport Sandbox from 'e2b'\n\nconst sandbox = await Sandbox.create('my-template', {\n timeoutMs: 60000,\n metadata: { userId: '123' },\n envs: { NODE_ENV: 'production' }\n})\n```\n\n**Beta Creation (with MCP support):**\n\n```typescript\nconst sandbox = await Sandbox.betaCreate('my-template', {\n mcp: { servers: ['exa', 'firecrawl'] }\n})\n```\n\nThe SDK automatically handles:\n- Template resolution (defaults to `base` or `mcp-gateway`)\n- Connection configuration\n- Debug mode fallback\n\n资料来源：[packages/js-sdk/src/sandbox/index.ts:60-120]()\n\n### Python SDK\n\n**Async Sandbox:**\n\n```python\nfrom e2b import AsyncSandbox\n\nasync with await AsyncSandbox.create(\n template='my-template',\n timeout=60_000,\n metadata={'userId': '123'},\n envs={'PYTHON_ENV': 'production'}\n) as sandbox:\n result = await sandbox.commands.run('echo \"Hello\"')\n```\n\n**Sync Sandbox:**\n\n```python\nfrom e2b import Sandbox\n\nwith Sandbox.create(\n template='my-template',\n timeout=60_000\n) as sandbox:\n result = sandbox.commands.run('echo \"Hello\"')\n```\n\n资料来源：[packages/python-sdk/e2b/sandbox_async/main.py:1-80]()\n资料来源：[packages/python-sdk/e2b/sandbox_sync/main.py:1-70]()\n\n## Sandbox Options and Configuration\n\n### Core Options\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `template` | `string` | No | `\"base\"` | Sandbox template name or ID |\n| `timeoutMs` | `number` | No | Varies by plan | Maximum sandbox lifetime in milliseconds |\n| `metadata` | `Record` | No | `{}` | Custom metadata for the sandbox |\n| `envs` | `Record` | No | `{}` | Environment variables |\n| `mcp` | `MCPConfig` | No | - | MCP server configuration |\n| `network` | `boolean` | No | `true` | Network isolation setting |\n| `allowInternetAccess` | `boolean` | No | `true` | Internet access in sandbox |\n\n### Resource Configuration\n\n```typescript\nconst sandbox = await Sandbox.create('my-template', {\n // CPU and memory can be specified via CLI\n // SDK uses template defaults\n})\n```\n\n**CLI Resource Options:**\n\n| Flag | Default | Description |\n|------|---------|-------------|\n| `--cpu-count` | `2` | Number of vCPUs |\n| `--memory-mb` | `512` | RAM in megabytes (must be even) |\n\n资料来源：[packages/js-sdk/src/sandbox/sandboxApi.ts:80-150]()\n资料来源：[packages/cli/src/commands/template/create.ts:40-80]()\n\n## Volume Mounts\n\nSandboxes support attaching persistent volumes for data storage across sessions.\n\n```python\nfrom e2b import AsyncSandbox, AsyncVolume\n\nvolume = await AsyncVolume.create('my-data-volume')\n\nasync with AsyncSandbox.create(\n volume_mounts={\n '/data': volume\n }\n) as sandbox:\n # Files in /data persist across sandbox instances\n await sandbox.commands.run('echo \"data\" > /data/file.txt')\n```\n\nVolume mount transformation:\n\n```python\ntransformed_mounts = [\n SandboxVolumeMountAPI(\n name=vol.name if isinstance(vol, AsyncVolume) else vol,\n path=path,\n )\n for path, vol in volume_mounts.items()\n]\n```\n\n资料来源：[packages/python-sdk/e2b/sandbox_async/main.py:30-60]()\n\n## Sandbox API Methods\n\n### Creation Response\n\nWhen a sandbox is created, the API returns a response containing connection details:\n\n```python\nSandboxCreateResponse(\n sandbox_id=\"sbox_xxxxx\",\n sandbox_domain=\"sbox-xxxxx.e2b.dev\",\n envd_version=\"0.1.0\",\n envd_access_token=\"token_xxxxx\",\n traffic_access_token=\"traffic_xxxxx\"\n)\n```\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `sandbox_id` | `string` | Unique sandbox identifier |\n| `sandbox_domain` | `string` or `null` | Public domain for the sandbox |\n| `envd_version` | `string` | Version of the envd agent |\n| `envd_access_token` | `string` or `null` | Token for envd authentication |\n| `traffic_access_token` | `string` or `null` | Token for traffic encryption |\n\n### Version Compatibility Check\n\nThe SDK validates that the template's envd version meets minimum requirements:\n\n```python\nif Version(res.parsed.envd_version) < Version(\"0.1.0\"):\n await SandboxApi._cls_kill(res.parsed.sandbox_id)\n raise TemplateException(\n \"You need to update the template to use the new SDK. \"\n \"You can do this by running `e2b template build`\"\n )\n```\n\n资料来源：[packages/python-sdk/e2b/sandbox_async/sandbox_api.py:50-80]()\n\n## CLI Sandbox Management\n\n### Viewing Sandbox Information\n\n```bash\ne2b sandbox info \n```\n\n**Output Fields:**\n\n| Field | Label | Description |\n|-------|-------|-------------|\n| `sandboxId` | Sandbox ID | Unique identifier |\n| `templateId` | Template ID | Template used |\n| `name` | Alias | User-assigned name |\n| `state` | State | Current sandbox state |\n| `startedAt` | Started at | Creation timestamp |\n| `endAt` | End at | Scheduled termination |\n| `cpuCount` | vCPUs | CPU allocation |\n| `memoryMB` | RAM MiB | Memory allocation |\n| `envdVersion` | Envd version | Agent version |\n| `allowInternetAccess` | Internet access | Network setting |\n| `lifecycle` | Lifecycle | Timeout behavior |\n| `network` | Network | Network configuration |\n| `sandboxDomain` | Sandbox domain | Public endpoint |\n| `metadata` | Metadata | Custom metadata |\n\n```bash\n# JSON output\ne2b sandbox info --format json\n\n# Pretty output (default)\ne2b sandbox info --format pretty\n```\n\n资料来源：[packages/cli/src/commands/sandbox/info.ts:1-60]()\n\n## Template-Based Sandbox Creation\n\nTemplates define the base environment for sandboxes. They can be built and managed via CLI.\n\n### Building Templates\n\n```bash\ne2b template build \n```\n\n**Options:**\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--path ` | `-p` | Template directory path |\n| `--dockerfile ` | `-d` | Custom Dockerfile name |\n| `--cmd ` | `-c` | Command executed on sandbox start |\n| `--ready-cmd ` | - | Command that must exit 0 for ready state |\n| `--cpu-count ` | - | vCPUs (default: 2) |\n| `--memory-mb ` | - | RAM in MB, even number (default: 512) |\n| `--no-cache` | - | Skip build cache |\n\n```bash\ne2b template build my-template \\\n --path ./templates/my-app \\\n --cmd \"python app.py\" \\\n --ready-cmd \"curl -f http://localhost:3000/health\" \\\n --cpu-count 4 \\\n --memory-mb 1024\n```\n\n### Template Validation\n\nTemplate names must follow strict naming conventions:\n\n```typescript\nif (!/^[a-z0-9-_]+$/.test(templateName)) {\n console.error(\n `Template name ${templateName} is not valid. ` +\n `Template name can only contain lowercase letters, numbers, dashes and underscores.`\n )\n}\n```\n\n资料来源：[packages/cli/src/commands/template/create.ts:50-90]()\n资料来源：[packages/cli/src/commands/template/build.ts:1-50]()\n\n## Debug Mode\n\nThe SDK supports a debug mode for local development:\n\n```typescript\nconst config = new ConnectionConfig(sandboxOpts)\nif (config.debug) {\n return new this({\n sandboxId: 'debug_sandbox_id',\n envdVersion: ENVD_DEBUG_FALLBACK,\n ...config,\n })\n}\n```\n\nIn debug mode, the sandbox uses a fallback environment instead of connecting to real infrastructure, enabling local testing of sandbox code without cloud resources.\n\n资料来源：[packages/js-sdk/src/sandbox/index.ts:80-100]()\n\n## Error Handling\n\n### Template Exceptions\n\nWhen a template is incompatible with the current SDK version:\n\n```python\nraise TemplateException(\n \"You need to update the template to use the new SDK. \"\n \"You can do this by running `e2b template build` in the directory with the template.\"\n)\n```\n\n### API Error Handling\n\n```python\nif res.status_code >= 300:\n raise handle_api_exception(res)\n\nif isinstance(res.parsed, Error):\n raise SandboxException(f\"{res.parsed.message}: Request failed\")\n```\n\n资料来源：[packages/python-sdk/e2b/sandbox_async/sandbox_api.py:40-60]()\n\n## Complete Workflow Diagram\n\n```mermaid\ngraph LR\n A[Define Template] --> B[Build Template]\n B --> C[Create Sandbox]\n C --> D[Execute Commands]\n D --> E{More Work?}\n E -->|Yes| D\n E -->|No| F[Terminate Sandbox]\n F --> G[Clean Up]\n \n H[CLI Commands] -.->|Manage| C\n I[SDK API] -.->|Programmatic| D\n```\n\n## See Also\n\n- [Template Building Guide](./template-building.md)\n- [JavaScript SDK Reference](../js-sdk/README.md)\n- [Python SDK Reference](../python-sdk/README.md)\n- [MCP Server Integration](./mcp-integration.md)\n\n---\n\n\n\n## Template System\n\n### 相关页面\n\n相关主题：[CLI Tool](#cli-tool)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/js-sdk/src/template/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/template/index.ts)\n- [packages/js-sdk/src/template/types.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/template/types.ts)\n- [packages/js-sdk/src/template/readycmd.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/template/readycmd.ts)\n- [packages/python-sdk/e2b/template/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template/main.py)\n- [packages/python-sdk/e2b/template/types.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template/types.py)\n- [packages/python-sdk/e2b/template_async/build_api.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template_async/build_api.py)\n- [packages/python-sdk/e2b/template_sync/build_api.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template_sync/build_api.py)\n- [packages/cli/src/commands/template/build.ts](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/template/build.ts)\n- [packages/cli/src/commands/template/create.ts](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/template/create.ts)\n \n\n# Template System\n\n## Overview\n\nThe Template System is a core component of the E2B infrastructure that enables developers to create reproducible, pre-configured sandbox environments for running AI-generated code. Templates define the base image, system packages, environment variables, files, and startup commands needed for a sandbox instance.\n\nTemplates follow a **fluent builder pattern** where developers chain method calls to configure the environment, then invoke `build()` to compile the template into a deployable sandbox image. The system supports both synchronous and asynchronous operations, with full SDK coverage for JavaScript/TypeScript and Python.\n\n资料来源：[packages/js-sdk/src/template/index.ts:1-50]()\n\n## Architecture\n\nThe Template System is organized across multiple layers:\n\n```mermaid\ngraph TD\n subgraph \"User Layer\"\n User[Developer]\n end\n \n subgraph \"SDK Layer\"\n JS_SDK[JS/TS SDK
TemplateBuilder]\n PY_SDK[Python SDK
TemplateBuilder]\n end\n \n subgraph \"API Layer\"\n BuildAPI[Build API]\n SandboxAPI[Sandbox API]\n end\n \n subgraph \"Infrastructure Layer\"\n Docker[Docker Build]\n Registry[Container Registry]\n Sandbox[Sandbox Runtime]\n end\n \n User -->|define template| JS_SDK\n User -->|define template| PY_SDK\n JS_SDK --> BuildAPI\n PY_SDK --> BuildAPI\n BuildAPI --> Docker\n Docker --> Registry\n Registry --> Sandbox\n```\n\n### Package Structure\n\n| Package | Language | Purpose |\n|---------|----------|---------|\n| `packages/js-sdk` | TypeScript | JS/TS SDK with Template support |\n| `packages/python-sdk` | Python | Python SDK with Template support |\n| `packages/cli` | TypeScript | Command-line template management |\n\n## Template Builder Pattern\n\nTemplates use a fluent builder API that enforces a valid state machine. The builder progresses through distinct states:\n\n```mermaid\nstateDiagram-v2\n [*] --> TemplateBuilder: instantiate Template()\n TemplateBuilder --> TemplateBuilder: add instructions\n TemplateBuilder --> TemplateBuilder: set env vars\n TemplateBuilder --> TemplateBuilder: copy files\n TemplateBuilder --> TemplateFinal: setStartCmd()\n TemplateFinal --> [*]: build()\n```\n\n### JavaScript SDK Usage\n\n```typescript\nimport { Template } from 'e2b'\n\nconst template = Template()\n .fromPythonImage('3')\n .runCmd('pip install flask')\n .copy('./app', '/app')\n .setEnvs({ FLASK_ENV: 'production' })\n .setStartCmd(\n 'python /app/main.py',\n 'curl -s http://localhost:8000/health'\n )\n\nconst buildInfo = await Template.build(template, 'my-flask-app:v1.0')\n```\n\n资料来源：[packages/js-sdk/src/template/index.ts:200-280]()\n\n### Python SDK Usage\n\n```python\nfrom e2b import Template\n\ntemplate = (\n Template()\n .from_python_image(\"3\")\n .run_cmd(\"pip install flask\")\n .copy(\"./app\", \"/app\")\n .set_envs({\"FLASK_ENV\": \"production\"})\n .set_start_cmd(\"python /app/main.py\", \"curl -s http://localhost:8000/health\")\n)\n\nbuild_info = template.build(\"my-flask-app:v1.0\")\n```\n\n资料来源：[packages/python-sdk/e2b/template/main.py:1-100]()\n\n## Base Images\n\nThe Template System provides convenience methods for common base images, along with support for custom images and registries.\n\n### Supported Base Images\n\n| Method | Image | Default Variant |\n|--------|-------|-----------------|\n| `fromBaseImage()` | `e2bdev/base:latest` | - |\n| `fromPythonImage()` | `python:{version}` | `3` |\n| `fromNodeImage()` | `node:{variant}` | `lts` |\n| `fromBunImage()` | `oven/bun:{variant}` | `latest` |\n| `fromDebianImage()` | `debian:{variant}` | `stable` |\n| `fromUbuntuImage()` | `ubuntu:{variant}` | `latest` |\n| `fromImage()` | Custom image | Required |\n\n```typescript\n// JavaScript SDK base image examples\nTemplate().fromPythonImage('3.12')\nTemplate().fromNodeImage('20')\nTemplate().fromBunImage('1.3')\n```\n\n```python\n# Python SDK base image examples\nTemplate().from_python_image(\"3.12\")\nTemplate().from_node_image(\"20\")\nTemplate().from_bun_image(\"1.3\")\n```\n\n资料来源：[packages/js-sdk/src/template/types.ts:100-180]()\n\n### Custom Registries\n\nFor private images, configure registry authentication:\n\n```typescript\nimport { Template, GenericDockerRegistry } from 'e2b'\n\nconst registry: GenericDockerRegistry = {\n type: 'registry',\n username: 'myuser',\n password: 'mypassword'\n}\n\nconst template = Template()\n .fromImage('my-private-registry.com/my-image:latest', {\n registries: [registry]\n })\n```\n\n## Build Instructions\n\nTemplates support multiple instruction types that translate directly to Dockerfile commands.\n\n### Instruction Types\n\n| Type | Dockerfile Equivalent | Description |\n|------|----------------------|-------------|\n| `RUN` | `RUN` | Execute shell commands |\n| `COPY` | `COPY` | Copy files into sandbox |\n| `ENV` | `ENV` | Set environment variables |\n| `WORKDIR` | `WORKDIR` | Set working directory |\n| `USER` | `USER` | Set current user |\n\n### Common Instructions\n\n#### Environment Variables\n\n```typescript\ntemplate.setEnvs({ NODE_ENV: 'production', PORT: '8080' })\n```\n\n```python\ntemplate.set_envs({\"NODE_ENV\": \"production\", \"PORT\": \"8080\"})\n```\n\n资料来源：[packages/js-sdk/src/template/types.ts:200-230]()\n\n#### File Operations\n\n```typescript\ntemplate.copy('./local/path', '/remote/path')\ntemplate.copy('./config', '/app/config')\n```\n\n#### Shell Commands\n\n```typescript\ntemplate.runCmd('apt-get update && apt-get install -y vim')\n```\n\n#### Skip Cache\n\nForce rebuild of subsequent layers:\n\n```typescript\ntemplate.skipCache().runCmd('apt-get update')\n```\n\n资料来源：[packages/python-sdk/e2b/template/main.py:150-200]()\n\n## Ready Commands\n\nReady commands verify that the sandbox is fully initialized before accepting connections.\n\n### ReadyCmd Helpers\n\n| Function | Use Case | Implementation |\n|----------|----------|----------------|\n| `waitForPort(port)` | Service listening on port | `nc -z localhost {port}` |\n| `waitForURL(url, statusCode)` | HTTP endpoint availability | `curl` with status check |\n| `waitForProcess(name)` | Daemon process running | `pgrep {name}` |\n| `waitForFile(path)` | File exists in filesystem | `test -f {path}` |\n\n```typescript\nimport { Template, waitForPort, waitForURL, waitForProcess, waitForFile } from 'e2b'\n\nconst template = Template()\n .fromNodeImage()\n .runCmd('npm start')\n .setStartCmd('npm start', waitForPort(3000))\n\nconst template2 = Template()\n .fromPythonImage()\n .setStartCmd('python server.py', waitForURL('http://localhost:8000/health', 200))\n```\n\n资料来源：[packages/js-sdk/src/template/readycmd.ts:1-80]()\n\n## Build Process\n\n### Build Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant TemplateBuilder\n participant BuildAPI\n participant DockerBuild\n participant Registry\n \n User->>TemplateBuilder: Define template\n User->>TemplateBuilder: build(name, options)\n TemplateBuilder->>BuildAPI: POST /templates/build\n BuildAPI->>DockerBuild: Start build\n DockerBuild->>DockerBuild: Build layers\n DockerBuild->>Registry: Push image\n Registry-->>BuildAPI: Build complete\n BuildAPI-->>TemplateBuilder: BuildInfo\n TemplateBuilder-->>User: Template deployed\n```\n\n### Build API Integration\n\nThe JavaScript SDK normalizes build arguments for different calling patterns:\n\n```typescript\n// New pattern - name as parameter\nawait Template.build(template, 'my-template:v1.0')\n\n// Legacy pattern - alias in options\nawait Template.build(template, { alias: 'my-template' })\n```\n\nThe SDK internally calls the E2B Build API which:\n1. Validates the template specification\n2. Initiates Docker build with caching\n3. Monitors build status until completion\n4. Pushes the resulting image to the registry\n\n资料来源：[packages/js-sdk/src/template/index.ts:250-350]()\n\n### Build Options\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `alias` | `string` | Template alias (deprecated) |\n| `tags` | `string[]` | Additional image tags |\n| `timeoutMs` | `number` | Build timeout in milliseconds |\n| `metadata` | `Record` | Custom metadata |\n\n## CLI Integration\n\nThe E2B CLI provides command-line access to template operations.\n\n### Available Commands\n\n| Command | Description |\n|---------|-------------|\n| `e2b template create` | Create a new template from Dockerfile |\n| `e2b template build` | Build and deploy a template |\n| `e2b template publish` | Publish template to registry |\n\n### Build Command\n\n```bash\ne2b template build --name my-template:v1.0\n```\n\nThe CLI reads Dockerfile content and handles:\n- Custom Dockerfile paths\n- Template validation\n- Build polling and status display\n- Error reporting with support links\n\n资料来源：[packages/cli/src/commands/template/build.ts:1-100]()\n\n### Create Command\n\n```bash\ne2b template create my-template\n```\n\nThe create command:\n1. Uploads local template files\n2. Initiates template creation\n3. Polls for completion\n4. Displays example usage code\n\n资料来源：[packages/cli/src/commands/template/create.ts:1-50]()\n\n## State Management\n\nThe template builder enforces valid state transitions through the `TemplateBuilder` and `TemplateFinal` interfaces.\n\n### State Interface Hierarchy\n\n```mermaid\nclassDiagram\n class TemplateBuilder {\n +fromImage(image)\n +runCmd(cmd)\n +copy(src, dest)\n +setEnvs(envs)\n +setStartCmd(start, ready)\n }\n \n class TemplateFinal {\n <>\n }\n \n TemplateBuilder --|> TemplateFinal : after setStartCmd()\n```\n\n### TypeScript Interfaces\n\n```typescript\nexport interface TemplateBuilder {\n fromImage(image: string, options?: FromImageOptions): TemplateBuilder\n runCmd(cmd: string, user?: string): TemplateBuilder\n copy(src: string, dest: string): TemplateBuilder\n setEnvs(envs: Record): TemplateBuilder\n skipCache(): this\n setStartCmd(startCommand: string, readyCommand: string): TemplateFinal\n}\n```\n\nThe `TemplateFinal` interface is an empty marker type that signals the builder is complete and ready for `build()`.\n\n资料来源：[packages/js-sdk/src/template/types.ts:50-150]()\n\n## Dockerfile Generation\n\nTemplates internally generate equivalent Dockerfile instructions:\n\n```typescript\ngenerateDockerfile(): string {\n let dockerfile = `FROM ${this.baseImage}\\n`\n \n for (const instruction of this.instructions) {\n switch (instruction.type) {\n case InstructionType.RUN:\n dockerfile += `RUN ${instruction.args[0]}\\n`\n case InstructionType.COPY:\n dockerfile += `COPY ${instruction.args[0]} ${instruction.args[1]}\\n`\n case InstructionType.ENV:\n const values = instruction.args.map((v, i) => \n i % 2 === 0 ? `${instruction.args[i]}=${instruction.args[i+1]}` : null\n ).filter(Boolean)\n dockerfile += `ENV ${values.join(' ')}\\n`\n }\n }\n \n if (this.startCmd) {\n dockerfile += `ENTRYPOINT ${this.startCmd}\\n`\n }\n \n return dockerfile\n}\n```\n\n资料来源：[packages/js-sdk/src/template/index.ts:350-400]()\n\n## Error Handling\n\nBuild errors are caught and reported with actionable guidance:\n\n```typescript\ncase 'error':\n throw new Error(\n `❌ Building sandbox template ${templateName} failed.\nCheck the logs above for more details or contact us (https://e2b.dev/docs/support) to get help.`\n )\n```\n\n## SDK Configuration\n\nTemplates inherit connection configuration for API communication:\n\n```typescript\nconst config = new ConnectionConfig(sandboxOpts)\nconst client = new ApiClient(config)\n```\n\nConfiguration includes:\n- API key authentication\n- Request timeouts\n- Debug mode for local development\n- Signal handling for cancellation\n\n资料来源：[packages/js-sdk/src/sandbox/index.ts:100-150]()\n\n## Summary\n\nThe E2B Template System provides a unified, fluent API for defining sandbox environments across JavaScript and Python SDKs. Key capabilities include:\n\n- **Base image selection** with convenience methods for common runtimes\n- **Instruction composition** using familiar Dockerfile semantics\n- **Ready command validation** ensuring sandboxes are fully initialized\n- **Build API integration** for remote Docker builds and registry deployment\n- **CLI tooling** for command-line workflow integration\n- **State machine enforcement** preventing invalid template configurations\n\n---\n\n\n\n## Filesystem and Git Operations\n\n### 相关页面\n\n相关主题：[Sandbox Usage](#sandbox-usage)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/js-sdk/src/sandbox/filesystem/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/filesystem/index.ts)\n- [packages/js-sdk/src/sandbox/filesystem/watchHandle.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/filesystem/watchHandle.ts)\n- [packages/js-sdk/src/sandbox/git/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/git/index.ts)\n- [packages/python-sdk/e2b/sandbox/filesystem/filesystem.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox/filesystem/filesystem.py)\n- [packages/python-sdk/e2b/sandbox_async/filesystem/filesystem.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_async/filesystem/filesystem.py)\n- [packages/python-sdk/e2b/sandbox_sync/filesystem/filesystem.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_sync/filesystem/filesystem.py)\n- [packages/python-sdk/e2b/sandbox/git.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox/git.py)\n- [packages/python-sdk/e2b/sandbox_async/git.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_async/git.py)\n- [packages/python-sdk/e2b/sandbox_sync/git.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_sync/git.py)\n- [packages/python-sdk/e2b/sandbox/_git/__init__.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox/_git/__init__.py)\n- [packages/python-sdk/e2b/sandbox/_git/args.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox/_git/args.py)\n- [packages/python-sdk/e2b/sandbox/_git/auth.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox/_git/auth.py)\n \n\n# Filesystem and Git Operations\n\n## Overview\n\nThe E2B SDK provides comprehensive filesystem and Git operations for interacting with sandbox environments. These operations allow developers to read, write, and watch files within isolated sandboxes, as well as perform Git operations including repository cloning with various authentication methods.\n\nFilesystem operations are available through dedicated filesystem classes that handle file I/O with support for multiple data formats (text, bytes, blob, stream), compression, and user-specific permissions. Git operations provide a fluent API for cloning repositories using SSH keys, tokens, or username/password authentication. 资料来源：[packages/js-sdk/src/sandbox/filesystem/index.ts:1-100]()\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n A[Sandbox Instance] --> B[Filesystem API]\n A --> C[Git API]\n \n B --> D[envd API - /files endpoint]\n B --> E[Volume API - /volumecontent endpoint]\n \n C --> F[envd API - git operations]\n C --> G[SSH Key Management]\n C --> H[Token Auth]\n C --> I[Username/Password Auth]\n \n J[Read Operations] --> K[text | bytes | blob | stream]\n L[Write Operations] --> M[multipart/form-data | application/octet-stream]\n N[Watch Operations] --> O[FilesystemEvent stream]\n```\n\n## Filesystem Operations\n\n### Core Components\n\nThe filesystem module is implemented separately in both JavaScript and Python SDKs with consistent functionality across both platforms.\n\n#### JavaScript SDK\n\nThe JavaScript SDK exposes filesystem operations through the `Sandbox.filesystem` property, providing type-safe methods for file operations. 资料来源：[packages/js-sdk/src/sandbox/filesystem/index.ts:1-50]()\n\n#### Python SDK\n\nThe Python SDK provides filesystem access through both synchronous (`sandbox_sync`) and asynchronous (`sandbox_async`) implementations, allowing developers to choose the appropriate model for their application. 资料来源：[packages/python-sdk/e2b/sandbox_sync/filesystem/filesystem.py:1-50]()\n\n### Reading Files\n\n#### Supported Formats\n\n| Format | Return Type | Description |\n|--------|-------------|-------------|\n| `text` | `string` | File content as plain text (default) |\n| `bytes` | `Uint8Array` / `bytes` | Raw binary content |\n| `blob` | `Blob` | Web API Blob object |\n| `stream` | `ReadableStream` | Streaming response |\n\nThe `read` method automatically handles user version compatibility by checking the envd API version. If the sandbox's envd version is below the default user version threshold, it falls back to a default username for authentication. 资料来源：[packages/js-sdk/src/sandbox/filesystem/index.ts:60-80]()\n\n#### Read Options\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `format` | `'text' \\| 'bytes' \\| 'blob' \\| 'stream'` | `'text'` | Output format |\n| `gzip` | `boolean` | `false` | Request gzip-compressed response |\n| `user` | `string` | `undefined` | Run as specific user |\n| `signal` | `AbortSignal` | `undefined` | Cancellation signal |\n| `requestTimeoutMs` | `number` | `undefined` | Request timeout |\n\n#### JavaScript SDK Example\n\n```typescript\n// Read as text\nconst content = await sandbox.filesystem.read('/path/to/file.txt')\n\n// Read as bytes\nconst bytes = await sandbox.filesystem.read('/path/to/file.bin', { format: 'bytes' })\n\n// Read with gzip compression\nconst compressed = await sandbox.filesystem.read('/path/to/large.txt', { gzip: true })\n```\n\n#### Python SDK Example\n\n```python\n# Read as text\ncontent = sandbox.filesystem.read('/path/to/file.txt')\n\n# Read as bytes\nbytes_data = sandbox.filesystem.read('/path/to/file.bin', format='bytes')\n\n# Async version\ncontent = await sandbox.filesystem.read('/path/to/file.txt')\n```\n\n### Writing Files\n\nThe write operation supports multiple files in a single call and creates necessary parent directories automatically. 资料来源：[packages/python-sdk/e2b/sandbox_sync/filesystem/filesystem.py:40-70]()\n\n#### Write Options\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `files` | `WriteEntry[]` | Required | List of files to write |\n| `user` | `string` | `undefined` | Run as specific user |\n| `gzip` | `boolean` | `false` | Use gzip compression |\n| `use_octet_stream` | `boolean` | `false` | Use octet-stream upload (requires envd 0.5.7+) |\n| `request_timeout` | `number` | `undefined` | Request timeout |\n\n#### WriteEntry Structure\n\n```typescript\ninterface WriteEntry {\n path: string // Destination path in sandbox\n data: string | Uint8Array // File content\n}\n```\n\n#### Upload Methods\n\nThe SDK supports two upload methods:\n\n1. **multipart/form-data** (default, universally supported)\n2. **application/octet-stream** (faster, requires envd 0.5.7+)\n\nWhen `use_octet_stream` is enabled and the envd version supports it, the upload uses `application/octet-stream` content type. Otherwise, it gracefully falls back to multipart form data. 资料来源：[packages/python-sdk/e2b/sandbox_sync/filesystem/filesystem.py:60-85]()\n\n#### Write Example\n\n```typescript\nawait sandbox.filesystem.write([\n { path: '/app/config.json', data: JSON.stringify(config) },\n { path: '/app/data.bin', data: binaryBuffer }\n])\n```\n\n### Directory Watching\n\nThe filesystem module provides directory watching capabilities through the `WatchHandle` class, allowing applications to monitor filesystem changes in real-time. 资料来源：[packages/js-sdk/src/sandbox/filesystem/watchHandle.ts:30-50]()\n\n#### WatchHandle Class\n\n```typescript\nclass WatchHandle {\n // Stop watching the directory\n async stop(): void\n \n // Event callback\n onEvent?: (event: FilesystemEvent) => void | Promise\n \n // Exit callback with optional error\n onExit?: (err?: Error) => void | Promise\n}\n```\n\n#### FilesystemEvent Structure\n\n```typescript\ninterface FilesystemEvent {\n name: string // Name of the changed file/directory\n type: FilesystemEventType // 'created' | 'modified' | 'deleted'\n}\n```\n\n#### Watch Flow\n\n```mermaid\nsequenceDiagram\n participant App as Application\n participant WH as WatchHandle\n participant API as envd API\n participant FS as Sandbox FS\n \n App->>WH: watch('/path')\n WH->>API: Subscribe to filesystem events\n FS->>API: File change detected\n API->>WH: Event stream\n WH->>App: onEvent callback\n App->>WH: stop()\n WH->>API: Unsubscribe\n```\n\n#### Watch Example\n\n```typescript\nconst handle = await sandbox.filesystem.watch('/app', {\n onEvent: (event) => {\n console.log(`File ${event.type}: ${event.name}`)\n },\n onExit: (err) => {\n if (err) console.error('Watch error:', err)\n }\n})\n\n// Later: stop watching\nawait handle.stop()\n```\n\n### File Information\n\nWhen writing files, the operation returns `WriteInfo` objects containing metadata about the created/modified files.\n\n#### WriteInfo Structure\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `name` | `string` | Name of the filesystem object |\n| `type` | `FileType` | Type of object (file, directory, symlink) |\n| `path` | `string` | Full path to the object |\n\n#### EntryInfo (for directory listings)\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `size` | `number` | Size in bytes |\n| `mode` | `number` | File mode and permission bits |\n| `permissions` | `string` | String representation (e.g., 'rwxr-xr-x') |\n| `owner` | `string` | Owner username |\n| `group` | `string` | Group owner |\n| `modifiedTime` | `Date` | Last modification time |\n| `symlinkTarget` | `string` | Target if symlink |\n\n## Git Operations\n\nGit operations provide a fluent API for cloning and managing Git repositories within sandboxes. The implementation supports multiple authentication methods and comprehensive git functionality. 资料来源：[packages/python-sdk/e2b/sandbox/git.py:1-80]()\n\n### Authentication Methods\n\nThe SDK supports three authentication methods for Git operations:\n\n| Method | Description | Use Case |\n|--------|-------------|----------|\n| SSH Key | Use predefined SSH key stored in E2B | Private repository access |\n| Token | Personal Access Token or GitHub Token | CI/CD scenarios |\n| Username/Password | Basic authentication | Legacy systems |\n\n#### Authentication Configuration\n\n```python\n# SSH Key authentication (most common)\ngit.auth.ssh_key('my-ssh-key-name')\n\n# Token authentication\ngit.auth.token('ghp_xxxxxxxxxxxx')\n\n# Username/Password\ngit.auth.username_password('user', 'password')\n```\n\n### Git Clone Operations\n\n#### Clone Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `url` | `string` | Yes | Repository URL |\n| `path` | `string` | No | Destination path (defaults to repo name) |\n| `branch` | `string` | No | Specific branch to clone |\n| `depth` | `number` | No | Clone depth for shallow clone |\n| `recursive` | `bool` | No | Clone submodules (default: true) |\n\n#### Clone Example\n\n```python\n# Basic clone\nsandbox.git.clone('https://github.com/user/repo.git')\n\n# Clone to specific path\nsandbox.git.clone('https://github.com/user/repo.git', '/workspace/project')\n\n# Clone specific branch\nsandbox.git.clone('https://github.com/user/repo.git', branch='develop')\n\n# Shallow clone\nsandbox.git.clone('https://github.com/user/repo.git', depth=1)\n\n# With authentication\nsandbox.git.auth.token('ghp_xxx').clone('https://github.com/user/private.git')\n```\n\n### Git Module Structure\n\nThe Python SDK organizes Git functionality across multiple modules:\n\n```mermaid\nclassDiagram\n class GitCore {\n +clone()\n +auth: GitAuth\n }\n class GitAuth {\n +ssh_key(name)\n +token(token)\n +username_password(user, pass)\n }\n class GitArgs {\n +build_clone_args()\n }\n \n GitCore --> GitAuth\n GitCore --> GitArgs\n```\n\n#### Module Responsibilities\n\n| Module | Purpose |\n|--------|---------|\n| `e2b/sandbox/_git/__init__.py` | Core git operations and command building |\n| `e2b/sandbox/_git/args.py` | Argument construction for git commands |\n| `e2b/sandbox/_git/auth.py` | Authentication configuration management |\n\n### JavaScript SDK Git Operations\n\nThe JavaScript SDK provides similar git functionality with a fluent builder pattern:\n\n```typescript\n// Clone repository\nawait sandbox.git.clone('https://github.com/user/repo.git')\n\n// Clone with options\nawait sandbox.git.clone('https://github.com/user/repo.git', {\n path: '/workspace/project',\n branch: 'main',\n depth: 1\n})\n\n// With authentication\nawait sandbox.git.auth.sshKey('my-key')\nawait sandbox.git.clone('git@github.com:user/private.git')\n```\n\n## Error Handling\n\n### Filesystem Errors\n\nThe SDK provides specific error types for filesystem operations:\n\n| Error Type | Condition |\n|------------|-----------|\n| `FileNotFoundError` | File or directory does not exist |\n| `NotFoundError` | Volume path not found |\n| `SandboxError` | General sandbox communication error |\n| `CommandExitError` | Command execution failed |\n\n#### Error Mapping\n\n```mermaid\ngraph LR\n A[HTTP/RPC Error] --> B{Error Code}\n B -->|404| C[FileNotFoundError]\n B -->|Default| D[SandboxError]\n \n E[API Response] --> F{Status Code}\n F -->|404| G[NotFoundError]\n F -->|Default| H[Generic Error]\n```\n\n### Error Handling Example\n\n```typescript\ntry {\n const content = await sandbox.filesystem.read('/path/to/file')\n} catch (error) {\n if (error instanceof FileNotFoundError) {\n console.log('File does not exist')\n } else if (error instanceof SandboxError) {\n console.log('Sandbox communication error:', error.message)\n }\n}\n```\n\n## Version Compatibility\n\n### envd Version Requirements\n\n| Feature | Minimum envd Version |\n|---------|---------------------|\n| Basic filesystem read/write | 0.1.0 |\n| Default user handling | Automatic fallback for older versions |\n| Octet-stream upload | 0.5.7 |\n| Gzip compression | All versions |\n\n### Version Checking\n\nThe SDK automatically checks the envd version during sandbox initialization and adjusts behavior accordingly:\n\n```typescript\n// Automatic version check in read operation\nif (user == undefined && compareVersions(envdVersion, ENVD_DEFAULT_USER) < 0) {\n user = defaultUsername\n}\n```\n\n## Best Practices\n\n1. **Use Appropriate Formats**: Choose `stream` for large files to avoid memory issues\n2. **Enable Compression**: Use gzip for text-based files larger than 1KB\n3. **Use Octet-Stream**: Enable for faster uploads when targeting envd 0.5.7+\n4. **Handle Errors**: Always catch specific error types for better error handling\n5. **Set Timeouts**: Configure appropriate request timeouts for network operations\n6. **Watch Cleanup**: Always call `stop()` on WatchHandle when done\n\n## Summary\n\nThe Filesystem and Git Operations in E2B provide comprehensive tools for:\n\n- **Reading files** in multiple formats (text, bytes, blob, stream) with optional compression\n- **Writing files** with automatic directory creation and multiple upload methods\n- **Watching directories** for real-time filesystem event monitoring\n- **Git operations** with flexible authentication (SSH keys, tokens, username/password)\n- **Robust error handling** with specific error types and version compatibility\n\n---\n\n\n\n## Network Configuration\n\n### 相关页面\n\n相关主题：[Sandbox Usage](#sandbox-usage), [Sandbox Management](#sandbox-management)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/js-sdk/src/sandbox/network.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/network.ts)\n- [packages/python-sdk/e2b/sandbox/network.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox/network.py)\n- [packages/python-sdk/e2b/api/client/models/sandbox_network_config.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/api/client/models/sandbox_network_config.py)\n- [packages/js-sdk/src/connectionConfig.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/connectionConfig.ts)\n \n\n# Network Configuration\n\nE2B provides comprehensive network configuration capabilities for sandboxes, allowing users to control DNS resolution, port access rules, and VPN connectivity. This document describes the network configuration system across the JavaScript and Python SDKs.\n\n## Overview\n\nNetwork Configuration in E2B enables fine-grained control over how sandboxes communicate with external networks and how network traffic is managed. Each sandbox can be configured with custom DNS settings, port access policies, and optional VPN tunnel support.\n\n资料来源：[packages/js-sdk/src/sandbox/network.ts:1-50]()\n\n## Architecture\n\nThe network configuration system consists of three main components that work together to manage sandbox networking:\n\n```mermaid\ngraph TD\n A[Sandbox Creation] --> B[NetworkConfig]\n B --> C[DNS Configuration]\n B --> D[Port Rules]\n B --> E[VPN Settings]\n C --> F[Sandbox DNS Resolution]\n D --> G[Port Access Control]\n E --> H[VPN Tunnel]\n```\n\n### Data Flow\n\nWhen creating a sandbox, the network configuration is serialized and sent to the E2B API as part of the sandbox creation request. The API validates and stores the configuration, which is then applied when the sandbox environment initializes.\n\n资料来源：[packages/python-sdk/e2b/api/client/models/sandbox_network_config.py:1-100]()\n\n## JavaScript SDK Implementation\n\n### NetworkConfig Interface\n\nThe JavaScript SDK provides a `NetworkConfig` interface located in `packages/js-sdk/src/sandbox/network.ts`:\n\n```typescript\ninterface NetworkConfig {\n dns?: DNSConfig\n ports?: PortConfig[]\n vpn?: VPNConfig\n}\n```\n\n#### DNS Configuration\n\nControls how the sandbox resolves domain names:\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `customServers` | `string[]` | List of custom DNS server IPs |\n| `blockAutoDetect` | `boolean` | Whether to block auto-detected DNS |\n\n资料来源：[packages/js-sdk/src/sandbox/network.ts:10-30]()\n\n#### Port Configuration\n\nManages inbound and outbound port access:\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `port` | `number` | The port number to configure |\n| `protocol` | `'tcp' \\| 'udp'` | Network protocol |\n| `access` | `'allow' \\| 'deny'` | Access rule for the port |\n| `description` | `string` | Optional description |\n\n资料来源：[packages/js-sdk/src/sandbox/network.ts:35-45]()\n\n#### VPN Configuration\n\nProvides VPN tunnel support:\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `enabled` | `boolean` | Enable/disable VPN tunnel |\n| `config` | `VPNConfig` | VPN configuration object |\n\n资料来源：[packages/js-sdk/src/sandbox/network.ts:50-60]()\n\n### Usage Example\n\n```typescript\nimport { Sandbox, NetworkConfig } from 'e2b'\n\nconst networkConfig: NetworkConfig = {\n dns: {\n customServers: ['8.8.8.8', '1.1.1.1'],\n blockAutoDetect: true\n },\n ports: [\n { port: 80, protocol: 'tcp', access: 'allow', description: 'HTTP' },\n { port: 443, protocol: 'tcp', access: 'allow', description: 'HTTPS' },\n { port: 22, protocol: 'tcp', access: 'deny', description: 'SSH disabled' }\n ],\n vpn: {\n enabled: true\n }\n}\n\nconst sandbox = await Sandbox.create('my-template', {\n network: networkConfig\n})\n```\n\n资料来源：[packages/js-sdk/src/sandbox/sandboxApi.ts:1-50]()\n\n## Python SDK Implementation\n\n### NetworkConfig Class\n\nThe Python SDK provides a fluent API for network configuration in `packages/python-sdk/e2b/sandbox/network.py`:\n\n```python\nclass NetworkConfig:\n def __init__(self) -> None:\n self._dns: Optional[DNSConfig] = None\n self._ports: List[PortRule] = []\n self._vpn: Optional[VPNConfig] = None\n```\n\n#### DNS Configuration\n\n```python\nclass DNSConfig:\n custom_servers: Optional[List[str]] = None\n block_auto_detect: bool = False\n```\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `custom_servers` | `List[str]` | `None` | Custom DNS server IPs |\n| `block_auto_detect` | `bool` | `False` | Block auto-detected DNS |\n\n资料来源：[packages/python-sdk/e2b/sandbox/network.py:1-80]()\n\n#### Port Rules\n\n```python\nclass PortRule:\n port: int\n protocol: str # 'tcp' or 'udp'\n access: str # 'allow' or 'deny'\n description: Optional[str] = None\n```\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `port` | `int` | Yes | Port number |\n| `protocol` | `str` | Yes | Network protocol |\n| `access` | `str` | Yes | Access rule |\n| `description` | `str` | No | Rule description |\n\n资料来源：[packages/python-sdk/e2b/sandbox/network.py:80-150]()\n\n### Fluent API Methods\n\nThe Python SDK provides a fluent interface for building network configurations:\n\n#### DNS Configuration\n\n```python\ndef dns(self, servers: List[str], block_auto_detect: bool = False) -> \"NetworkConfig\":\n \"\"\"Configure custom DNS servers.\"\"\"\n self._dns = DNSConfig(\n custom_servers=servers,\n block_auto_detect=block_auto_detect\n )\n return self\n```\n\n#### Port Management\n\n```python\ndef allow_port(self, port: int, protocol: str = \"tcp\", description: str = None) -> \"NetworkConfig\":\n \"\"\"Allow traffic on specified port.\"\"\"\n self._ports.append(PortRule(\n port=port,\n protocol=protocol,\n access=\"allow\",\n description=description\n ))\n return self\n\ndef deny_port(self, port: int, protocol: str = \"tcp\", description: str = None) -> \"NetworkConfig\":\n \"\"\"Deny traffic on specified port.\"\"\"\n self._ports.append(PortRule(\n port=port,\n protocol=protocol,\n access=\"deny\",\n description=description\n ))\n return self\n```\n\n#### VPN Configuration\n\n```python\ndef enable_vpn(self) -> \"NetworkConfig\":\n \"\"\"Enable VPN tunnel for the sandbox.\"\"\"\n self._vpn = VPNConfig(enabled=True)\n return self\n```\n\n资料来源：[packages/python-sdk/e2b/sandbox/network.py:150-250]()\n\n### Python Usage Example\n\n```python\nfrom e2b import Sandbox, NetworkConfig\n\nnetwork = (\n NetworkConfig()\n .dns(servers=['8.8.8.8', '1.1.1.1'], block_auto_detect=True)\n .allow_port(80, protocol='tcp', description='HTTP traffic')\n .allow_port(443, protocol='tcp', description='HTTPS traffic')\n .allow_port(5432, protocol='tcp', description='PostgreSQL')\n .deny_port(22, protocol='tcp', description='SSH disabled')\n .enable_vpn()\n)\n\nsandbox = await Sandbox.create(\n template='my-template',\n network=network\n)\n```\n\n资料来源：[packages/python-sdk/e2b/sandbox_async/main.py:1-80]()\n\n## API Model\n\nThe backend API uses a standardized `SandboxNetworkConfig` model defined in OpenAPI format:\n\n```python\nclass SandboxNetworkConfig:\n dns: Optional[DNSConfig] = None\n ports: Optional[List[PortRule]] = None\n vpn: Optional[VPNConfig] = None\n```\n\n资料来源：[packages/python-sdk/e2b/api/client/models/sandbox_network_config.py:1-100]()\n\n### Serialization\n\nThe configuration is serialized to JSON when sent to the API:\n\n```json\n{\n \"dns\": {\n \"customServers\": [\"8.8.8.8\", \"1.1.1.1\"],\n \"blockAutoDetect\": true\n },\n \"ports\": [\n {\"port\": 80, \"protocol\": \"tcp\", \"access\": \"allow\"},\n {\"port\": 443, \"protocol\": \"tcp\", \"access\": \"allow\"}\n ],\n \"vpn\": {\"enabled\": true}\n}\n```\n\n资料来源：[packages/js-sdk/src/sandbox/sandboxApi.ts:50-70]()\n\n## Sandbox Creation Integration\n\nNetwork configuration is passed during sandbox creation through the `network` option:\n\n### JavaScript\n\n```typescript\nconst sandboxInfo = await SandboxApi.createSandbox(\n template,\n timeoutMs,\n {\n network: networkConfig,\n // ... other options\n }\n)\n```\n\n### Python\n\n```python\nsandbox = await cls._create(\n template=template,\n timeout=timeout,\n network=network,\n # ... other options\n)\n```\n\n资料来源：[packages/js-sdk/src/sandbox/sandboxApi.ts:1-50]()\n资料来源：[packages/python-sdk/e2b/sandbox_async/main.py:1-60]()\n\n## Default Behavior\n\nWhen no network configuration is provided, the sandbox uses default network settings:\n\n| Setting | Default Value |\n|---------|---------------|\n| DNS | Auto-detected system DNS |\n| Ports | All ports allowed |\n| VPN | Disabled |\n\nInternet access is enabled by default unless explicitly disabled via `allow_internet_access: false`.\n\n资料来源：[packages/js-sdk/src/sandbox/sandboxApi.ts:20-40]()\n\n## Best Practices\n\n1. **Explicit Port Rules**: Always explicitly define port access rules rather than relying on defaults for production workloads.\n\n2. **DNS Configuration**: Use specific DNS servers when you need consistent resolution behavior across sandbox instances.\n\n3. **VPN for Sensitive Workloads**: Enable VPN when handling sensitive data that requires encrypted tunnel communication.\n\n4. **Protocol Specificity**: Specify both port and protocol to avoid unintended access.\n\n## Related Documentation\n\n- [Sandbox API Reference](packages/js-sdk/src/sandbox/sandboxApi.ts)\n- [Connection Configuration](packages/js-sdk/src/connectionConfig.ts)\n- [Template Building](packages/cli/src/commands/template/build.ts)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：e2b-dev/E2B\n\n摘要：发现 20 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：配置坑 - 来源证据：process was not killed when auto paused。\n\n## 1. 配置坑 · 来源证据：process was not killed when auto paused\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：process was not killed when auto paused\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_66994844a2ec44a784ad5b80307d82e9 | https://github.com/e2b-dev/E2B/issues/1031 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 安装坑 · 来源证据：Closed Port Error\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Closed Port Error\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_33133a8885a44301a7f98b23844205cc | https://github.com/e2b-dev/E2B/issues/907 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：Please add skills to use with any ai agent to use e2b in our project\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Please add skills to use with any ai agent to use e2b in our project\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8cebd572dbd2485ab6cdbc13733fdee0 | https://github.com/e2b-dev/E2B/issues/1138 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 安装坑 · 来源证据：[Bug]: Incorrect info about webhooks in docs and dashboard\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: Incorrect info about webhooks in docs and dashboard\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8b25841679fd4eaea5d759a33dfad3b1 | https://github.com/e2b-dev/E2B/issues/1103 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 5. 安装坑 · 来源证据：[Bug]: Sandbox create fails from template, but succeeds without template\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: Sandbox create fails from template, but succeeds without template\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3ae274a17e7e420ca9f2cd6e7c6105bd | https://github.com/e2b-dev/E2B/issues/1130 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 安装坑 · 来源证据：build status polling timed out\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：build status polling timed out\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_88fc7403d6a44edb8b8d4c9deaff0279 | https://github.com/e2b-dev/E2B/issues/1009 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 7. 配置坑 · 来源证据：Paused sandbox is not persisting the file changes / addition after second time resumed and onward\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Paused sandbox is not persisting the file changes / addition after second time resumed and onward\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2fc5340254c94ae2931673fede53e25b | https://github.com/e2b-dev/E2B/issues/884 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 8. 配置坑 · 社区讨论暴露的待验证问题：[Bug]: torch.compile fails for Gemma3n on pytorch 2.8\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：[Bug]: torch.compile fails for Gemma3n on pytorch 2.8 ### Your current environment The output of python collect_env.py
```text Your output of `python collect_env.py` here ``` ### 🐛 Describe the bug run ``` vllm serve google/gemma-3n-E2B-it -tp 1 ``` on torch==2.8.0:…\n- 对用户的影响：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。\n- 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。\n- 证据：social_signal:github | ssig_3c3209f718cd4d108c88e3bf9d35db24 | https://github.com/vllm-project/vllm/issues/24547 | [Bug]: torch.compile fails for Gemma3n on pytorch 2.8\n\n## 9. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:609539715 | https://github.com/e2b-dev/E2B | README/documentation is current enough for a first validation pass.\n\n## 10. 维护坑 · 来源证据：When using autoPause in sandbox creation, connect overrides this when resuming the sandbox again\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：When using autoPause in sandbox creation, connect overrides this when resuming the sandbox again\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3002fb1e72dd4aa2ab6baed80425d7b2 | https://github.com/e2b-dev/E2B/issues/875 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 11. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:609539715 | https://github.com/e2b-dev/E2B | last_activity_observed missing\n\n## 12. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:609539715 | https://github.com/e2b-dev/E2B | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:609539715 | https://github.com/e2b-dev/E2B | no_demo; severity=medium\n\n## 14. 安全/权限坑 · 来源证据：(feature request) Run-scoped messaging for multi-sandbox agent workflows\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：(feature request) Run-scoped messaging for multi-sandbox agent workflows\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a6ad64f1b6d54498906e63b880471ac4 | https://github.com/e2b-dev/E2B/issues/1330 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 15. 安全/权限坑 · 来源证据：AuthenticationError: Unauthorized, please check your credentials. - Invalid API key\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：AuthenticationError: Unauthorized, please check your credentials. - Invalid API key\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c6225e71e02943b7a367a36c86c96b65 | https://github.com/e2b-dev/E2B/issues/980 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 16. 安全/权限坑 · 来源证据：Docker Build Secrets Support\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Docker Build Secrets Support\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6d5e325b8d00480b8ac7acf0b5b01379 | https://github.com/e2b-dev/E2B/issues/815 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 17. 安全/权限坑 · 来源证据：How to use the file that I uploaded when I create template\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：How to use the file that I uploaded when I create template\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_57466d7f984143c1bb2ae3fb20b9b4f0 | https://github.com/e2b-dev/E2B/issues/1049 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：Template Build Fails with \"syncing took too long\" Error\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Template Build Fails with \"syncing took too long\" Error\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4c757d3a005b45989cf3f2e3a6f4433b | https://github.com/e2b-dev/E2B/issues/996 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 19. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:609539715 | https://github.com/e2b-dev/E2B | issue_or_pr_quality=unknown\n\n## 20. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:609539715 | https://github.com/e2b-dev/E2B | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：e2b-dev/E2B\n\n摘要：发现 20 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：配置坑 - 来源证据：process was not killed when auto paused。\n\n## 1. 配置坑 · 来源证据：process was not killed when auto paused\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：process was not killed when auto paused\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_66994844a2ec44a784ad5b80307d82e9 | https://github.com/e2b-dev/E2B/issues/1031 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 安装坑 · 来源证据：Closed Port Error\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Closed Port Error\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_33133a8885a44301a7f98b23844205cc | https://github.com/e2b-dev/E2B/issues/907 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：Please add skills to use with any ai agent to use e2b in our project\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Please add skills to use with any ai agent to use e2b in our project\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8cebd572dbd2485ab6cdbc13733fdee0 | https://github.com/e2b-dev/E2B/issues/1138 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 安装坑 · 来源证据：[Bug]: Incorrect info about webhooks in docs and dashboard\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: Incorrect info about webhooks in docs and dashboard\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8b25841679fd4eaea5d759a33dfad3b1 | https://github.com/e2b-dev/E2B/issues/1103 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 5. 安装坑 · 来源证据：[Bug]: Sandbox create fails from template, but succeeds without template\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: Sandbox create fails from template, but succeeds without template\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3ae274a17e7e420ca9f2cd6e7c6105bd | https://github.com/e2b-dev/E2B/issues/1130 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 安装坑 · 来源证据：build status polling timed out\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：build status polling timed out\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_88fc7403d6a44edb8b8d4c9deaff0279 | https://github.com/e2b-dev/E2B/issues/1009 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 7. 配置坑 · 来源证据：Paused sandbox is not persisting the file changes / addition after second time resumed and onward\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Paused sandbox is not persisting the file changes / addition after second time resumed and onward\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2fc5340254c94ae2931673fede53e25b | https://github.com/e2b-dev/E2B/issues/884 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 8. 配置坑 · 社区讨论暴露的待验证问题：[Bug]: torch.compile fails for Gemma3n on pytorch 2.8\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：[Bug]: torch.compile fails for Gemma3n on pytorch 2.8 ### Your current environment The output of python collect_env.py
```text Your output of `python collect_env.py` here ``` ### 🐛 Describe the bug run ``` vllm serve google/gemma-3n-E2B-it -tp 1 ``` on torch==2.8.0:…\n- 对用户的影响：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。\n- 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。\n- 证据：social_signal:github | ssig_3c3209f718cd4d108c88e3bf9d35db24 | https://github.com/vllm-project/vllm/issues/24547 | [Bug]: torch.compile fails for Gemma3n on pytorch 2.8\n\n## 9. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:609539715 | https://github.com/e2b-dev/E2B | README/documentation is current enough for a first validation pass.\n\n## 10. 维护坑 · 来源证据：When using autoPause in sandbox creation, connect overrides this when resuming the sandbox again\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：When using autoPause in sandbox creation, connect overrides this when resuming the sandbox again\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3002fb1e72dd4aa2ab6baed80425d7b2 | https://github.com/e2b-dev/E2B/issues/875 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 11. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:609539715 | https://github.com/e2b-dev/E2B | last_activity_observed missing\n\n## 12. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:609539715 | https://github.com/e2b-dev/E2B | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:609539715 | https://github.com/e2b-dev/E2B | no_demo; severity=medium\n\n## 14. 安全/权限坑 · 来源证据：(feature request) Run-scoped messaging for multi-sandbox agent workflows\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：(feature request) Run-scoped messaging for multi-sandbox agent workflows\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a6ad64f1b6d54498906e63b880471ac4 | https://github.com/e2b-dev/E2B/issues/1330 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 15. 安全/权限坑 · 来源证据：AuthenticationError: Unauthorized, please check your credentials. - Invalid API key\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：AuthenticationError: Unauthorized, please check your credentials. - Invalid API key\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c6225e71e02943b7a367a36c86c96b65 | https://github.com/e2b-dev/E2B/issues/980 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 16. 安全/权限坑 · 来源证据：Docker Build Secrets Support\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Docker Build Secrets Support\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6d5e325b8d00480b8ac7acf0b5b01379 | https://github.com/e2b-dev/E2B/issues/815 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 17. 安全/权限坑 · 来源证据：How to use the file that I uploaded when I create template\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：How to use the file that I uploaded when I create template\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_57466d7f984143c1bb2ae3fb20b9b4f0 | https://github.com/e2b-dev/E2B/issues/1049 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：Template Build Fails with \"syncing took too long\" Error\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Template Build Fails with \"syncing took too long\" Error\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4c757d3a005b45989cf3f2e3a6f4433b | https://github.com/e2b-dev/E2B/issues/996 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 19. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:609539715 | https://github.com/e2b-dev/E2B | issue_or_pr_quality=unknown\n\n## 20. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:609539715 | https://github.com/e2b-dev/E2B | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# E2B - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for e2b-dev/E2B.\n\nProject:\n- Name: E2B\n- Repository: https://github.com/e2b-dev/E2B\n- Summary: Open-source, secure environment with real-world tools for enterprise-grade agents.\n- Host target: local_cli\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: Open-source, secure environment with real-world tools for enterprise-grade agents.\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Open-source, secure environment with real-world tools for enterprise-grade agents.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. overview: Overview. Produce one small intermediate artifact and wait for confirmation.\n2. sandbox-usage: Sandbox Usage. Produce one small intermediate artifact and wait for confirmation.\n3. js-sdk: JavaScript/TypeScript SDK. Produce one small intermediate artifact and wait for confirmation.\n4. python-sdk: Python SDK. Produce one small intermediate artifact and wait for confirmation.\n5. sandbox-management: Sandbox Management. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/e2b-dev/E2B\n- https://github.com/e2b-dev/E2B#readme\n- README.md\n- CLAUDE.md\n- packages/js-sdk/src/index.ts\n- packages/python-sdk/e2b/__init__.py\n- packages/js-sdk/src/sandbox/index.ts\n- packages/js-sdk/src/sandbox/sandboxApi.ts\n- packages/python-sdk/e2b/sandbox/main.py\n- packages/python-sdk/e2b/sandbox/sandbox_api.py\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：e2b-dev/E2B\n\n## 官方安装入口\n\n### Node.js / npm · 官方安装入口\n\n```bash\nnpm i e2b\n```\n\n来源：https://github.com/e2b-dev/E2B#readme\n\n## 来源\n\n- repo: https://github.com/e2b-dev/E2B\n- docs: https://github.com/e2b-dev/E2B#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_f21c731f96224a40a2c234a37a3e5491"
}