Add guide: run a Java coding agent safely with Docker Sandboxes#25474
Add guide: run a Java coding agent safely with Docker Sandboxes#25474dvdksn wants to merge 14 commits into
Conversation
Add a guide that builds a reusable sbx kit to make a coding agent productive on a Spring Boot project inside an isolated microVM: install SDKMAN, a Temurin JDK, and Maven, put them on PATH for both sbx exec and the agent shell, discover the minimal network allowlist, and run Testcontainers integration tests against the sandbox's Docker daemon. Feature the new guide in place of "Use OpenCode with Docker Model Runner", and add Temurin to the Vale vocabulary. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
✅ Deploy Preview for docsdocker ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
docker-agent
left a comment
docker-agent
left a comment
There was a problem hiding this comment.
Assessment: 🟡 NEEDS ATTENTION
The new Java coding agent sandbox guide is well-structured and technically solid. Two medium-severity issues need attention before publishing:
- Meta-commentary aside (line 21): The security risk is stated indirectly; a direct statement would be clearer and more consistent with the style guide.
- Placeholder date (line 333):
2026-xx-xxin the example output will render verbatim on the published page.
No missing front matter, no broken Markdown, no vendored-file edits, and no missing redirects were found. The Vale vocabulary addition and the featured flag change are clean.
- Reframe the title/description around safely running a coding agent on a Java project (the agent is general, the development is Java-specific). - Reword the sample description to emphasize a representative Java setup instead of "a good test of the whole setup". - Format in-agent (Claude Code `!` shell) interactions as plaintext without a shell `$` prompt; keep `console` for host commands. - Frame `.sbx/kits/<name>/` as a suggested location and clarify that committing the kit is optional but good for sharing across a team. - Switch the kit spec to the current `network.allow` property and drop the allowedDomains deprecation callout. - Clarify that the sandbox denies outbound network requests by default. - Move the human launch command to the README, add kit-specific agent context via the `agentContext` key instead of CLAUDE.md, and add a tip about enforcing sandbox use through agent instructions. - Link both the kits overview and the kit spec reference. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The allowedDomains -> allow rename isn't in the shipped kit-reference.md (only memory -> agentContext, kind: agent -> sandbox, and the agent -> sandbox block rename are documented). Align the guide's spec with the reference as it stands. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Running through the guide showed the base image already includes a JDK (Java 25); only Maven is missing. Reframe the intro and the bare-sandbox check to reflect this: the sandbox preinstalls a useful tool set but not everything, manual installs are per-sandbox and drift, and a kit makes provisioning consistent and reusable. Note the kit still pins a JDK so the version doesn't drift with the base image. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Replace the <sandbox-name> placeholders with a concrete 'java-tmp' name: launch with 'sbx run --name java-tmp', target it directly in policy log and exec, and force-remove it with 'sbx rm -f java-tmp' between phases and at the end. Keep the README's launch command in its clean, nameless form. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
A kit whose install commands need the network can't be run without a network block: the blocked requests fail the install and 'sbx run' never finishes creating the sandbox. Stop instructing the reader to run the kit before the allowlist exists. Explain the up-front requirement, declare the allowlist directly, and move domain discovery into a failure-free tip (allow all briefly, build, read 'sbx policy log', then lock down). Section that runs the tests is now the first successful --kit create. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Remove the tip that suggested 'sbx policy allow network "**"' to discover domains — it's a hack. The guide already sequences things to avoid the problem: the allowlist is declared as part of building the kit, before the kit is ever run. Reword the two 'discover' references to match the declare-up-front approach. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Move the 'sbx kit validate' step out of the toolchain-install section (where it ran against an incomplete, install-only spec) to the top of the test section, after the network allowlist is added and just before the first run. Reflects the declare-up-front flow. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
docker-agent
left a comment
docker-agent
left a comment
There was a problem hiding this comment.
Assessment: 🟡 NEEDS ATTENTION
| > relaunch you with `sbx run claude --kit .sbx/kits/java-toolchain`. | ||
| > ``` | ||
| > | ||
| > It's opinionated, but it turns "use the sandbox" from a suggestion into |
There was a problem hiding this comment.
[MEDIUM] Meta-commentary phrase "It's opinionated, but…" violates Docker style guide
Docker's style guide prohibits meta-commentary — phrases that comment on the advice itself rather than stating information directly. "It's opinionated, but…" is in the same category as "It's worth noting that…" or "Keep in mind that…": it adds a layer of self-reflection instead of stating the fact.
Suggested rewrite:
This turns "use the sandbox" from a suggestion into something the agent helps enforce.
| linkTitle: Kit out your sandbox for Java | ||
| description: Use a Docker Sandbox and a reusable sbx kit to run a coding agent on a Spring Boot project, without giving it unrestricted access to your machine. | ||
| keywords: ai, sbx, docker sandboxes, java, spring boot, testcontainers, maven, sdkman, coding agent, kit | ||
| weight: 3 |
There was a problem hiding this comment.
[MEDIUM] New guide uses same weight: 3 as opencode-model-runner.md, producing ambiguous sidebar ordering
Both content/guides/java-coding-agent-sandbox.md (added by this PR) and content/guides/opencode-model-runner.md (unchanged) declare weight: 3. Hugo uses weight for sidebar ordering; when two pages share the same value, sort order falls back to Hugo's tiebreaking behavior (typically alphabetical by filename), which is undocumented and could change between Hugo versions.
If the intent is for the new guide to appear before the OpenCode guide, set weight: 3 for the new guide and bump the OpenCode guide to weight: 4 (or vice versa), so the ordering is explicit.
docker-agent
left a comment
docker-agent
left a comment
There was a problem hiding this comment.
Assessment: 🟡 NEEDS ATTENTION
The new Java coding agent sandbox guide is technically thorough and well-structured. Front matter is complete. The opencode-model-runner.md change (removing featured: true) is correct. The Temurin vocabulary addition is appropriate.
Five medium-severity style guide violations were found in the new guide — all in newly added content. No broken commands, broken Markdown, or missing redirects were identified.
| @@ -0,0 +1,471 @@ | |||
| --- | |||
| title: Run a coding agent safely on a Java project with Docker Sandboxes | |||
| linkTitle: Kit out your sandbox for Java | |||
There was a problem hiding this comment.
[MEDIUM] linkTitle uses colloquial slang
The value Kit out your sandbox for Java uses the British/colloquial idiom "kit out" (meaning to equip or outfit), which is inconsistent with Docker's documentation voice. The style guide requires action-oriented, plain US English for navigation titles.
Consider a more direct alternative such as: Java coding agent sandbox or Run a Java coding agent in a sandbox.
| featured: true | ||
| --- | ||
|
|
||
| Coding agents are most useful when they can build and test your project: |
There was a problem hiding this comment.
[MEDIUM] Opening paragraph does not answer "What will I learn?" and "Why does this matter?"
The Docker style guide requires the first paragraph to answer two questions: what the reader will learn, and why it matters. The current opening paragraph is entirely problem-context framing — it explains what agents need and the risk of running them on your machine, but defers "What will I learn?" to a bullet list after a two-paragraph preamble.
Consider leading with the outcome and benefit, then providing the context. For example:
In this guide, you'll build a reusable
sbxkit so a coding agent can build and test a Spring Boot project inside an isolated microVM — with a full Java toolchain, a working Docker daemon, and a minimal network allowlist. That means the agent can do real work without accessing your credentials or full file system.
| the `claude` agent attached to your terminal. The agent can read and edit your | ||
| files, and it has its own Docker daemon, and the base image comes with a useful | ||
| set of tools — but not everything a given project needs. Ask it to check the | ||
| toolchain, or run the check yourself through the agent's `!` shell (the `!` |
There was a problem hiding this comment.
[MEDIUM] Parenthetical explanation violates style guide
The Docker style guide says to avoid parentheses in technical documentation and restructure as a separate sentence instead. The phrase (the ! prefix runs a command in the sandbox and prints the result) should be its own sentence:
The
!prefix runs a command in the sandbox and prints the result. Ask it to check the toolchain, or run the check yourself:
| and you can see exactly what the agent is allowed to reach. | ||
|
|
||
| > [!NOTE] | ||
| > Your host might already have broader policy rules (for GitHub or Docker Hub, |
There was a problem hiding this comment.
[MEDIUM] Colloquial "say" should be "for example"
The word "say" used here is a colloquial British English construction meaning "for example." Docker documentation is written in US English, and the style guide says to use "for example" or "such as" — not "e.g.", and certainly not "say."
Suggested rewrite:
Your host might already have broader policy rules — for example, for GitHub or Docker Hub — from other work.
| > relaunch you with `sbx run claude --kit .sbx/kits/java-toolchain`. | ||
| > ``` | ||
| > | ||
| > It's opinionated, but it turns "use the sandbox" from a suggestion into |
There was a problem hiding this comment.
[MEDIUM] Meta-commentary "It's opinionated" — state the fact directly
The Docker style guide says to avoid meta-commentary and state facts directly. "It's opinionated" is a subjective characterization that adds no factual value. The second clause already states the practical benefit clearly.
Suggested rewrite — simply drop the first clause:
This turns "use the sandbox" from a suggestion into something the agent helps enforce.
|
I'm not very happy with this guide atm, because there is a glaring UX gap in discovering which domains you need to allow in your network policy. I've reported that upstream in docker/sandboxes#3961 Until that is fixed, I'd like to hold off with publishing, because it really just means there's no way to "discover" what you need to whitelist. You just have to know 🫠 So I'll follow up with updates once the workflow is better. |
2 participants
Description
Adds a new guide, Run a Java coding agent safely with Docker Sandboxes, under
content/guides/.The guide walks through building a reusable
sbxkit that makes a coding agent productive on a Spring Boot project inside an isolated microVM:mixinkit that installs SDKMAN, a Temurin JDK 25, and Maven, and putsjava/mvnonPATHfor bothsbx execand the agent's shell.Discover the minimal network allowlist a Spring Boot + Maven workflow needs via- this is currently not possible (on latest main) - needs a fix upstream.sbx policy log, instead of guessing.The sample is based on the official Testcontainers guide
tc-guide-testing-spring-boot-kafka-listener.Also in this PR
featured: trueto the new guide atweight: 3; the OpenCode guide keeps its tags/weight, just unfeatured).Temurinto the Vale vocabulary (_vale/config/vocabularies/Docker/accept.txt).Open items
sbxTUI network-approval view is left as a<!-- TODO -->in the "Open the network" section and needs to be added before this leaves draft.🤖 Generated with Claude Code