feat(cli): forkd doctor — diagnose host setup with fix hints#134
Merged
Conversation
WaylandYang
force-pushed
the
feat/cli-doctor
branch
from
08752b6 to
07276e8
Compare
New subcommand that runs 10 checks against the host's forkd-readiness: - platform (Linux + kernel) - KVM (/dev/kvm presence + readability) - cgroup v2 (memory.max enforcement) - ip_forward sysctl (1 = required) - forkd-tap0 device (presence + operstate) - per-child netns count (forkd-child-*) - firecracker binary on PATH - kernel image present (vmlinux-*) - snapshot dir (XDG_DATA_HOME/forkd/snapshots) - controller daemon reachable (configurable URL + token) Each check emits PASS / WARN / FAIL / SKIP with a one-line detail and (on non-pass) a specific fix hint. Designed to compress the "I ran \`forkd fork\` and got a mysterious error" loop into one command. Safe to run unprivileged; checks that need root degrade to SKIP with a note rather than failing. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
WaylandYang
force-pushed
the
feat/cli-doctor
branch
from
07276e8 to
f7b2e98
Compare
WaylandYang
added a commit
that referenced
this pull request
May 21, 2026
Companion to \`forkd doctor\` (#134). Runs a representative spawn → exec → branch(diff=true) → fanout(N) → cleanup cycle against a live daemon and prints per-step timing. Output is screenshot-friendly. Use case: "is forkd actually fast on this box?" — answer in 1 command, without writing a benchmark script. Also useful for regression checks after a daemon config change. Example output: forkd bench against snapshot coding-agent-fork-prewarm-v1 fanout n=5 per_child_netns=true spawn (n=1) 123 ms sb-...-0001 exec round-trip 8 ms exit=0 branch (diff=true) 287 ms pause_ms=234 diff_physical_bytes=393216 fanout (n=5) 142 ms 28ms/child cleanup 45 ms 6 sandboxes ----- total 605 ms Implementation: ~210 LOC in crates/forkd-cli/src/bench.rs. Uses ureq directly (small wrapper) instead of pulling reqwest for one command. Subcommand wired in main.rs with --tag / --n / --per-child-netns / --daemon-url / --daemon-token options. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
WaylandYang
added a commit
that referenced
this pull request
May 21, 2026
Companion to \`forkd doctor\` (#134). Runs a representative spawn → exec → branch(diff=true) → fanout(N) → cleanup cycle against a live daemon and prints per-step timing. Output is screenshot-friendly. Use case: "is forkd actually fast on this box?" — answer in 1 command, without writing a benchmark script. Also useful for regression checks after a daemon config change. Example output: forkd bench against snapshot coding-agent-fork-prewarm-v1 fanout n=5 per_child_netns=true spawn (n=1) 123 ms sb-...-0001 exec round-trip 8 ms exit=0 branch (diff=true) 287 ms pause_ms=234 diff_physical_bytes=393216 fanout (n=5) 142 ms 28ms/child cleanup 45 ms 6 sandboxes ----- total 605 ms Implementation: ~210 LOC in crates/forkd-cli/src/bench.rs. Uses ureq directly (small wrapper) instead of pulling reqwest for one command. Subcommand wired in main.rs with --tag / --n / --per-child-netns / --daemon-url / --daemon-token options. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
WaylandYang
added a commit
that referenced
this pull request
May 21, 2026
Companion to \`forkd doctor\` (#134). Runs a representative spawn → exec → branch(diff=true) → fanout(N) → cleanup cycle against a live daemon and prints per-step timing. Output is screenshot-friendly. Use case: "is forkd actually fast on this box?" — answer in 1 command, without writing a benchmark script. Also useful for regression checks after a daemon config change. Example output: forkd bench against snapshot coding-agent-fork-prewarm-v1 fanout n=5 per_child_netns=true spawn (n=1) 123 ms sb-...-0001 exec round-trip 8 ms exit=0 branch (diff=true) 287 ms pause_ms=234 diff_physical_bytes=393216 fanout (n=5) 142 ms 28ms/child cleanup 45 ms 6 sandboxes ----- total 605 ms Implementation: ~210 LOC in crates/forkd-cli/src/bench.rs. Uses ureq directly (small wrapper) instead of pulling reqwest for one command. Subcommand wired in main.rs with --tag / --n / --per-child-netns / --daemon-url / --daemon-token options. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
WaylandYang
added a commit
that referenced
this pull request
May 21, 2026
Companion to \`forkd doctor\` (#134). Runs a representative spawn → exec → branch(diff=true) → fanout(N) → cleanup cycle against a live daemon and prints per-step timing. Output is screenshot-friendly. Use case: "is forkd actually fast on this box?" — answer in 1 command, without writing a benchmark script. Also useful for regression checks after a daemon config change. Example output: forkd bench against snapshot coding-agent-fork-prewarm-v1 fanout n=5 per_child_netns=true spawn (n=1) 123 ms sb-...-0001 exec round-trip 8 ms exit=0 branch (diff=true) 287 ms pause_ms=234 diff_physical_bytes=393216 fanout (n=5) 142 ms 28ms/child cleanup 45 ms 6 sandboxes ----- total 605 ms Implementation: ~210 LOC in crates/forkd-cli/src/bench.rs. Uses ureq directly (small wrapper) instead of pulling reqwest for one command. Subcommand wired in main.rs with --tag / --n / --per-child-netns / --daemon-url / --daemon-token options. Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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
1 participant
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
New subcommand that runs 10 checks against host forkd-readiness and surfaces fix hints. Designed to compress the "I ran `forkd fork` and it errored mysteriously" loop into one command.
Checks:
Each check emits PASS / WARN / FAIL / SKIP with detail and a one-line fix hint on non-pass.
Smoke test on dev box (live)
Also verified the FAIL+hint path by running without `FORKD_TOKEN` — daemon check returns:
```
✗ daemon http://127.0.0.1:8889 HTTP 401
→ set FORKD_TOKEN to match the daemon's --token-file
```
Files
Follow-up
`forkd bench` (quick latency probe: spawn + exec + branch timing) is queued as the next CLI utility. Same shape, separate PR.
🤖 Generated with Claude Code