feat(cli): forkd from-image — Docker image → snapshot in one command#136
Merged
Conversation
Closes the OCI-native distribution gap. boxlite's pitch is \"docker pull python:slim and you're done\"; forkd previously required users to chain \`forkd parent build\` (image → ext4) and \`forkd snapshot --kernel ... --rootfs ...\` themselves. This wraps the pipeline into one verb. forkd from-image python:3.12-slim --tag py-numpy --extra python3-numpy # → builds rootfs (cached), boots parent, warms up, snapshots, # registers 'py-numpy' tag. Ready to fork. Resolves \`--kernel\` by searching standard paths if unset: ./vmlinux-6.1.141 → ./vmlinux → /var/lib/forkd/kernels/vmlinux → /usr/local/share/forkd/vmlinux Calls existing parent_build_cmd and snapshot_cmd internally — no new boot/snapshot machinery, just the convenience chain that boxlite-style users expect. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
fe619e5 to
f9f079f
Compare
WaylandYang
added a commit
that referenced
this pull request
May 21, 2026
…start (#137) The 3 CLI commands shipped 2026-05-21 (#134, #135, #136) collapse the new-user setup from 4 hand-pasted commands to a single \`forkd doctor\` + \`forkd from-image\` flow. Surface this prominently in Quick start so visitors landing from a Twitter / blog link see the modern story. - README.md: new \"Confirm your host is ready\" subsection leads with \`forkd doctor\`. New \"From a Docker image (one command)\" subsection shows \`forkd from-image python:3.12-slim --tag py-numpy\`. New \"Probe your install's latency\" subsection shows \`forkd bench\` with example output. - README-zh.md: parallel sections in Chinese. The original Hub-pull, from-source, and multi-child-fork-out sections are unchanged — those audiences still need them. New subsections come first since they're the most-likely user path. No code changes. Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
WaylandYang
added a commit
that referenced
this pull request
May 21, 2026
* docs: feature \`forkd doctor\` / \`from-image\` / \`bench\` in Quick start The 3 CLI commands shipped 2026-05-21 (#134, #135, #136) collapse the new-user setup from 4 hand-pasted commands to a single \`forkd doctor\` + \`forkd from-image\` flow. Surface this prominently in Quick start so visitors landing from a Twitter / blog link see the modern story. - README.md: new \"Confirm your host is ready\" subsection leads with \`forkd doctor\`. New \"From a Docker image (one command)\" subsection shows \`forkd from-image python:3.12-slim --tag py-numpy\`. New \"Probe your install's latency\" subsection shows \`forkd bench\` with example output. - README-zh.md: parallel sections in Chinese. The original Hub-pull, from-source, and multi-child-fork-out sections are unchanged — those audiences still need them. New subsections come first since they're the most-likely user path. No code changes. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(cli): \`forkd ls\` + \`forkd kill\` — direct sandbox lifecycle Two small subcommands that wrap GET /v1/sandboxes and DELETE /v1/sandboxes/:id so users don't have to hand-write curl. Same ergonomics as \`docker ps\` / \`docker rm\`. forkd ls ID SNAPSHOT PID NETNS GUEST_ADDR sb-6a0e8d4f-0023 coding-agent-fork-prewarm-v1 123456 forkd-child-1 10.42.0.2:8888 sb-6a0e8d50-0024 speculative-1234 123457 forkd-child-2 10.42.0.2:8888 ... 2 sandboxes forkd kill sb-6a0e8d4f-0023 ✓ sb-6a0e8d4f-0023 forkd kill --all forkd kill --tag speculative-1234 Implementation in crates/forkd-cli/src/sandbox.rs (~170 LOC), wired in main.rs as Cmd::Ls / Cmd::Kill. Reads FORKD_URL / FORKD_TOKEN from env like the other daemon-talking commands. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes the OCI-native distribution gap. Before this PR, going from a Docker image to a forkd snapshot required two commands:
```bash
forkd parent build python:3.12-slim --output python.ext4 --extra python3-numpy
forkd snapshot --tag py-numpy --kernel ./vmlinux-6.1.141 --rootfs python.ext4 --tap forkd-tap0
```
After this PR, one command:
```bash
forkd from-image python:3.12-slim --tag py-numpy --extra python3-numpy
```
Same pipeline (Docker pull → ext4 → boot + warmup → pause → register tag), wrapped in one verb. boxlite's positioning is "docker pull X and you're done"; this matches that surface.
Design
Smoke tests on dev box
```
$ forkd from-image --help
Build a forkd snapshot from a Docker image in one command.
...
$ forkd from-image alpine:latest --tag t --kernel /nonexistent
Error: kernel not found: /nonexistent
$ forkd from-image alpine:latest --tag t # no kernel in cwd or env
Error: no kernel found; pass --kernel or set FORKD_KERNEL. searched: ./vmlinux-6.1.141, ./vmlinux, /var/lib/forkd/kernels/vmlinux, /usr/local/share/forkd/vmlinux
```
End-to-end pipeline not run in CI (requires root + Docker + ~3 minutes per image); the underlying `parent_build_cmd` and `snapshot_cmd` are already exercised separately. This PR is convenience wiring.
Files
🤖 Generated with Claude Code