Add Amp sandbox tutorial

[SystemSculpt]

Summary

• add a dedicated Amp-on-Blaxel tutorial
• cover TypeScript and Python setup with secure AMP_API_KEY handling
• stream and validate Amp's structured output
• continue the same private Amp thread after sandbox standby and reconnect
• document interactive terminal use, safety guidance, troubleshooting, and cleanup
• add the tutorial to the main Tutorials and Examples navigation

Why

Users need one complete path from account setup through a real Amp task, reconnection, and cleanup. The guide keeps the examples readable while checking both process exit status and Amp's final structured result.

Verification

• Mintlify strict build validation passed
• Mintlify broken-link validation passed
• local rendered preview loaded the complete tutorial and navigation
• TypeScript type checks and six runtime unit tests passed
• five Python runtime unit tests passed
• a live Amp task completed in a Blaxel sandbox, entered standby, reconnected through a new SDK instance, and continued the same thread

Dependency

This documentation depends on blaxel-ai/sandbox#285. Do not merge or publish this tutorial until the Amp image is approved and released.

No Amp outreach is included in this PR.

Linear: ENG-4614, ENG-4631

---

Note

Adds a complete tutorial (Tutorials/Amp.mdx) for running Amp inside a Blaxel sandbox with TypeScript and Python examples covering sandbox creation, streaming a coding task, continuing a thread after reconnection, and cleanup. Also adds the tutorial to the docs navigation in docs.json.

^{Written by Mendral for commit 77f0472.}

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
blaxel	🟢 Ready	View Preview	Aug 10, 2026, 6:33 PM

[mendral-app]

🔍 PR Interaction Flow

This is a docs-only PR (new tutorial + nav entry), so there are no runtime code changes. However, the tutorial documents a meaningful interaction flow between components. Here's a sequence diagram of the user workflow described in the tutorial:

sequenceDiagram
    participant User as User Script
    participant SDK as Blaxel SDK
    participant Sandbox as Blaxel Sandbox
    participant Git as Git Host
    participant Amp as Amp CLI

    User->>SDK: createIfNotExists("amp-sandbox")
    SDK->>Sandbox: Provision (blaxel/amp:latest, 8GB, env: AMP_API_KEY)
    Sandbox-->>SDK: Sandbox ready
    SDK-->>User: SandboxInstance

    User->>Sandbox: process.exec(git clone)
    Sandbox->>Git: git clone --depth 1
    Git-->>Sandbox: Repository files
    Sandbox-->>User: exitCode 0

    User->>Sandbox: process.exec(amp --stream-json --execute ...)
    Sandbox->>Amp: Run task in repository
    Amp-->>Sandbox: JSON event stream (init, content, result)
    Sandbox-->>User: Stream stdout + exitCode

    Note over Sandbox: Sandbox enters standby

    User->>SDK: SandboxInstance.get("amp-sandbox")
    SDK->>Sandbox: Wake from standby
    Sandbox-->>User: Resumed instance

    User->>Sandbox: process.exec(amp threads continue <threadId>)
    Sandbox->>Amp: Continue existing thread
    Amp-->>Sandbox: JSON event stream (result)
    Sandbox-->>User: Stream stdout + exitCode

    User->>SDK: bl delete sandbox amp-sandbox
    SDK->>Sandbox: Terminate

Loading

Summary

The tutorial walks through a 4-phase lifecycle:

1. Provision — Create a sandbox with Amp pre-installed and inject AMP_API_KEY
2. Execute — Clone a repo, run an Amp coding task, and parse structured JSON output for the thread ID
3. Reconnect — Resume the same sandbox after standby and continue the Amp thread
4. Cleanup — Delete the sandbox

No code/infra review concerns — this is a well-structured documentation addition.

Note

Posted by PR Sequence Diagram · Tag @mendral-app with feedback.

[mendral-app]

🧪 Testing Guide

What this PR addresses

Adds a new tutorial page (Tutorials/Amp.mdx) that walks users through running Amp inside a Blaxel sandbox — covering sandbox creation, streaming an Amp coding task, continuing a thread after reconnection, interactive terminal use, troubleshooting, and cleanup. It also registers the page in the docs navigation (docs.json).

Steps to verify the new content

1. Navigation entry — Confirm that docs.json now includes the "Tutorials/Amp" page inside a new "Amp" group under Tutorials, and that the JSON is still valid (no trailing commas, correct nesting).
2. Local docs preview — Run the docs site locally (e.g. mintlify dev) and navigate to Tutorials → Amp → Run Amp in a sandbox. Verify the page renders without errors and all code blocks, notes, warnings, and card groups display correctly.
3. Code group switching — Toggle between the TypeScript and Python tabs in every <CodeGroup> block. Ensure all snippets are visible and properly syntax-highlighted.
4. Link integrity — Spot-check internal links (/cli-reference/introduction#install, /Sandboxes/Processes) and external links (https://ampcode.com/manual, https://ampcode.com/settings/security) resolve correctly.
5. Code correctness (read-through) — Review the TypeScript and Python examples for:
   • Proper shell-quoting of user-provided values (shellQuote / shlex.quote).
   • Correct parsing of Amp's JSON-line output (init event for session_id, result event for success check).
   • Consistent use of --no-archive-after-execute in the initial task but not in the continuation (intentional per Amp semantics).
6. Frontmatter — Verify the title and description in the MDX frontmatter are appropriate for SEO / docs search.

What to verify (expected behavior)

• The new page appears in the sidebar under Tutorials → Amp.
• The page renders cleanly with no build warnings or broken components.
• Both language variants (TypeScript and Python) are complete, consistent, and follow the same logical flow.
• No existing pages or navigation entries are affected (the diff only adds, no deletions).

Note

Posted by PR Testing Guide · Tag @mendral-app with feedback.

[mendral-app]

✅ Linked to Linear issue ENG-4631 — status already In Progress, assigned to Michael Stolarz.

Note

Posted by Linear Issue Enforcer · Tag @mendral-app with feedback.

[mendral-app]

LGTM

The tutorial code is well-structured with correct shell quoting (preventing injection), proper secret handling via environment variables, and sound JSON event validation logic. The riskiest area—shell command construction with user-supplied REPOSITORY_URL and AMP_THREAD_ID—is properly handled by shellQuote/shlex.quote in both languages. No security, correctness, or data-integrity issues found.

_{Tag @mendral-app with feedback or questions. View session}