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

---

Note

Low Risk
Documentation-only: a new tutorial page and nav entry. No product, auth, or runtime code changes.

Overview
Adds a complete Amp-on-Blaxel tutorial (Tutorials/Amp.mdx) and lists it under a new Amp group in Tutorials navigation.

The guide walks through SDK setup, creating a blaxel/amp:latest sandbox with AMP_API_KEY, cloning a repo, streaming a headless Amp task, parsing JSON events for thread ID and success, then continuing the same private thread after standby. It also covers interactive bl connect, safety notes for unattended Amp, troubleshooting, and cleanup.

^{Reviewed by Cursor Bugbot for commit 3a4e815. Bugbot is set up for automated code reviews on this repo. Configure here.}

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