From a9b7f739f44a2e2399e16367407cfdb9f0a39c81 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Thu, 29 Oct 2026 14:57:52 +0000 Subject: [PATCH 1/8] docs: add cloud sandbox workflow guides Add targeted workflows for sharing an app, developing over SSH, and handing a local task to the cloud. Link them from onboarding and cloud documentation so readers can apply the platform to a concrete task. --- content/manuals/agentic-platform/_index.md | 4 + .../manuals/agentic-platform/get-started.md | 6 + .../manuals/agentic-platform/guides/_index.md | 16 ++ .../agentic-platform/guides/local-handoff.md | 176 ++++++++++++++++++ .../guides/remote-development.md | 125 +++++++++++++ .../agentic-platform/guides/share-app.md | 101 ++++++++++ content/manuals/ai/sandboxes/cloud/_index.md | 3 + 7 files changed, 431 insertions(+) create mode 100644 content/manuals/agentic-platform/guides/_index.md create mode 100644 content/manuals/agentic-platform/guides/local-handoff.md create mode 100644 content/manuals/agentic-platform/guides/remote-development.md create mode 100644 content/manuals/agentic-platform/guides/share-app.md diff --git a/content/manuals/agentic-platform/_index.md b/content/manuals/agentic-platform/_index.md index e26099a48164..9d91f38fae5c 100644 --- a/content/manuals/agentic-platform/_index.md +++ b/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 diff --git a/content/manuals/agentic-platform/get-started.md b/content/manuals/agentic-platform/get-started.md index 7aef6e2af525..8a550f304989 100644 --- a/content/manuals/agentic-platform/get-started.md +++ b/content/manuals/agentic-platform/get-started.md @@ -214,6 +214,12 @@ To run a task from your own terminal, follow the For programmatic workflows, see the [Sandboxes API quickstart](/manuals/ai/sandboxes-api/get-started.md). +Continue with a targeted workflow: + +- [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. + ## Sandbox options After launch, you can't change the selected credentials, tools, network policies, diff --git a/content/manuals/agentic-platform/guides/_index.md b/content/manuals/agentic-platform/guides/_index.md new file mode 100644 index 000000000000..7311776062cd --- /dev/null +++ b/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). diff --git a/content/manuals/agentic-platform/guides/local-handoff.md b/content/manuals/agentic-platform/guides/local-handoff.md new file mode 100644 index 000000000000..dec522e437c4 --- /dev/null +++ b/content/manuals/agentic-platform/guides/local-handoff.md @@ -0,0 +1,176 @@ +--- +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. Your cloud account must support the +local sandbox's architecture: a move doesn't convert Arm to Intel/AMD or the reverse. + +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). + +## 1. Prepare files inside the local sandbox + +On your computer, create a sandbox without a workspace argument: + +```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 +``` + +The project belongs to the sandbox filesystem. Host workspace mounts and +clone-mode volumes aren't included in a move. + +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. +``` + +Read the handoff file from another terminal on your computer: + +```console +$ sbx exec handoff-local cat /home/agent/workspace/HANDOFF.md +$ sbx exec handoff-local git -C /home/agent/workspace/project rev-parse HEAD +$ sbx exec handoff-local git -C /home/agent/workspace/project status --short +``` + +Expect the recorded revision to match and the project working tree to be clean. +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. + +## 2. 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 name or ID in place of ``. 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. + +## 3. Verify the destination and restart the agent + +Inspect both states and the destination before doing more work: + +```console +$ sbx ls +$ sbx --cloud ls +$ sbx --cloud inspect +$ sbx --cloud ttl +$ sbx --cloud secret ls +$ sbx --cloud ports +$ sbx --cloud exec cat /home/agent/workspace/HANDOFF.md +$ sbx --cloud exec git -C /home/agent/workspace/project rev-parse HEAD +$ sbx --cloud exec git -C /home/agent/workspace/project status --short +``` + +Expect the source to be stopped, a distinct destination ID, the same baseline, +a clean project tree, and the handoff file. Confirm the platform, compute size, +expiration action, and cloud Anthropic credential. This task needs no published +ports; remove any unintended exposure before continuing. Verify destination +[network policy](/manuals/ai/sandboxes/cloud/network-policy.md) permits the model +provider. The cloud uses its own policy and agent rules, rather than local rules. + +Restart the agent explicitly; its local process wasn't transferred: + +```console +$ sbx --cloud attach +``` + +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. +``` + +## 4. Disconnect and retrieve the result + +Once the agent starts, press `Ctrl+\` to detach. 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 from your computer's terminal: + +```console +$ sbx --cloud attach +``` + +Review the agent's response. Attaching resumes a stopped sandbox and starts a +fresh timer. When the report is ready, detach with `Ctrl+\` and copy both files: + +```console +$ sbx --cloud ttl +$ sbx --cloud cp :/home/agent/workspace/review.md ./review.md +$ sbx --cloud cp :/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. + +## 5. Clean up both sandboxes + +After verifying your saved files, remove the destination and source separately: + +```console +$ sbx --cloud rm +$ sbx rm handoff-local +$ sbx --cloud ls +$ sbx ls +``` + +Confirm both are absent. Removal deletes files stored only in those sandboxes. +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). diff --git a/content/manuals/agentic-platform/guides/remote-development.md b/content/manuals/agentic-platform/guides/remote-development.md new file mode 100644 index 000000000000..c69e5dd1f0e5 --- /dev/null +++ b/content/manuals/agentic-platform/guides/remote-development.md @@ -0,0 +1,125 @@ +--- +title: Develop remotely in a cloud sandbox +linkTitle: Remote development +description: Connect VS Code or Cursor to a cloud sandbox over SSH, edit and preview a sample, and save your work. +keywords: docker agentic platform, cloud sandboxes, workflows, remote development +weight: 20 +--- + +Keep project files and development tools in a cloud sandbox while using VS Code +or Cursor on your computer. Provisional duration: 25 minutes; this estimate needs +measurement during review. + +## Before you begin + +You need an active [Docker Agentic Platform subscription](/manuals/agentic-platform/signup.md#activate-cloud-access), +the [Docker Sandboxes CLI](/manuals/ai/sandboxes/install.md) version 0.45.0 or +later, an SSH client, and VS Code or Cursor. The public sample needs no GitHub +token or model API key. Use the same Docker account in the CLI and Console. + +Your editor window runs locally. Project files, terminal commands, and the +editor's remote server run inside the sandbox. Files don't sync to your computer. +Docker bills compute while the sandbox runs, even with the editor disconnected. + +## 1. Create the remote project + +1. Open the [Console](https://agentic-platform.docker.com/) and select **+ New sandbox**. +2. Choose **shell**, deselect saved credentials and MCP tools, and select + **Balanced** for GitHub, Docker Hub, and npm access. Deselect **Open** if selected. +3. Review the compute price and timer. Select **Stop** under **When the time is up** + to retain files, then select **Run**. +4. In the sandbox's browser terminal, clone the sample: + + ```console + $ cd /home/agent/workspace + $ git clone https://github.com/docker/welcome-to-docker.git project + ``` + +Expect `/home/agent/workspace/project` to contain the sample source and Dockerfile. +Local workspaces aren't mounted in the cloud sandbox. + +## 2. Configure and test SSH + +In a terminal on your computer, run: + +```console +$ sbx login +$ sbx --cloud setup ssh +$ sbx --cloud ls +``` + +Copy the sandbox's `sbx_`-prefixed ID from the list, then test the connection: + +```console +$ ssh @sbx_cloud +$ ls /home/agent/workspace/project +$ exit +``` + +Expect a shell inside the sandbox and the project files. `exit` returns you to +your computer. Use the ID, rather than the sandbox's display name, for SSH. +See [Connect with SSH](/manuals/ai/sandboxes/cloud/usage.md#connect-with-ssh) +for proxy troubleshooting. + +## 3. Connect your editor + +Choose the instructions for your editor: + +- In VS Code, install the + [Remote - SSH extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh). + Open the Command Palette and run **Remote-SSH: Connect to Host**. +- In Cursor, install its Remote - SSH support. Open the Command Palette and run + **Remote-SSH: Connect to Host**. + +Enter `@sbx_cloud` using the ID you tested. In the remote window, +open `/home/agent/workspace/project`. The first connection installs the editor's +server inside the sandbox. Expect the editor to show a remote connection and +the same project files you listed over SSH. + +For local sandbox integration, see the separate +[VS Code](/manuals/ai/sandboxes/integrations/vscode.md) and +[Cursor](/manuals/ai/sandboxes/integrations/cursor.md) pages. + +## 4. Edit and preview remotely + +In the remote editor, find a visible heading in the application's source, +change its text, and save the file. In the editor's remote terminal, build and run: + +```console +$ cd /home/agent/workspace/project +$ docker build -t welcome-to-docker . +$ docker run -d --name welcome-to-docker -p 3000:3000 welcome-to-docker +``` + +In the Console, select **Connect**, enter `3000` under **Connect via a Port**, +and select **Open Port**. Open the generated HTTPS URL and expect to see your +changed heading. This URL is public: Docker account authentication doesn't +protect it. Use non-sensitive data and application authentication for private +content. Close the port in **Connect** after checking the preview and reload +the URL to verify the application is no longer reachable. + +## 5. Reconnect and keep your work + +Close the remote editor window, then connect again using the same host entry +and open the same directory. Expect your saved change to remain. Disconnecting +doesn't pause the sandbox. If the timer stopped it, resume it in the Console +before reconnecting; check the fresh timer and restart the workload if needed. + +From a terminal on your computer, copy the project out: + +```console +$ sbx --cloud cp :/home/agent/workspace/project ./cloud-project +``` + +Inspect the copied source and confirm that your edit is present. Alternatively, +commit and push to a repository you control. Configure a +[GitHub credential](/manuals/agentic-platform/secrets.md#github-credential) +with the required repository permissions before launching a sandbox for that workflow. + +## 6. Clean up + +In **Sandboxes**, pause the sandbox and confirm its paused status to stop compute +charges and retain files. A resumed sandbox gets a fresh timer with the original +duration. Once you've verified your saved copy, delete the sandbox if you no +longer need it. Deletion removes the remote files and editor server. +See [Lifecycle actions](/manuals/agentic-platform/sandboxes.md#manage-the-lifecycle). diff --git a/content/manuals/agentic-platform/guides/share-app.md b/content/manuals/agentic-platform/guides/share-app.md new file mode 100644 index 000000000000..71c905ebeed4 --- /dev/null +++ b/content/manuals/agentic-platform/guides/share-app.md @@ -0,0 +1,101 @@ +--- +title: Share an application from a cloud sandbox +linkTitle: Share an app +description: Build a public sample in a cloud sandbox, share its HTTPS URL, and close the port when you finish. +keywords: docker agentic platform, cloud sandboxes, workflows, share an app +weight: 10 +--- + +Run the Welcome to Docker application in a cloud sandbox and share a preview +without setting up the project on your computer. Provisional duration: 20 minutes; +this estimate needs measurement during review. + +## Before you begin + +You need a browser and an active +[Docker Agentic Platform subscription](/manuals/agentic-platform/signup.md#activate-cloud-access). +This public sample needs no GitHub token, model API key, or MCP tools. +Use non-sensitive data: the preview URL is public, and Docker account +authentication doesn't protect it. Add authentication to your application +before sharing private content or operations that change data. + +Docker bills compute while the sandbox runs, including when you disconnect. +Review the compute price and timer before launching. Choose **Stop** as the +timeout action to retain files; **Delete** removes them. A stopped application +can't serve visitors. See [Sandbox lifecycle](/manuals/agentic-platform/sandboxes.md#manage-the-lifecycle). + +## 1. Launch a shell + +1. Open the [Console](https://agentic-platform.docker.com/) and select **+ New sandbox**. +2. Choose the **shell** kit. Deselect saved credentials and MCP tools. +3. Select **Balanced** for GitHub, Docker Hub, and npm access. Deselect **Open** + if selected; combining it with Balanced doesn't restrict Open's access. +4. Review the compute size, **Run for** duration, and **When the time is up** + action, then select **Run**. + +The browser terminal opens a Bash shell inside the sandbox. Local files aren't +mounted there. See [Network policies](/manuals/agentic-platform/policies.md) +if your account applies additional restrictions. + +## 2. Build and run the sample + +In the sandbox terminal, clone the public project into the sandbox filesystem: + +```console +$ cd /home/agent/workspace +$ git clone https://github.com/docker/welcome-to-docker.git project +$ cd project +$ docker build -t welcome-to-docker . +$ docker run -d --name welcome-to-docker -p 3000:3000 welcome-to-docker +``` + +The build should finish successfully, and the last command should return a +container ID. Check the running container: + +```console +$ docker ps --filter name=welcome-to-docker +``` + +Expect the container to be running with port `3000` published in the sandbox. +This container port mapping alone doesn't create the public cloud URL. + +## 3. Open and share the preview + +1. On the sandbox detail page, select **Connect**. +2. Under **Connect via a Port**, enter `3000` and select **Open Port**. +3. Open the generated HTTPS URL in a separate private browser session where + you aren't signed in to Docker. Expect the Welcome to Docker application. +4. Share the URL only after checking the page and confirming it contains no + private data. Anyone with the URL can access the exposed application. + +The service runs inside the sandbox. Closing your browser leaves it running +until you stop it or the timer action takes effect. + +## 4. Withdraw access and save work + +Use the close action next to port `3000` in **Connect**. In the separate browser +session, reload the URL and confirm that the application is no longer reachable. +Don't share the URL further if withdrawal hasn't succeeded; stop the sandbox +and investigate before continuing. + +Stop the container in the sandbox terminal: + +```console +$ docker stop welcome-to-docker +``` + +The project remains at `/home/agent/workspace/project`. To keep changes outside +the sandbox, [copy the files](/manuals/ai/sandboxes/cloud/usage.md#transfer-files) +or push them to a repository you control using an appropriately scoped +[GitHub credential](/manuals/agentic-platform/secrets.md#github-credential). +Verify your saved copy before deleting the sandbox; files don't sync automatically. + +## 5. Clean up + +In **Sandboxes**, pause the sandbox and confirm its paused status to stop compute +charges while retaining files. Resuming starts a fresh timer with the original +duration. Delete the sandbox after saving anything you need; deletion removes +files stored only there. + +For CLI port controls, timers, and file transfers, see +[Use cloud sandboxes](/manuals/ai/sandboxes/cloud/usage.md). diff --git a/content/manuals/ai/sandboxes/cloud/_index.md b/content/manuals/ai/sandboxes/cloud/_index.md index 3a397424aafd..d45faeb50c31 100644 --- a/content/manuals/ai/sandboxes/cloud/_index.md +++ b/content/manuals/ai/sandboxes/cloud/_index.md @@ -118,6 +118,9 @@ Removal deletes files stored only in the sandbox. For your own projects, see [Transfer files](usage.md#transfer-files) and [Authenticate cloud agents](credentials.md) before cloning private repositories. +For step-by-step sharing, remote development, and local handoff workflows, see +[Docker Agentic Platform guides](/manuals/agentic-platform/guides/_index.md). + ## Learn more - [Signup and billing](/manuals/agentic-platform/signup.md) covers activation From b218ab648550d81933c0f7e25b614eb508fa7647 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Thu, 29 Oct 2026 15:28:05 +0000 Subject: [PATCH 2/8] docs: reconcile DAP onboarding with workflow guides The quickstart repeated editor setup and launch configuration covered elsewhere. Keep both browser workflows, link to the detailed guides and references, and clarify how to continue with an existing sandbox. --- .../manuals/agentic-platform/get-started.md | 98 ++++++------------- 1 file changed, 32 insertions(+), 66 deletions(-) diff --git a/content/manuals/agentic-platform/get-started.md b/content/manuals/agentic-platform/get-started.md index 8a550f304989..cebf8c61049b 100644 --- a/content/manuals/agentic-platform/get-started.md +++ b/content/manuals/agentic-platform/get-started.md @@ -11,8 +11,10 @@ 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 @@ -20,6 +22,9 @@ 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 @@ -149,46 +156,17 @@ 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. +To continue with the same project in VS Code or Cursor, follow +[Develop remotely](guides/remote-development.md#2-configure-and-test-ssh). +Check the guide's [prerequisites](guides/remote-development.md#before-you-begin) +first. Skip its project creation step and connect to the sandbox you created +here. Open `/home/agent/workspace/project`; the coding agent also saves +`review.md` in `/home/agent/workspace`. -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 `` with that ID: - - ```console - $ ssh @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 `@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 :/home/agent/workspace/review.md ./review.md -``` +The guide covers SSH setup, both editors, reconnecting, and copying files back +to your computer. You can also use the +[CLI file transfer commands](/manuals/ai/sandboxes/cloud/usage.md#transfer-files) +to download `review.md` without an editor. ## Pause, keep running, or delete the sandbox @@ -222,20 +200,8 @@ Continue with a targeted workflow: ## Sandbox options -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). +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. From 901a5a356a14892113d04f0fbe5b80ef722d8e8b Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Thu, 29 Oct 2026 15:38:19 +0000 Subject: [PATCH 3/8] docs: keep DAP onboarding focused on browser workflows The quickstart mixed follow-up workflows into lifecycle guidance and included an optional editor section. Remove that section and collect workflow links under a closing Next steps heading. --- .../manuals/agentic-platform/get-started.md | 35 +++++++------------ 1 file changed, 12 insertions(+), 23 deletions(-) diff --git a/content/manuals/agentic-platform/get-started.md b/content/manuals/agentic-platform/get-started.md index cebf8c61049b..e139252d50b8 100644 --- a/content/manuals/agentic-platform/get-started.md +++ b/content/manuals/agentic-platform/get-started.md @@ -154,23 +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) - -To continue with the same project in VS Code or Cursor, follow -[Develop remotely](guides/remote-development.md#2-configure-and-test-ssh). -Check the guide's [prerequisites](guides/remote-development.md#before-you-begin) -first. Skip its project creation step and connect to the sandbox you created -here. Open `/home/agent/workspace/project`; the coding agent also saves -`review.md` in `/home/agent/workspace`. - -The guide covers SSH setup, both editors, reconnecting, and copying files back -to your computer. You can also use the -[CLI file transfer commands](/manuals/ai/sandboxes/cloud/usage.md#transfer-files) -to download `review.md` without an editor. - ## 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. @@ -187,6 +173,17 @@ 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 @@ -197,11 +194,3 @@ Continue with a targeted workflow: - [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. - -## 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. From 41d961d1808ba98e1100ece96b9dea1894b7d4f1 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Fri, 30 Oct 2026 08:15:45 +0000 Subject: [PATCH 4/8] docs: add cloud sandbox guide verification checklist The workflow guides request live review without providing a checklist. Add checks for each guide step, expected results, environment records, and publication requirements so reviewers can record what remains unverified. --- .../review-checklists/cloud-sandbox-guides.md | 102 ++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 .github/review-checklists/cloud-sandbox-guides.md diff --git a/.github/review-checklists/cloud-sandbox-guides.md b/.github/review-checklists/cloud-sandbox-guides.md new file mode 100644 index 000000000000..8197a317c505 --- /dev/null +++ b/.github/review-checklists/cloud-sandbox-guides.md @@ -0,0 +1,102 @@ +# Verify the cloud sandbox guides + +Use this checklist to review the three Docker Agentic Platform guides before +publication. All live checks are pending. Drafting used documentation references; +commands, Console labels, editor behavior, and version requirements still need +live verification. Source presence doesn't establish account availability. + +Run each journey from its prerequisites through cleanup. For each row, replace +Pending with Pass, Fail, or Blocked, and record the date, observed result, and +supporting output or screenshot in the observations cell. Remove credentials, +tokens, and private data from evidence. Correct the guide after any discrepancy +and repeat the affected checks. A blocked or failed required check prevents +publication. + +## Record the test environment + +Complete a separate record for each guide and repeat it if the environment changes. + +| Field | Share an app | Remote development | Local-to-cloud handoff | +| --- | --- | --- | --- | +| Reviewer and test date | Pending | Pending | Pending | +| Docs commit tested | Pending | Pending | Pending | +| Account capabilities: subscription, cloud entitlement, available architectures and compute sizes | Pending | Pending | Pending | +| Account network restrictions and credential scopes, without secret values | Pending | Pending | Pending | +| CLI version and installation method, or not used | Pending | Pending | Pending | +| Kit name and version or image digest | Pending | Pending | Pending | +| Local OS, architecture, and runtime version, or not used | Pending | Pending | Pending | +| Cloud architecture and compute size | Pending | Pending | Pending | +| Browser version; SSH client and editor/extension versions where used | Pending | Pending | Pending | +| Sample repository full commit ID | Pending | Pending | Pending | +| Start/end times and measured active and elapsed duration | Pending | Pending | Pending | +| Corrections made and retest evidence | Pending | Pending | Pending | + +Don't infer minimum supported versions from one successful run. Check the +0.45.0-or-later requirement in the remote development and handoff guides against +the supported CLI release information and record that evidence. Record any +missing access as Blocked rather than treating an untested claim as confirmed. + +## Share an app + +Guide: [Share an application from a cloud sandbox](../../content/manuals/agentic-platform/guides/share-app.md). + +| Guide section and claim to test | Expected result | Status | Date, observations, and evidence | +| --- | --- | --- | --- | +| Introduction: provisional 20-minute duration | Measure the entire journey and replace the provisional estimate with a measured duration in the guide. | Pending | Pending | +| Before you begin: entitlement, credentials, pricing, and timers | Account can launch the Shell kit without GitHub/model credentials or MCP tools. Console pricing and timeout choices support the guidance. Record compute charging rules and distinguish them from observed usage. | Pending | Pending | +| Step 1: Console launch controls and network policy | The documented labels and Balanced/Open choices exist. Shell starts with the chosen size, duration, and timeout action; no saved credentials or MCP tools are selected. Local files aren't mounted. | Pending | Pending | +| Step 2: clone, build, run, and inspect commands | All commands succeed from the stated directory. Record the sample revision. Container runs with port 3000 mapped inside the sandbox; the mapping alone doesn't publish a cloud URL. | Pending | Pending | +| Step 3: Connect, Connect via a Port, and Open Port | The documented UI publishes port 3000 and returns a working HTTPS URL. A separate browser session signed out of Docker displays the sample. Record that the app has no application authentication and contains no sensitive data. | Pending | Pending | +| Step 3: disconnect behavior | Closing the original browser leaves the sample reachable until an explicit stop or timeout action. | Pending | Pending | +| Step 4: withdraw public access | Closing port 3000 makes the application unreachable on reload in the separate session. Record the observed response and any delay. Confirm the documented container stop command succeeds. | Pending | Pending | +| Step 4: save files and credential scope | Project remains at the documented path. Copy it outside the sandbox using the linked transfer instructions and inspect the copy. If testing the Git alternative, use only the required repository permissions and record them without secrets. | Pending | Pending | +| Step 5: pause, resume, timeout, charges, and deletion | Pause retains files and stops compute charging under the documented billing rules. Resume starts a fresh timer with the original duration. Exercise Stop and Delete timeout actions on disposable sandboxes; confirm retention versus removal. Save work before deletion and confirm the sandbox is absent. | Pending | Pending | + +## Remote development + +Guide: [Develop remotely in a cloud sandbox](../../content/manuals/agentic-platform/guides/remote-development.md). + +Run the editor-specific checks with both VS Code and Cursor. Record versions and +observations separately for each editor, including its Remote - SSH extension. + +| Guide section and claim to test | Expected result | Status | Date, observations, and evidence | +| --- | --- | --- | --- | +| Introduction and prerequisites: provisional 25-minute duration and CLI requirement | Measure each editor journey and replace provisional timing. Record evidence for the minimum CLI version, cloud entitlement, and use of the same Docker account in Console and CLI. | Pending | Pending | +| Step 1: Console controls, credential scope, and clone | Shell launches with Balanced, without Open, saved credentials, or MCP tools. Stop is available as the timeout action. Clone succeeds without a GitHub token and creates source and Dockerfile at the stated remote path. | Pending | Pending | +| Step 2: login, SSH setup, list, connect, and exit | Each command succeeds. The sbx_-prefixed ID works as the SSH user with sbx_cloud; project files are visible and exit returns to the local terminal. Record any SSH setup prompts or prerequisites missing from the guide. | Pending | Pending | +| Step 3: VS Code connection | The named extension and Command Palette action connect using the tested ID. Remote server installs inside the sandbox and the remote window opens the documented directory. Record exact UI labels and extension version. | Pending | Pending | +| Step 3: Cursor connection | Cursor's Remote - SSH support and Command Palette action connect using the tested ID. Remote server installs inside the sandbox and the remote window opens the documented directory. Record exact extension identity, UI labels, and version. | Pending | Pending | +| Step 4: edit, build, run, preview, and withdraw in each editor | Saved heading change is in the remote files. Build/run commands succeed; public HTTPS preview shows the edit. Closing the public port withdraws access on reload. No sensitive data is exposed. | Pending | Pending | +| Step 5: disconnect and reconnect in each editor | Closing the window leaves the sandbox running. Reconnection opens the same files and saved change. After a timer stop, resume permits reconnection with a fresh timer; restart the workload if required and record that behavior. | Pending | Pending | +| Step 5: copy and optional Git credential | The documented cp command creates a local project copy containing the edit. Files don't sync automatically. If testing the Git alternative, record required repository permissions without secrets. | Pending | Pending | +| Before you begin and step 6: file/process location, timers, charges, and cleanup | Editor window runs locally; project, terminal processes, and remote server live in the sandbox. Confirm billing guidance for running/disconnected and paused states. Pause retains files, resume refreshes the original timer, and deletion removes the sandbox after verifying the saved copy. | Pending | Pending | + +## Local-to-cloud handoff + +Guide: [Continue local work in the cloud](../../content/manuals/agentic-platform/guides/local-handoff.md). + +| Guide section and claim to test | Expected result | Status | Date, observations, and evidence | +| --- | --- | --- | --- | +| Introduction and prerequisites: provisional 25-minute duration, CLI/runtime, and architecture | Measure the journey and replace provisional timing. Record evidence for minimum CLI version, supported local runtime, and cloud support for the local architecture. A move doesn't convert architectures. | Pending | Pending | +| Before you begin: login, diagnose, and separate secret commands | Commands succeed with the recorded account. Local and cloud Anthropic credentials are configured separately; record required scope without keys. Confirm compute and inference charging guidance against billing information. | Pending | Pending | +| Step 1: create, policy, clone, and run commands | Sandbox is created without a host workspace argument; public sample is cloned inside its filesystem. Agent starts with the managed local credential and no GitHub token. | Pending | Pending | +| Step 1: bounded prompt, baseline, and credential removal | HANDOFF.md records the full matching Git revision, clean tree, project path, and remaining task without starting the review. No application files change or dependencies install. Review filesystem credential files before capture and remove them without recording secrets in evidence. | Pending | Pending | +| Step 2: move command and timeout support | Exact move command succeeds with a two-hour Stop action or fails explicitly if stopping is unsupported. Local source stops for capture and a distinct cloud destination is reported. Record command output and supported options. | Pending | Pending | +| Step 2: transfer boundaries | Destination contains filesystem files, but local processes, memory, sockets, host mounts, clone-mode volumes, managed secrets, and local network rules aren't transferred. Use disposable non-sensitive fixtures for applicable boundaries and record any boundary not exercised as pending. Verify documented TCP port republication/warning behavior separately on disposable resources. | Pending | Pending | +| Step 3: all inspection commands | Local/cloud lists, inspect, ttl, secret ls, ports, and exec commands succeed. Source is stopped; destination has the same baseline, clean tree, and handoff file. Platform, size, expiration, cloud credential, and destination policy are correct; no unintended ports remain. | Pending | Pending | +| Step 3: attach and restart the agent | Attach starts the cloud agent using destination credentials and policy. Agent confirms the baseline and completes only the saved task, without an application run. The local agent process hasn't transferred. | Pending | Pending | +| Step 4: detach, continue, and attach after stop | Ctrl+\ detaches without ending cloud work. Agent continues while the client is disconnected until timeout. No work runs while stopped; attach resumes the stopped destination and starts a fresh timer. | Pending | Pending | +| Step 4: retrieve and verify artifacts | Both cp commands succeed and local copies contain the matching baseline, build/startup explanation, listening port, one recommendation with source references, and limitations. Compare the report with the source; record corrections rather than accepting agent claims as test evidence. | Pending | Pending | +| Step 5: remove both states or retain a stopped destination | Removal commands succeed and both list commands confirm absence after local copies are verified. If retaining the destination, confirm stopped status, expiration after resume, file retention, and billing guidance. Remove all disposable test resources. | Pending | Pending | + +## Publication decision + +- [ ] Every required row passes with dated observations and evidence. +- [ ] Both editor journeys pass with separate version records. +- [ ] Commands, UI labels, availability, and minimum versions match the evidence. +- [ ] Provisional durations are replaced with measured durations. +- [ ] Discrepancies are corrected in the guides and affected checks repeated. +- [ ] Saved copies are verified and test sandboxes, public ports, and temporary credentials are cleaned up. +- [ ] Reviewer records the tested docs commit and approves publication. + +Decision: Pending. Reviewer, date, and remaining blockers: Pending. From e56d61ad17b8db0dfb7e21bcb98a4f0c7e6c7e21 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Fri, 30 Oct 2026 09:29:05 +0000 Subject: [PATCH 5/8] docs: Refine cloud sandbox workflow instructions Remove redundant setup and inspection steps, recommend Open for remote editor downloads, and clarify local-to-cloud authentication and architecture. Document the transferred template and remove it during cleanup, with matching live verification checks. --- .../review-checklists/cloud-sandbox-guides.md | 18 ++--- .../agentic-platform/guides/local-handoff.md | 71 +++++++++---------- .../guides/remote-development.md | 5 +- .../agentic-platform/guides/share-app.md | 1 - 4 files changed, 46 insertions(+), 49 deletions(-) diff --git a/.github/review-checklists/cloud-sandbox-guides.md b/.github/review-checklists/cloud-sandbox-guides.md index 8197a317c505..d04b9d3c2a07 100644 --- a/.github/review-checklists/cloud-sandbox-guides.md +++ b/.github/review-checklists/cloud-sandbox-guides.md @@ -62,7 +62,7 @@ observations separately for each editor, including its Remote - SSH extension. | Guide section and claim to test | Expected result | Status | Date, observations, and evidence | | --- | --- | --- | --- | | Introduction and prerequisites: provisional 25-minute duration and CLI requirement | Measure each editor journey and replace provisional timing. Record evidence for the minimum CLI version, cloud entitlement, and use of the same Docker account in Console and CLI. | Pending | Pending | -| Step 1: Console controls, credential scope, and clone | Shell launches with Balanced, without Open, saved credentials, or MCP tools. Stop is available as the timeout action. Clone succeeds without a GitHub token and creates source and Dockerfile at the stated remote path. | Pending | Pending | +| Step 1: Console controls, credential scope, and clone | Shell launches with Open, without saved credentials or MCP tools. Confirm the editor server and dependencies download with this policy. Stop is available as the timeout action. Clone succeeds without a GitHub token and creates source and Dockerfile at the stated remote path. | Pending | Pending | | Step 2: login, SSH setup, list, connect, and exit | Each command succeeds. The sbx_-prefixed ID works as the SSH user with sbx_cloud; project files are visible and exit returns to the local terminal. Record any SSH setup prompts or prerequisites missing from the guide. | Pending | Pending | | Step 3: VS Code connection | The named extension and Command Palette action connect using the tested ID. Remote server installs inside the sandbox and the remote window opens the documented directory. Record exact UI labels and extension version. | Pending | Pending | | Step 3: Cursor connection | Cursor's Remote - SSH support and Command Palette action connect using the tested ID. Remote server installs inside the sandbox and the remote window opens the documented directory. Record exact extension identity, UI labels, and version. | Pending | Pending | @@ -77,17 +77,17 @@ Guide: [Continue local work in the cloud](../../content/manuals/agentic-platform | Guide section and claim to test | Expected result | Status | Date, observations, and evidence | | --- | --- | --- | --- | -| Introduction and prerequisites: provisional 25-minute duration, CLI/runtime, and architecture | Measure the journey and replace provisional timing. Record evidence for minimum CLI version, supported local runtime, and cloud support for the local architecture. A move doesn't convert architectures. | Pending | Pending | -| Before you begin: login, diagnose, and separate secret commands | Commands succeed with the recorded account. Local and cloud Anthropic credentials are configured separately; record required scope without keys. Confirm compute and inference charging guidance against billing information. | Pending | Pending | +| Introduction and prerequisites: provisional 25-minute duration, CLI/runtime, and architecture | Measure the journey and replace provisional timing. Record evidence for minimum CLI version, supported local runtime, and support for both amd64 and arm64 in the cloud. The destination matches the local architecture. | Pending | Pending | +| Before you begin: login, diagnose, and separate secret commands | Commands succeed with the recorded account. Cloud Claude Code requires an API key, while local Claude Code also supports subscriptions. Verify this distinction against Anthropic's terms and supported authentication guidance. Local and cloud Anthropic credentials are configured separately; record required scope without keys. Confirm compute and inference charging guidance against billing information. | Pending | Pending | | Step 1: create, policy, clone, and run commands | Sandbox is created without a host workspace argument; public sample is cloned inside its filesystem. Agent starts with the managed local credential and no GitHub token. | Pending | Pending | | Step 1: bounded prompt, baseline, and credential removal | HANDOFF.md records the full matching Git revision, clean tree, project path, and remaining task without starting the review. No application files change or dependencies install. Review filesystem credential files before capture and remove them without recording secrets in evidence. | Pending | Pending | -| Step 2: move command and timeout support | Exact move command succeeds with a two-hour Stop action or fails explicitly if stopping is unsupported. Local source stops for capture and a distinct cloud destination is reported. Record command output and supported options. | Pending | Pending | +| Step 2: move command and timeout support | Exact move command succeeds with a two-hour Stop action or fails explicitly if stopping is unsupported. Local source stops for capture; a distinct cloud destination and backing template ID are reported. The template contains the captured HANDOFF.md. Record command output and supported options. | Pending | Pending | | Step 2: transfer boundaries | Destination contains filesystem files, but local processes, memory, sockets, host mounts, clone-mode volumes, managed secrets, and local network rules aren't transferred. Use disposable non-sensitive fixtures for applicable boundaries and record any boundary not exercised as pending. Verify documented TCP port republication/warning behavior separately on disposable resources. | Pending | Pending | -| Step 3: all inspection commands | Local/cloud lists, inspect, ttl, secret ls, ports, and exec commands succeed. Source is stopped; destination has the same baseline, clean tree, and handoff file. Platform, size, expiration, cloud credential, and destination policy are correct; no unintended ports remain. | Pending | Pending | -| Step 3: attach and restart the agent | Attach starts the cloud agent using destination credentials and policy. Agent confirms the baseline and completes only the saved task, without an application run. The local agent process hasn't transferred. | Pending | Pending | -| Step 4: detach, continue, and attach after stop | Ctrl+\ detaches without ending cloud work. Agent continues while the client is disconnected until timeout. No work runs while stopped; attach resumes the stopped destination and starts a fresh timer. | Pending | Pending | +| Step 3: transferred handoff and destination settings | The exec cat command succeeds using the printed sbx_-prefixed ID. The handoff file contains the recorded baseline, project path, and remaining task. Platform, size, expiration, cloud credential, and destination policy are correct; no unintended ports remain. | Pending | Pending | +| Step 3: run and restart the agent | Run starts the cloud agent using destination credentials and policy. Agent confirms the baseline and completes only the saved task, without an application run. The local agent process hasn't transferred. | Pending | Pending | +| Step 4: detach, continue, and run after stop | Ctrl+\ detaches without ending cloud work. Agent continues while the client is disconnected until timeout. No work runs while stopped; run resumes the stopped destination and starts a fresh timer. | Pending | Pending | | Step 4: retrieve and verify artifacts | Both cp commands succeed and local copies contain the matching baseline, build/startup explanation, listening port, one recommendation with source references, and limitations. Compare the report with the source; record corrections rather than accepting agent claims as test evidence. | Pending | Pending | -| Step 5: remove both states or retain a stopped destination | Removal commands succeed and both list commands confirm absence after local copies are verified. If retaining the destination, confirm stopped status, expiration after resume, file retention, and billing guidance. Remove all disposable test resources. | Pending | Pending | +| Step 5: remove both sandboxes and the backing template, or retain a stopped destination | Sandbox removal succeeds before template removal; local/cloud sandbox lists and the cloud template list confirm absence after local copies are verified. Confirm the template persists if only its sandbox is removed. If retaining the destination, confirm stopped status, expiration after resume, file retention, and billing guidance. Remove all disposable test resources. | Pending | Pending | ## Publication decision @@ -96,7 +96,7 @@ Guide: [Continue local work in the cloud](../../content/manuals/agentic-platform - [ ] Commands, UI labels, availability, and minimum versions match the evidence. - [ ] Provisional durations are replaced with measured durations. - [ ] Discrepancies are corrected in the guides and affected checks repeated. -- [ ] Saved copies are verified and test sandboxes, public ports, and temporary credentials are cleaned up. +- [ ] Saved copies are verified and test sandboxes, backing templates, public ports, and temporary credentials are cleaned up. - [ ] Reviewer records the tested docs commit and approves publication. Decision: Pending. Reviewer, date, and remaining blockers: Pending. diff --git a/content/manuals/agentic-platform/guides/local-handoff.md b/content/manuals/agentic-platform/guides/local-handoff.md index dec522e437c4..841d11ba6c8e 100644 --- a/content/manuals/agentic-platform/guides/local-handoff.md +++ b/content/manuals/agentic-platform/guides/local-handoff.md @@ -16,8 +16,9 @@ during review. 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. Your cloud account must support the -local sandbox's architecture: a move doesn't convert Arm to Intel/AMD or the reverse. +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. @@ -35,7 +36,10 @@ Local and cloud secret stores are separate. See ## 1. Prepare files inside the local sandbox -On your computer, create a sandbox without a workspace argument: +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 @@ -44,9 +48,6 @@ $ sbx exec handoff-local git clone https://github.com/docker/welcome-to-docker.g $ sbx run --name handoff-local ``` -The project belongs to the sandbox filesystem. Host workspace mounts and -clone-mode volumes aren't included in a move. - Ask the local agent to prepare the task without carrying it out: ```text @@ -62,15 +63,6 @@ files read, and limitations. Don't claim to have run the application. Don't start this review yet. ``` -Read the handoff file from another terminal on your computer: - -```console -$ sbx exec handoff-local cat /home/agent/workspace/HANDOFF.md -$ sbx exec handoff-local git -C /home/agent/workspace/project rev-parse HEAD -$ sbx exec handoff-local git -C /home/agent/workspace/project status --short -``` - -Expect the recorded revision to match and the project working tree to be clean. 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. @@ -84,8 +76,16 @@ $ 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 name or ID in place of ``. The explicit timeout requests -that the destination stop after two hours and retain its files; the command +Use its printed `sbx_`-prefixed ID in place of ``. Also save the +printed template ID as `` for cleanup. The template is 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. @@ -97,31 +97,23 @@ republished with cloud URLs; rejected ports produce warnings. See ## 3. Verify the destination and restart the agent -Inspect both states and the destination before doing more work: +Use the destination ID printed by the move to read the transferred handoff: ```console -$ sbx ls -$ sbx --cloud ls -$ sbx --cloud inspect -$ sbx --cloud ttl -$ sbx --cloud secret ls -$ sbx --cloud ports $ sbx --cloud exec cat /home/agent/workspace/HANDOFF.md -$ sbx --cloud exec git -C /home/agent/workspace/project rev-parse HEAD -$ sbx --cloud exec git -C /home/agent/workspace/project status --short ``` -Expect the source to be stopped, a distinct destination ID, the same baseline, -a clean project tree, and the handoff file. Confirm the platform, compute size, -expiration action, and cloud Anthropic credential. This task needs no published -ports; remove any unintended exposure before continuing. Verify destination -[network policy](/manuals/ai/sandboxes/cloud/network-policy.md) permits the model -provider. The cloud uses its own policy and agent rules, rather than local rules. +Expect the recorded baseline, project path, and remaining task. Before starting +work, confirm the move's reported 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. Restart the agent explicitly; its local process wasn't transferred: ```console -$ sbx --cloud attach +$ sbx --cloud run ``` Give it this prompt: @@ -141,10 +133,10 @@ runs after the sandbox stops until you resume it. Return from your computer's terminal: ```console -$ sbx --cloud attach +$ sbx --cloud run ``` -Review the agent's response. Attaching resumes a stopped sandbox and starts a +Review the agent's response. Running resumes a stopped sandbox and starts a fresh timer. When the report is ready, detach with `Ctrl+\` and copy both files: ```console @@ -161,16 +153,21 @@ results is what brings them back to your computer. ## 5. Clean up both sandboxes -After verifying your saved files, remove the destination and source separately: +After verifying your saved files, remove the destination, its template, and the +local source. Delete the cloud sandbox before removing its backing template: ```console $ sbx --cloud rm +$ sbx --cloud template rm $ sbx rm handoff-local $ sbx --cloud ls +$ sbx --cloud template ls $ sbx ls ``` -Confirm both are absent. Removal deletes files stored only in those sandboxes. +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). diff --git a/content/manuals/agentic-platform/guides/remote-development.md b/content/manuals/agentic-platform/guides/remote-development.md index c69e5dd1f0e5..2bf95c1914b1 100644 --- a/content/manuals/agentic-platform/guides/remote-development.md +++ b/content/manuals/agentic-platform/guides/remote-development.md @@ -25,13 +25,14 @@ Docker bills compute while the sandbox runs, even with the editor disconnected. 1. Open the [Console](https://agentic-platform.docker.com/) and select **+ New sandbox**. 2. Choose **shell**, deselect saved credentials and MCP tools, and select - **Balanced** for GitHub, Docker Hub, and npm access. Deselect **Open** if selected. + **Open** so the editor can download its remote server and dependencies. + Open permits unrestricted outbound network access; use it here with the + public sample and no saved credentials. 3. Review the compute price and timer. Select **Stop** under **When the time is up** to retain files, then select **Run**. 4. In the sandbox's browser terminal, clone the sample: ```console - $ cd /home/agent/workspace $ git clone https://github.com/docker/welcome-to-docker.git project ``` diff --git a/content/manuals/agentic-platform/guides/share-app.md b/content/manuals/agentic-platform/guides/share-app.md index 71c905ebeed4..06fb3e1eac4f 100644 --- a/content/manuals/agentic-platform/guides/share-app.md +++ b/content/manuals/agentic-platform/guides/share-app.md @@ -42,7 +42,6 @@ if your account applies additional restrictions. In the sandbox terminal, clone the public project into the sandbox filesystem: ```console -$ cd /home/agent/workspace $ git clone https://github.com/docker/welcome-to-docker.git project $ cd project $ docker build -t welcome-to-docker . From f4f44b42822acecece2072a1dc6e96a6e0f7cfce Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Fri, 30 Oct 2026 13:34:58 +0000 Subject: [PATCH 6/8] docs: Continue cloud handoff work in the Console The handoff guide kept cloud work in the CLI and required saving a template ID during the move. Continue the agent task in the Console, explain the terminal redraw workaround, and identify the backing template during cleanup. Update the live verification checklist to match. --- .../review-checklists/cloud-sandbox-guides.md | 8 +-- .../agentic-platform/guides/local-handoff.md | 64 +++++++++++-------- 2 files changed, 42 insertions(+), 30 deletions(-) diff --git a/.github/review-checklists/cloud-sandbox-guides.md b/.github/review-checklists/cloud-sandbox-guides.md index d04b9d3c2a07..0484efd88a41 100644 --- a/.github/review-checklists/cloud-sandbox-guides.md +++ b/.github/review-checklists/cloud-sandbox-guides.md @@ -83,11 +83,11 @@ Guide: [Continue local work in the cloud](../../content/manuals/agentic-platform | Step 1: bounded prompt, baseline, and credential removal | HANDOFF.md records the full matching Git revision, clean tree, project path, and remaining task without starting the review. No application files change or dependencies install. Review filesystem credential files before capture and remove them without recording secrets in evidence. | Pending | Pending | | Step 2: move command and timeout support | Exact move command succeeds with a two-hour Stop action or fails explicitly if stopping is unsupported. Local source stops for capture; a distinct cloud destination and backing template ID are reported. The template contains the captured HANDOFF.md. Record command output and supported options. | Pending | Pending | | Step 2: transfer boundaries | Destination contains filesystem files, but local processes, memory, sockets, host mounts, clone-mode volumes, managed secrets, and local network rules aren't transferred. Use disposable non-sensitive fixtures for applicable boundaries and record any boundary not exercised as pending. Verify documented TCP port republication/warning behavior separately on disposable resources. | Pending | Pending | -| Step 3: transferred handoff and destination settings | The exec cat command succeeds using the printed sbx_-prefixed ID. The handoff file contains the recorded baseline, project path, and remaining task. Platform, size, expiration, cloud credential, and destination policy are correct; no unintended ports remain. | Pending | Pending | -| Step 3: run and restart the agent | Run starts the cloud agent using destination credentials and policy. Agent confirms the baseline and completes only the saved task, without an application run. The local agent process hasn't transferred. | Pending | Pending | -| Step 4: detach, continue, and run after stop | Ctrl+\ detaches without ending cloud work. Agent continues while the client is disconnected until timeout. No work runs while stopped; run resumes the stopped destination and starts a fresh timer. | Pending | Pending | +| Step 3: transferred handoff and destination settings | The moved destination appears in Console under the same account and can be selected by its printed sbx_-prefixed ID. An additional browser shell can read HANDOFF.md with cat. The handoff file contains the recorded baseline, project path, and remaining task. Platform, size, expiration, cloud credential, and destination policy are correct; no unintended ports remain. | Pending | Pending | +| Step 3: browser terminal and agent restart | The moved sandbox opens an agent terminal in Console using destination credentials and policy; record any startup steps missing from the guide. Agent confirms the baseline and completes only the saved task, without an application run. The local agent process hasn't transferred. | Pending | Pending | +| Step 4: browser disconnect, reconnect, and resume after stop | Closing the browser leaves cloud work running until timeout. Reopening the destination reconnects to the agent; resizing the browser redraws the interface if it appears stuck. No work runs while stopped; Restore to connect resumes the destination and starts a fresh timer. Record whether the rendering workaround is needed and effective. | Pending | Pending | | Step 4: retrieve and verify artifacts | Both cp commands succeed and local copies contain the matching baseline, build/startup explanation, listening port, one recommendation with source references, and limitations. Compare the report with the source; record corrections rather than accepting agent claims as test evidence. | Pending | Pending | -| Step 5: remove both sandboxes and the backing template, or retain a stopped destination | Sandbox removal succeeds before template removal; local/cloud sandbox lists and the cloud template list confirm absence after local copies are verified. Confirm the template persists if only its sandbox is removed. If retaining the destination, confirm stopped status, expiration after resume, file retention, and billing guidance. Remove all disposable test resources. | Pending | Pending | +| Step 5: remove both sandboxes and the backing template, or retain a stopped destination | Inspect identifies the backing template; template ls lists it and its ID, without requiring an ID saved during the move. Confirm the matching moved-handoff-local entry before removal. Sandbox removal succeeds before template removal; local/cloud sandbox lists and the cloud template list confirm absence after local copies are verified. Confirm the template persists if only its sandbox is removed. If retaining the destination, confirm stopped status, expiration after resume, file retention, and billing guidance. Remove all disposable test resources. | Pending | Pending | ## Publication decision diff --git a/content/manuals/agentic-platform/guides/local-handoff.md b/content/manuals/agentic-platform/guides/local-handoff.md index 841d11ba6c8e..71ecb0022439 100644 --- a/content/manuals/agentic-platform/guides/local-handoff.md +++ b/content/manuals/agentic-platform/guides/local-handoff.md @@ -76,10 +76,9 @@ $ 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 ``. Also save the -printed template ID as `` for cleanup. The template is the -filesystem image used to create the destination, including `HANDOFF.md`. It -remains after you remove the sandbox. +Use its printed `sbx_`-prefixed ID in place of ``. 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. @@ -95,27 +94,29 @@ 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. -## 3. Verify the destination and restart the agent +## 3. Continue in the Console -Use the destination ID printed by the move to read the transferred handoff: +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. -```console -$ sbx --cloud exec cat /home/agent/workspace/HANDOFF.md -``` - -Expect the recorded baseline, project path, and remaining task. Before starting -work, confirm the move's reported 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 +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. -Restart the agent explicitly; its local process wasn't transferred: +In an additional shell, check the transferred handoff: ```console -$ sbx --cloud run +$ 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 @@ -126,18 +127,19 @@ Complete only the recorded task and save /home/agent/workspace/review.md. ## 4. Disconnect and retrieve the result -Once the agent starts, press `Ctrl+\` to detach. 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. +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 from your computer's terminal: +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. -```console -$ sbx --cloud run -``` +> [!TIP] +> If the terminal appears stuck after reconnecting, try resizing it by resizing +> your browser window. This can make the agent interface redraw. -Review the agent's response. Running resumes a stopped sandbox and starts a -fresh timer. When the report is ready, detach with `Ctrl+\` and copy both files: +When the report is ready, return to your computer's terminal and copy both files: ```console $ sbx --cloud ttl @@ -154,7 +156,17 @@ results is what brings them back to your computer. ## 5. Clean up both sandboxes After verifying your saved files, remove the destination, its template, and the -local source. Delete the cloud sandbox before removing its backing template: +local source. First inspect the destination to identify its backing template, +then list the templates. Find the matching entry, typically named +`moved-handoff-local-`, and use its ID as ``. Check the ID +against the inspected sandbox so you remove only this move's snapshot: + +```console +$ sbx --cloud inspect +$ sbx --cloud template ls +``` + +Delete the cloud sandbox before removing its backing template: ```console $ sbx --cloud rm From 7d94a56ee532a27a45d479bf1f9de743377aa9d5 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Fri, 30 Oct 2026 14:29:19 +0000 Subject: [PATCH 7/8] docs: fix cloud sandbox guide headings and remove review checklist Numbered headings triggered heading punctuation warnings in CI. Remove the visible numbers while preserving heading anchors, and remove the repository review checklist as requested. --- .../review-checklists/cloud-sandbox-guides.md | 102 ------------------ .../agentic-platform/guides/local-handoff.md | 10 +- .../guides/remote-development.md | 12 +-- .../agentic-platform/guides/share-app.md | 10 +- 4 files changed, 16 insertions(+), 118 deletions(-) delete mode 100644 .github/review-checklists/cloud-sandbox-guides.md diff --git a/.github/review-checklists/cloud-sandbox-guides.md b/.github/review-checklists/cloud-sandbox-guides.md deleted file mode 100644 index 0484efd88a41..000000000000 --- a/.github/review-checklists/cloud-sandbox-guides.md +++ /dev/null @@ -1,102 +0,0 @@ -# Verify the cloud sandbox guides - -Use this checklist to review the three Docker Agentic Platform guides before -publication. All live checks are pending. Drafting used documentation references; -commands, Console labels, editor behavior, and version requirements still need -live verification. Source presence doesn't establish account availability. - -Run each journey from its prerequisites through cleanup. For each row, replace -Pending with Pass, Fail, or Blocked, and record the date, observed result, and -supporting output or screenshot in the observations cell. Remove credentials, -tokens, and private data from evidence. Correct the guide after any discrepancy -and repeat the affected checks. A blocked or failed required check prevents -publication. - -## Record the test environment - -Complete a separate record for each guide and repeat it if the environment changes. - -| Field | Share an app | Remote development | Local-to-cloud handoff | -| --- | --- | --- | --- | -| Reviewer and test date | Pending | Pending | Pending | -| Docs commit tested | Pending | Pending | Pending | -| Account capabilities: subscription, cloud entitlement, available architectures and compute sizes | Pending | Pending | Pending | -| Account network restrictions and credential scopes, without secret values | Pending | Pending | Pending | -| CLI version and installation method, or not used | Pending | Pending | Pending | -| Kit name and version or image digest | Pending | Pending | Pending | -| Local OS, architecture, and runtime version, or not used | Pending | Pending | Pending | -| Cloud architecture and compute size | Pending | Pending | Pending | -| Browser version; SSH client and editor/extension versions where used | Pending | Pending | Pending | -| Sample repository full commit ID | Pending | Pending | Pending | -| Start/end times and measured active and elapsed duration | Pending | Pending | Pending | -| Corrections made and retest evidence | Pending | Pending | Pending | - -Don't infer minimum supported versions from one successful run. Check the -0.45.0-or-later requirement in the remote development and handoff guides against -the supported CLI release information and record that evidence. Record any -missing access as Blocked rather than treating an untested claim as confirmed. - -## Share an app - -Guide: [Share an application from a cloud sandbox](../../content/manuals/agentic-platform/guides/share-app.md). - -| Guide section and claim to test | Expected result | Status | Date, observations, and evidence | -| --- | --- | --- | --- | -| Introduction: provisional 20-minute duration | Measure the entire journey and replace the provisional estimate with a measured duration in the guide. | Pending | Pending | -| Before you begin: entitlement, credentials, pricing, and timers | Account can launch the Shell kit without GitHub/model credentials or MCP tools. Console pricing and timeout choices support the guidance. Record compute charging rules and distinguish them from observed usage. | Pending | Pending | -| Step 1: Console launch controls and network policy | The documented labels and Balanced/Open choices exist. Shell starts with the chosen size, duration, and timeout action; no saved credentials or MCP tools are selected. Local files aren't mounted. | Pending | Pending | -| Step 2: clone, build, run, and inspect commands | All commands succeed from the stated directory. Record the sample revision. Container runs with port 3000 mapped inside the sandbox; the mapping alone doesn't publish a cloud URL. | Pending | Pending | -| Step 3: Connect, Connect via a Port, and Open Port | The documented UI publishes port 3000 and returns a working HTTPS URL. A separate browser session signed out of Docker displays the sample. Record that the app has no application authentication and contains no sensitive data. | Pending | Pending | -| Step 3: disconnect behavior | Closing the original browser leaves the sample reachable until an explicit stop or timeout action. | Pending | Pending | -| Step 4: withdraw public access | Closing port 3000 makes the application unreachable on reload in the separate session. Record the observed response and any delay. Confirm the documented container stop command succeeds. | Pending | Pending | -| Step 4: save files and credential scope | Project remains at the documented path. Copy it outside the sandbox using the linked transfer instructions and inspect the copy. If testing the Git alternative, use only the required repository permissions and record them without secrets. | Pending | Pending | -| Step 5: pause, resume, timeout, charges, and deletion | Pause retains files and stops compute charging under the documented billing rules. Resume starts a fresh timer with the original duration. Exercise Stop and Delete timeout actions on disposable sandboxes; confirm retention versus removal. Save work before deletion and confirm the sandbox is absent. | Pending | Pending | - -## Remote development - -Guide: [Develop remotely in a cloud sandbox](../../content/manuals/agentic-platform/guides/remote-development.md). - -Run the editor-specific checks with both VS Code and Cursor. Record versions and -observations separately for each editor, including its Remote - SSH extension. - -| Guide section and claim to test | Expected result | Status | Date, observations, and evidence | -| --- | --- | --- | --- | -| Introduction and prerequisites: provisional 25-minute duration and CLI requirement | Measure each editor journey and replace provisional timing. Record evidence for the minimum CLI version, cloud entitlement, and use of the same Docker account in Console and CLI. | Pending | Pending | -| Step 1: Console controls, credential scope, and clone | Shell launches with Open, without saved credentials or MCP tools. Confirm the editor server and dependencies download with this policy. Stop is available as the timeout action. Clone succeeds without a GitHub token and creates source and Dockerfile at the stated remote path. | Pending | Pending | -| Step 2: login, SSH setup, list, connect, and exit | Each command succeeds. The sbx_-prefixed ID works as the SSH user with sbx_cloud; project files are visible and exit returns to the local terminal. Record any SSH setup prompts or prerequisites missing from the guide. | Pending | Pending | -| Step 3: VS Code connection | The named extension and Command Palette action connect using the tested ID. Remote server installs inside the sandbox and the remote window opens the documented directory. Record exact UI labels and extension version. | Pending | Pending | -| Step 3: Cursor connection | Cursor's Remote - SSH support and Command Palette action connect using the tested ID. Remote server installs inside the sandbox and the remote window opens the documented directory. Record exact extension identity, UI labels, and version. | Pending | Pending | -| Step 4: edit, build, run, preview, and withdraw in each editor | Saved heading change is in the remote files. Build/run commands succeed; public HTTPS preview shows the edit. Closing the public port withdraws access on reload. No sensitive data is exposed. | Pending | Pending | -| Step 5: disconnect and reconnect in each editor | Closing the window leaves the sandbox running. Reconnection opens the same files and saved change. After a timer stop, resume permits reconnection with a fresh timer; restart the workload if required and record that behavior. | Pending | Pending | -| Step 5: copy and optional Git credential | The documented cp command creates a local project copy containing the edit. Files don't sync automatically. If testing the Git alternative, record required repository permissions without secrets. | Pending | Pending | -| Before you begin and step 6: file/process location, timers, charges, and cleanup | Editor window runs locally; project, terminal processes, and remote server live in the sandbox. Confirm billing guidance for running/disconnected and paused states. Pause retains files, resume refreshes the original timer, and deletion removes the sandbox after verifying the saved copy. | Pending | Pending | - -## Local-to-cloud handoff - -Guide: [Continue local work in the cloud](../../content/manuals/agentic-platform/guides/local-handoff.md). - -| Guide section and claim to test | Expected result | Status | Date, observations, and evidence | -| --- | --- | --- | --- | -| Introduction and prerequisites: provisional 25-minute duration, CLI/runtime, and architecture | Measure the journey and replace provisional timing. Record evidence for minimum CLI version, supported local runtime, and support for both amd64 and arm64 in the cloud. The destination matches the local architecture. | Pending | Pending | -| Before you begin: login, diagnose, and separate secret commands | Commands succeed with the recorded account. Cloud Claude Code requires an API key, while local Claude Code also supports subscriptions. Verify this distinction against Anthropic's terms and supported authentication guidance. Local and cloud Anthropic credentials are configured separately; record required scope without keys. Confirm compute and inference charging guidance against billing information. | Pending | Pending | -| Step 1: create, policy, clone, and run commands | Sandbox is created without a host workspace argument; public sample is cloned inside its filesystem. Agent starts with the managed local credential and no GitHub token. | Pending | Pending | -| Step 1: bounded prompt, baseline, and credential removal | HANDOFF.md records the full matching Git revision, clean tree, project path, and remaining task without starting the review. No application files change or dependencies install. Review filesystem credential files before capture and remove them without recording secrets in evidence. | Pending | Pending | -| Step 2: move command and timeout support | Exact move command succeeds with a two-hour Stop action or fails explicitly if stopping is unsupported. Local source stops for capture; a distinct cloud destination and backing template ID are reported. The template contains the captured HANDOFF.md. Record command output and supported options. | Pending | Pending | -| Step 2: transfer boundaries | Destination contains filesystem files, but local processes, memory, sockets, host mounts, clone-mode volumes, managed secrets, and local network rules aren't transferred. Use disposable non-sensitive fixtures for applicable boundaries and record any boundary not exercised as pending. Verify documented TCP port republication/warning behavior separately on disposable resources. | Pending | Pending | -| Step 3: transferred handoff and destination settings | The moved destination appears in Console under the same account and can be selected by its printed sbx_-prefixed ID. An additional browser shell can read HANDOFF.md with cat. The handoff file contains the recorded baseline, project path, and remaining task. Platform, size, expiration, cloud credential, and destination policy are correct; no unintended ports remain. | Pending | Pending | -| Step 3: browser terminal and agent restart | The moved sandbox opens an agent terminal in Console using destination credentials and policy; record any startup steps missing from the guide. Agent confirms the baseline and completes only the saved task, without an application run. The local agent process hasn't transferred. | Pending | Pending | -| Step 4: browser disconnect, reconnect, and resume after stop | Closing the browser leaves cloud work running until timeout. Reopening the destination reconnects to the agent; resizing the browser redraws the interface if it appears stuck. No work runs while stopped; Restore to connect resumes the destination and starts a fresh timer. Record whether the rendering workaround is needed and effective. | Pending | Pending | -| Step 4: retrieve and verify artifacts | Both cp commands succeed and local copies contain the matching baseline, build/startup explanation, listening port, one recommendation with source references, and limitations. Compare the report with the source; record corrections rather than accepting agent claims as test evidence. | Pending | Pending | -| Step 5: remove both sandboxes and the backing template, or retain a stopped destination | Inspect identifies the backing template; template ls lists it and its ID, without requiring an ID saved during the move. Confirm the matching moved-handoff-local entry before removal. Sandbox removal succeeds before template removal; local/cloud sandbox lists and the cloud template list confirm absence after local copies are verified. Confirm the template persists if only its sandbox is removed. If retaining the destination, confirm stopped status, expiration after resume, file retention, and billing guidance. Remove all disposable test resources. | Pending | Pending | - -## Publication decision - -- [ ] Every required row passes with dated observations and evidence. -- [ ] Both editor journeys pass with separate version records. -- [ ] Commands, UI labels, availability, and minimum versions match the evidence. -- [ ] Provisional durations are replaced with measured durations. -- [ ] Discrepancies are corrected in the guides and affected checks repeated. -- [ ] Saved copies are verified and test sandboxes, backing templates, public ports, and temporary credentials are cleaned up. -- [ ] Reviewer records the tested docs commit and approves publication. - -Decision: Pending. Reviewer, date, and remaining blockers: Pending. diff --git a/content/manuals/agentic-platform/guides/local-handoff.md b/content/manuals/agentic-platform/guides/local-handoff.md index 71ecb0022439..e1ca847375e8 100644 --- a/content/manuals/agentic-platform/guides/local-handoff.md +++ b/content/manuals/agentic-platform/guides/local-handoff.md @@ -34,7 +34,7 @@ $ sbx --cloud secret set anthropic Local and cloud secret stores are separate. See [Cloud credentials](/manuals/ai/sandboxes/cloud/credentials.md). -## 1. Prepare files inside the local sandbox +## Prepare files inside the local sandbox {#1-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 @@ -67,7 +67,7 @@ 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. -## 2. Move the filesystem +## Move the filesystem {#2-move-the-filesystem} From your computer, run: @@ -94,7 +94,7 @@ 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. -## 3. Continue in the Console +## Continue in the Console {#3-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 @@ -125,7 +125,7 @@ working tree before doing the remaining review. Stop and report a mismatch. Complete only the recorded task and save /home/agent/workspace/review.md. ``` -## 4. Disconnect and retrieve the result +## Disconnect and retrieve the result {#4-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; @@ -153,7 +153,7 @@ 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. -## 5. Clean up both sandboxes +## Clean up both sandboxes {#5-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, diff --git a/content/manuals/agentic-platform/guides/remote-development.md b/content/manuals/agentic-platform/guides/remote-development.md index 2bf95c1914b1..6f6c38a165e4 100644 --- a/content/manuals/agentic-platform/guides/remote-development.md +++ b/content/manuals/agentic-platform/guides/remote-development.md @@ -21,7 +21,7 @@ Your editor window runs locally. Project files, terminal commands, and the editor's remote server run inside the sandbox. Files don't sync to your computer. Docker bills compute while the sandbox runs, even with the editor disconnected. -## 1. Create the remote project +## Create the remote project {#1-create-the-remote-project} 1. Open the [Console](https://agentic-platform.docker.com/) and select **+ New sandbox**. 2. Choose **shell**, deselect saved credentials and MCP tools, and select @@ -39,7 +39,7 @@ Docker bills compute while the sandbox runs, even with the editor disconnected. Expect `/home/agent/workspace/project` to contain the sample source and Dockerfile. Local workspaces aren't mounted in the cloud sandbox. -## 2. Configure and test SSH +## Configure and test SSH {#2-configure-and-test-ssh} In a terminal on your computer, run: @@ -62,7 +62,7 @@ your computer. Use the ID, rather than the sandbox's display name, for SSH. See [Connect with SSH](/manuals/ai/sandboxes/cloud/usage.md#connect-with-ssh) for proxy troubleshooting. -## 3. Connect your editor +## Connect your editor {#3-connect-your-editor} Choose the instructions for your editor: @@ -81,7 +81,7 @@ For local sandbox integration, see the separate [VS Code](/manuals/ai/sandboxes/integrations/vscode.md) and [Cursor](/manuals/ai/sandboxes/integrations/cursor.md) pages. -## 4. Edit and preview remotely +## Edit and preview remotely {#4-edit-and-preview-remotely} In the remote editor, find a visible heading in the application's source, change its text, and save the file. In the editor's remote terminal, build and run: @@ -99,7 +99,7 @@ protect it. Use non-sensitive data and application authentication for private content. Close the port in **Connect** after checking the preview and reload the URL to verify the application is no longer reachable. -## 5. Reconnect and keep your work +## Reconnect and keep your work {#5-reconnect-and-keep-your-work} Close the remote editor window, then connect again using the same host entry and open the same directory. Expect your saved change to remain. Disconnecting @@ -117,7 +117,7 @@ commit and push to a repository you control. Configure a [GitHub credential](/manuals/agentic-platform/secrets.md#github-credential) with the required repository permissions before launching a sandbox for that workflow. -## 6. Clean up +## Clean up {#6-clean-up} In **Sandboxes**, pause the sandbox and confirm its paused status to stop compute charges and retain files. A resumed sandbox gets a fresh timer with the original diff --git a/content/manuals/agentic-platform/guides/share-app.md b/content/manuals/agentic-platform/guides/share-app.md index 06fb3e1eac4f..1bc49559b086 100644 --- a/content/manuals/agentic-platform/guides/share-app.md +++ b/content/manuals/agentic-platform/guides/share-app.md @@ -24,7 +24,7 @@ Review the compute price and timer before launching. Choose **Stop** as the timeout action to retain files; **Delete** removes them. A stopped application can't serve visitors. See [Sandbox lifecycle](/manuals/agentic-platform/sandboxes.md#manage-the-lifecycle). -## 1. Launch a shell +## Launch a shell {#1-launch-a-shell} 1. Open the [Console](https://agentic-platform.docker.com/) and select **+ New sandbox**. 2. Choose the **shell** kit. Deselect saved credentials and MCP tools. @@ -37,7 +37,7 @@ The browser terminal opens a Bash shell inside the sandbox. Local files aren't mounted there. See [Network policies](/manuals/agentic-platform/policies.md) if your account applies additional restrictions. -## 2. Build and run the sample +## Build and run the sample {#2-build-and-run-the-sample} In the sandbox terminal, clone the public project into the sandbox filesystem: @@ -58,7 +58,7 @@ $ docker ps --filter name=welcome-to-docker Expect the container to be running with port `3000` published in the sandbox. This container port mapping alone doesn't create the public cloud URL. -## 3. Open and share the preview +## Open and share the preview {#3-open-and-share-the-preview} 1. On the sandbox detail page, select **Connect**. 2. Under **Connect via a Port**, enter `3000` and select **Open Port**. @@ -70,7 +70,7 @@ This container port mapping alone doesn't create the public cloud URL. The service runs inside the sandbox. Closing your browser leaves it running until you stop it or the timer action takes effect. -## 4. Withdraw access and save work +## Withdraw access and save work {#4-withdraw-access-and-save-work} Use the close action next to port `3000` in **Connect**. In the separate browser session, reload the URL and confirm that the application is no longer reachable. @@ -89,7 +89,7 @@ or push them to a repository you control using an appropriately scoped [GitHub credential](/manuals/agentic-platform/secrets.md#github-credential). Verify your saved copy before deleting the sandbox; files don't sync automatically. -## 5. Clean up +## Clean up {#5-clean-up} In **Sandboxes**, pause the sandbox and confirm its paused status to stop compute charges while retaining files. Resuming starts a fresh timer with the original From e0406c3cdd83eec8741228eb561eb18b5a0a9547 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Fri, 30 Oct 2026 14:33:14 +0000 Subject: [PATCH 8/8] docs: remove explicit IDs from cloud sandbox guide headings The workflow headings retain unnecessary IDs from their numbered versions. Remove the explicit IDs so Hugo generates anchors from the heading text. --- .../manuals/agentic-platform/guides/local-handoff.md | 10 +++++----- .../agentic-platform/guides/remote-development.md | 12 ++++++------ content/manuals/agentic-platform/guides/share-app.md | 10 +++++----- 3 files changed, 16 insertions(+), 16 deletions(-) diff --git a/content/manuals/agentic-platform/guides/local-handoff.md b/content/manuals/agentic-platform/guides/local-handoff.md index e1ca847375e8..757ba38b1833 100644 --- a/content/manuals/agentic-platform/guides/local-handoff.md +++ b/content/manuals/agentic-platform/guides/local-handoff.md @@ -34,7 +34,7 @@ $ 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 {#1-prepare-files-inside-the-local-sandbox} +## 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 @@ -67,7 +67,7 @@ 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 {#2-move-the-filesystem} +## Move the filesystem From your computer, run: @@ -94,7 +94,7 @@ 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 {#3-continue-in-the-console} +## 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 @@ -125,7 +125,7 @@ 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 {#4-disconnect-and-retrieve-the-result} +## 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; @@ -153,7 +153,7 @@ 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 {#5-clean-up-both-sandboxes} +## 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, diff --git a/content/manuals/agentic-platform/guides/remote-development.md b/content/manuals/agentic-platform/guides/remote-development.md index 6f6c38a165e4..2125d151b431 100644 --- a/content/manuals/agentic-platform/guides/remote-development.md +++ b/content/manuals/agentic-platform/guides/remote-development.md @@ -21,7 +21,7 @@ Your editor window runs locally. Project files, terminal commands, and the editor's remote server run inside the sandbox. Files don't sync to your computer. Docker bills compute while the sandbox runs, even with the editor disconnected. -## Create the remote project {#1-create-the-remote-project} +## Create the remote project 1. Open the [Console](https://agentic-platform.docker.com/) and select **+ New sandbox**. 2. Choose **shell**, deselect saved credentials and MCP tools, and select @@ -39,7 +39,7 @@ Docker bills compute while the sandbox runs, even with the editor disconnected. Expect `/home/agent/workspace/project` to contain the sample source and Dockerfile. Local workspaces aren't mounted in the cloud sandbox. -## Configure and test SSH {#2-configure-and-test-ssh} +## Configure and test SSH In a terminal on your computer, run: @@ -62,7 +62,7 @@ your computer. Use the ID, rather than the sandbox's display name, for SSH. See [Connect with SSH](/manuals/ai/sandboxes/cloud/usage.md#connect-with-ssh) for proxy troubleshooting. -## Connect your editor {#3-connect-your-editor} +## Connect your editor Choose the instructions for your editor: @@ -81,7 +81,7 @@ For local sandbox integration, see the separate [VS Code](/manuals/ai/sandboxes/integrations/vscode.md) and [Cursor](/manuals/ai/sandboxes/integrations/cursor.md) pages. -## Edit and preview remotely {#4-edit-and-preview-remotely} +## Edit and preview remotely In the remote editor, find a visible heading in the application's source, change its text, and save the file. In the editor's remote terminal, build and run: @@ -99,7 +99,7 @@ protect it. Use non-sensitive data and application authentication for private content. Close the port in **Connect** after checking the preview and reload the URL to verify the application is no longer reachable. -## Reconnect and keep your work {#5-reconnect-and-keep-your-work} +## Reconnect and keep your work Close the remote editor window, then connect again using the same host entry and open the same directory. Expect your saved change to remain. Disconnecting @@ -117,7 +117,7 @@ commit and push to a repository you control. Configure a [GitHub credential](/manuals/agentic-platform/secrets.md#github-credential) with the required repository permissions before launching a sandbox for that workflow. -## Clean up {#6-clean-up} +## Clean up In **Sandboxes**, pause the sandbox and confirm its paused status to stop compute charges and retain files. A resumed sandbox gets a fresh timer with the original diff --git a/content/manuals/agentic-platform/guides/share-app.md b/content/manuals/agentic-platform/guides/share-app.md index 1bc49559b086..0ef793ed6658 100644 --- a/content/manuals/agentic-platform/guides/share-app.md +++ b/content/manuals/agentic-platform/guides/share-app.md @@ -24,7 +24,7 @@ Review the compute price and timer before launching. Choose **Stop** as the timeout action to retain files; **Delete** removes them. A stopped application can't serve visitors. See [Sandbox lifecycle](/manuals/agentic-platform/sandboxes.md#manage-the-lifecycle). -## Launch a shell {#1-launch-a-shell} +## Launch a shell 1. Open the [Console](https://agentic-platform.docker.com/) and select **+ New sandbox**. 2. Choose the **shell** kit. Deselect saved credentials and MCP tools. @@ -37,7 +37,7 @@ The browser terminal opens a Bash shell inside the sandbox. Local files aren't mounted there. See [Network policies](/manuals/agentic-platform/policies.md) if your account applies additional restrictions. -## Build and run the sample {#2-build-and-run-the-sample} +## Build and run the sample In the sandbox terminal, clone the public project into the sandbox filesystem: @@ -58,7 +58,7 @@ $ docker ps --filter name=welcome-to-docker Expect the container to be running with port `3000` published in the sandbox. This container port mapping alone doesn't create the public cloud URL. -## Open and share the preview {#3-open-and-share-the-preview} +## Open and share the preview 1. On the sandbox detail page, select **Connect**. 2. Under **Connect via a Port**, enter `3000` and select **Open Port**. @@ -70,7 +70,7 @@ This container port mapping alone doesn't create the public cloud URL. The service runs inside the sandbox. Closing your browser leaves it running until you stop it or the timer action takes effect. -## Withdraw access and save work {#4-withdraw-access-and-save-work} +## Withdraw access and save work Use the close action next to port `3000` in **Connect**. In the separate browser session, reload the URL and confirm that the application is no longer reachable. @@ -89,7 +89,7 @@ or push them to a repository you control using an appropriately scoped [GitHub credential](/manuals/agentic-platform/secrets.md#github-credential). Verify your saved copy before deleting the sandbox; files don't sync automatically. -## Clean up {#5-clean-up} +## Clean up In **Sandboxes**, pause the sandbox and confirm its paused status to stop compute charges while retaining files. Resuming starts a fresh timer with the original