Add practical cloud sandbox workflow guides

content/manuals/agentic-platform/_index.md

@@ -26,6 +26,10 @@ grid:
     description: Access, pause, resume, and delete your sandboxes.
     icon: command-line
     link: /agentic-platform/sandboxes/
+  - title: Guides
+    description: Share an app, develop remotely, or continue local work in the cloud.
+    icon: command-line
+    link: /agentic-platform/guides/
   - title: MCP
     description: Connect predefined or custom MCP servers.
     icon: cpu-chip

content/manuals/agentic-platform/get-started.md

@@ -11,15 +11,20 @@ aliases:
 Use a cloud sandbox to review a project with a coding agent or build and run
 an application from a shell, without setting up the project on your computer.
 
-You can complete either workflow in the browser. An optional step shows how
-to open the same project in VS Code or Cursor over SSH.
+Both paths introduce the same cloud sandbox lifecycle: launch an environment,
+run a task, save work, and pause or delete it. Complete either path in your
+browser, then use the [guides](guides/_index.md) for sharing, remote development,
+or moving local work to the cloud.
 
 ## Before you begin
 
 You need a personal Docker account with an active
 [Docker Agentic Platform subscription](signup.md#activate-cloud-access).
 
 Both workflows use a public sample project, so you don't need a GitHub token.
+Review the compute price and timer before launching. Choose **Stop** as the
+timeout action to keep files. Compute is billed while the sandbox runs;
+closing the browser doesn't stop it.
 
 ## Choose a workflow
 
@@ -73,8 +78,7 @@ Claude Code summarizes the project in the conversation and saves the review
 at `/home/agent/workspace/review.md`. You can ask follow-up questions or give
 it another task in the same session.
 
-Continue to [keep your work](#keep-your-work), or
-[open the project in your editor](#open-the-project-in-your-editor-optional).
+Continue to [keep your work](#keep-your-work).
 
 ## Use a shell
 
@@ -88,8 +92,9 @@ The Shell kit starts a Bash shell without an agent.
 3. If saved secrets or a GitHub token are selected, deselect them for this
    walkthrough. You don't need MCP tools either.
 4. In the network policy picker, select **Balanced** to permit access to
-   GitHub, Docker Hub, and npm. Keep the compute and timer defaults and select
-   **Run**.
+   GitHub, Docker Hub, and npm. Deselect **Open** if selected: combining it
+   with Balanced doesn't restrict Open's access. Review the compute price and
+   timer, choose **Stop** as the timeout action, and select **Run**.
 
 If you use a custom network policy, make sure it permits GitHub, Docker Hub,
 and npm. See [Network policies](policies.md).
@@ -129,11 +134,13 @@ You should see the Welcome to Docker application. The application runs in the
 cloud sandbox, so you can try it without installing Docker or Node.js on your
 computer.
 
-The generated URL is public. Close the port in **Connect** when you've finished
-previewing the application.
+The generated URL is public, and Docker account authentication doesn't protect
+it. Use only non-sensitive data. Close the port in **Connect** when you've
+finished previewing, then reload the URL to confirm access is withdrawn.
+For a complete sharing workflow, including checking access from a separate
+browser session, follow [Share an application](guides/share-app.md).
 
-Continue to [keep your work](#keep-your-work), or
-[open the project in your editor](#open-the-project-in-your-editor-optional).
+Continue to [keep your work](#keep-your-work).
 
 ## Keep your work
 
@@ -147,52 +154,9 @@ and push changes to a repository. Include a
 [GitHub credential](secrets.md#github-credential) when launching a sandbox that
 needs to push changes.
 
-## Open the project in your editor (optional)
-
-Open the project in VS Code or Cursor over SSH to edit the application. Your
-editor runs on your computer, while the files and terminal commands stay in
-the cloud sandbox.
-
-1. Install the [Docker Sandboxes CLI](/manuals/ai/sandboxes/install.md),
-   version 0.45.0 or later.
-2. In a terminal on your computer, sign in with the same Docker account you
-   used in the Console and configure cloud SSH access:
-
-   ```console
-   $ sbx login
-   $ sbx --cloud setup ssh
-   $ sbx --cloud ls
-   ```
-
-3. Find your sandbox in the list and copy its `sbx_`-prefixed ID. Test the
-   connection, replacing `<SANDBOX_ID>` with that ID:
-
-   ```console
-   $ ssh <SANDBOX_ID>@sbx_cloud
-   ```
-
-   A successful connection opens a shell inside the cloud sandbox. Run `exit`
-   to return to your computer's terminal.
-4. In VS Code, install the
-   [Remote - SSH extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh).
-   In Cursor, install its Remote - SSH support.
-5. Open your editor's Command Palette and run **Remote-SSH: Connect to Host**.
-   Enter `<SANDBOX_ID>@sbx_cloud`, using the same ID as in the SSH command.
-6. Open `/home/agent/workspace` in the remote window. Both workflows clone
-   the application into `project`. The coding agent also saves `review.md`
-   in the workspace.
-
-The first connection installs the editor's server inside the sandbox.
-
-If you followed the coding agent workflow, download the review run this command in a terminal on your computer:
-
-```console
-$ sbx --cloud cp <SANDBOX_ID>:/home/agent/workspace/review.md ./review.md
-```
-
 ## Pause, keep running, or delete the sandbox
 
-Closing the browser or disconnecting your editor leaves the sandbox running.
+Closing the browser leaves the sandbox running.
 Commands and background processes can continue until you pause or delete the
 sandbox, or its timer expires. Compute is billed while the sandbox runs, even
 when no commands are running.
@@ -209,27 +173,24 @@ Return to **Sandboxes** in the Console and choose what to do next:
   you want to keep first. Deletion removes files stored only in the sandbox.
 
 For more detail, see [Lifecycle actions](sandboxes.md#manage-the-lifecycle).
+
+## Sandbox options
+
+For launch settings, see [Kits](kits.md), [Secrets](secrets.md),
+[Network policies](policies.md), and [MCP tools](mcp.md). For compute platforms
+and timer actions, see [Sandboxes](sandboxes.md). Choose these settings before
+launching: credentials, tools, network policies, and compute size can't be
+changed afterward.
+
+## Next steps
+
 To run a task from your own terminal, follow the
 [cloud CLI walkthrough](/manuals/ai/sandboxes/cloud/_index.md#get-started).
 For programmatic workflows, see the
 [Sandboxes API quickstart](/manuals/ai/sandboxes-api/get-started.md).
 
-## Sandbox options
+Continue with a targeted workflow:
 
-After launch, you can't change the selected credentials, tools, network policies,
-or compute size. Configure these options before selecting **Run**:
-
-| Option | What to choose |
-| --- | --- |
-| Sandbox name | Select **randomly** to enter a name, or keep the generated name. |
-| Agent credentials | Add the API keys or tokens your kit needs. Saved credentials are reused by default; deselect optional credentials you don't want to include. See [Secrets](secrets.md). |
-| GitHub token | Provide a token for Copilot or for cloning private repositories and pushing changes. Copilot uses the same token for both. Repository access is optional for other agents. See [GitHub credential](secrets.md#github-credential). |
-| Network policies | Review the hosts and services the sandbox can reach. See [Network policies](policies.md). |
-| MCP tools | Choose the servers your agent can use and authorize them if prompted. See [MCP](mcp.md). |
-| Compute and platform | Choose a size based on the CPU and memory your task needs, from Micro for light tasks to XL for larger workloads. The picker shows each size's resources and hourly price. Under **Platform**, use **auto** or a platform supported by the kit's image. See [Sandbox platforms](sandboxes.md#choose-a-platform). |
-| Timer | Under **Run for**, choose 1 to 24 hours. Under **When the time is up**, choose **Stop**, **Delete**, or **Restart** if offered. See [Lifecycle actions](sandboxes.md#manage-the-lifecycle). |
-
-The launcher remembers your policy selections from the previous launch in the
-same browser. Policies marked **Always applied** are selected automatically.
-Review the selected policies before launching. Selecting **Balanced** alongside
-**Open** doesn't restrict Open's access; see [How policies combine](policies.md#how-policies-combine).
+- [Share an application](guides/share-app.md) through a public URL.
+- [Develop remotely](guides/remote-development.md) with VS Code or Cursor.
+- [Continue local work in the cloud](guides/local-handoff.md) and retrieve the results.

content/manuals/agentic-platform/guides/_index.md

@@ -0,0 +1,16 @@
+---
+title: Docker Agentic Platform guides
+linkTitle: Guides
+description: Follow step-by-step workflows to share an application, develop remotely, or hand off a local task to a cloud sandbox.
+keywords: docker agentic platform, cloud sandboxes, workflows, guides
+weight: 25
+---
+
+Choose a workflow to put a cloud sandbox to work:
+
+- [Share an application](share-app.md) through a public HTTPS URL, then withdraw access.
+- [Develop remotely](remote-development.md) with VS Code or Cursor over SSH.
+- [Continue local work in the cloud](local-handoff.md) and retrieve the results.
+
+For account setup, start with [Get started](/manuals/agentic-platform/get-started.md).
+For command options, see [Use cloud sandboxes](/manuals/ai/sandboxes/cloud/usage.md).

content/manuals/agentic-platform/guides/local-handoff.md

@@ -0,0 +1,185 @@
+---
+title: Continue local work in the cloud
+linkTitle: Local-to-cloud handoff
+description: Prepare a bounded agent task in a local sandbox, move its filesystem to the cloud, and retrieve the results.
+keywords: docker agentic platform, cloud sandboxes, workflows, local-to-cloud handoff
+weight: 30
+---
+
+Prepare a sample review locally, then let an agent finish it in the cloud while
+your computer is disconnected. Retrieve the report before removing either
+sandbox. Provisional duration: 25 minutes; this estimate needs measurement
+during review.
+
+## Before you begin
+
+You need the [CLI and a supported local runtime](/manuals/ai/sandboxes/install.md),
+version 0.45.0 or later, an active
+[Docker Agentic Platform subscription](/manuals/agentic-platform/signup.md#activate-cloud-access),
+and an Anthropic API key for Claude Code in the cloud. You can use a Claude
+subscription locally, but cloud sandboxes require an API key. This guide uses
+an API key in both environments.
+
+Docker bills cloud compute while the destination runs, even when disconnected.
+Anthropic bills inference separately. The public sample needs no GitHub token.
+Use the managed credential stores so keys stay out of the filesystem snapshot:
+
+```console
+$ sbx login
+$ sbx --cloud diagnose
+$ sbx secret set anthropic
+$ sbx --cloud secret set anthropic
+```
+
+Local and cloud secret stores are separate. See
+[Cloud credentials](/manuals/ai/sandboxes/cloud/credentials.md).
+
+## Prepare files inside the local sandbox
+
+On your computer, create a mountless sandbox by omitting the workspace argument.
+Clone the project inside it so the files transfer to the cloud. Directories
+mounted from your computer and clone-mode volumes are outside the sandbox
+filesystem and aren't included in a move:
+
+```console
+$ sbx create --name handoff-local --cpus 2 --memory 4g claude
+$ sbx policy allow network github.com:443 --sandbox handoff-local
+$ sbx exec handoff-local git clone https://github.com/docker/welcome-to-docker.git /home/agent/workspace/project
+$ sbx run --name handoff-local
+```
+
+Ask the local agent to prepare the task without carrying it out:
+
+```text
+Read /home/agent/workspace/project. Don't modify it or install dependencies.
+Record the full git HEAD revision and confirm the working tree is clean.
+Write /home/agent/workspace/HANDOFF.md with that baseline, the project path,
+and this remaining task:
+Review package.json and the Dockerfile. Explain the build and startup commands,
+identify the application's listening port, and recommend one small improvement
+with a source path and reason. Don't modify the application or install anything.
+Save the review to /home/agent/workspace/review.md. Include the baseline revision,
+files read, and limitations. Don't claim to have run the application.
+Don't start this review yet.
+```
+
+Exit the local agent when preparation is complete. Before snapshotting, remove
+any credentials saved in filesystem files, including interactive sign-in files.
+Managed secrets aren't copied, but ordinary credential files are.
+
+## Move the filesystem
+
+From your computer, run:
+
+```console
+$ sbx move handoff-local --to cloud --ttl 2h --on-timeout stop
+```
+
+The move stops the local source for capture and creates a separate destination.
+Use its printed `sbx_`-prefixed ID in place of `<CLOUD_ID>`. The move also creates
+a template: the filesystem image used to create the destination, including
+`HANDOFF.md`. It remains after you remove the sandbox.
+
+Cloud sandboxes support both `linux/amd64` and `linux/arm64`. The destination
+matches your local sandbox's architecture; a move doesn't convert between them.
+
+The explicit timeout requests that the destination stop after two hours and
+retain its files; the command
+fails if stopping isn't supported. Don't substitute deletion without first
+arranging to save your work.
+
+A move transfers a filesystem snapshot. Running processes, memory, open sockets,
+workspace mounts, clone-mode volumes, and managed secrets don't transfer.
+Local network rules don't transfer either. Published TCP sandbox ports can be
+republished with cloud URLs; rejected ports produce warnings. See
+[Move a sandbox](/manuals/ai/sandboxes/cloud/move.md) for transfer details.
+
+## Continue in the Console
+
+Open the [Console](https://agentic-platform.docker.com) and sign in with the
+same Docker account you used for the CLI. Open **Sandboxes** and select the
+destination using the ID printed by the move. Use its browser terminal to
+continue the task; the local agent process wasn't transferred.
+
+Before starting work, confirm the destination's architecture, compute size,
+and expiration match your expectations. Check that your cloud Anthropic
+credential is set. This task needs no published ports; remove any unintended
+exposure. Verify the
+[cloud network policy](/manuals/ai/sandboxes/cloud/network-policy.md) permits
+the model provider; local network rules don't transfer.
+
+In an additional shell, check the transferred handoff:
+
+```console
+$ cat /home/agent/workspace/HANDOFF.md
+```
+
+Expect the recorded baseline, project path, and remaining task. Return to the
+agent's terminal to restart the work.
+
+Give it this prompt:
+
+```text
+Read /home/agent/workspace/HANDOFF.md. Confirm the baseline revision and clean
+working tree before doing the remaining review. Stop and report a mismatch.
+Complete only the recorded task and save /home/agent/workspace/review.md.
+```
+
+## Disconnect and retrieve the result
+
+Once the agent starts, close the browser tab to disconnect. The cloud agent
+can continue while your computer is disconnected. The timer still applies;
+no further work runs after the sandbox stops until you resume it.
+
+Return to **Sandboxes** in the Console and reopen the destination. If it is
+paused, select **Restore to connect**. Resuming starts a fresh timer. Review
+the agent's response in the browser terminal.
+
+> [!TIP]
+> If the terminal appears stuck after reconnecting, try resizing it by resizing
+> your browser window. This can make the agent interface redraw.
+
+When the report is ready, return to your computer's terminal and copy both files:
+
+```console
+$ sbx --cloud ttl <CLOUD_ID>
+$ sbx --cloud cp <CLOUD_ID>:/home/agent/workspace/review.md ./review.md
+$ sbx --cloud cp <CLOUD_ID>:/home/agent/workspace/HANDOFF.md ./HANDOFF.md
+```
+
+Read the local copies. Expect the report to identify the recorded baseline,
+explain the build and startup commands with file references, and state that the
+application wasn't run. Compare it with the source rather than treating the
+agent's claims as verified. Files don't synchronize after a move: copying these
+results is what brings them back to your computer.
+
+## Clean up both sandboxes
+
+After verifying your saved files, remove the destination, its template, and the
+local source. First inspect the destination to identify its backing template,
+then list the templates. Find the matching entry, typically named
+`moved-handoff-local-<SUFFIX>`, and use its ID as `<TEMPLATE_ID>`. Check the ID
+against the inspected sandbox so you remove only this move's snapshot:
+
+```console
+$ sbx --cloud inspect <CLOUD_ID>
+$ sbx --cloud template ls
+```
+
+Delete the cloud sandbox before removing its backing template:
+
+```console
+$ sbx --cloud rm <CLOUD_ID>
+$ sbx --cloud template rm <TEMPLATE_ID>
+$ sbx rm handoff-local
+$ sbx --cloud ls
+$ sbx --cloud template ls
+$ sbx ls
+```
+
+Confirm both sandboxes and the template are absent. The template contains the
+captured filesystem, so removing only the sandbox leaves that snapshot stored.
+Removal deletes files stored only in those resources.
+If retaining the cloud destination instead, stop it and confirm its state with
+`sbx --cloud ls` to stop compute charges. Check the expiration again after any
+resume. See [Stop or remove a sandbox](/manuals/ai/sandboxes/cloud/usage.md#stop-or-remove-a-sandbox).