setup-isolated-setup-doctor

Name: setup-isolated-setup-doctor
Author: apache

68stars52forks

How to install setup-isolated-setup-doctor?

apache/magpie/setup-isolated-setup-doctor

$npx -y skills add apache/magpie --skill setup-isolated-setup-doctor

Installs into the current project.

Summary

Probe the secure-agent setup for in-session functional restrictions that block legitimate workflows. Three live probes — SSH agent / Yubikey reachability, localhost port binding, docker / podman runtime socket — each pointing the user at the matching numbered troubleshooting entr

Files · 1

View on GitHub

SKILL.md

1	<!-- Placeholder convention (see AGENTS.md#placeholder-convention-used-in-skill-files):
2	<project-config> → adopting project's `.apache-magpie/` directory -->
3
4	# setup-isolated-setup-doctor
5
6	The diagnostic layer over the secure agent setup. Complements
7	the existing setup skills:
8
9	- [`setup-isolated-setup-install`](../setup-isolated-setup-install/SKILL.md)
10	installs the secure setup.
11	- [`setup-isolated-setup-verify`](../setup-isolated-setup-verify/SKILL.md)
12	answers "is the secure setup installed* correctly?"* —
13	static checks on settings.json shape, hook wiring, pinned tool
14	versions. Catches drift and missing pieces.
15	- [`setup-isolated-setup-update`](../setup-isolated-setup-update/SKILL.md)
16	surfaces drift against the framework's latest.
17	- `setup-isolated-setup-doctor` (this skill) answers *"are
18	common workflows functionally blocked by the current
19	sandbox?"* — live probes of SSH agent, port binding, docker /
20	podman socket. Catches over-restrictive allowlists.
21
22	Run `verify` first when the install is in question (fresh
23	machine, recent framework upgrade, sandbox-state surprise). Run
24	`doctor` when the install is known good but a workflow fails in
25	a sandbox-shaped way — agent unreachable, socket error, port
26	permission error.
27
28	Every probe maps to a numbered entry in
29	[`docs/setup/sandbox-troubleshooting.md`](../../docs/setup/sandbox-troubleshooting.md);
30	the doctor's job is to identify which entry applies right now,
31	not to re-explain the remediation. If a fail surfaces a failure
32	mode not catalogued there, propose appending a new entry per the
33	catalog's Adding a new entry section.
34
35	## Golden rules
36
37	- Read-only. Each probe runs a small, deterministic,
38	side-effect-free check. The skill never edits any settings
39	file, never runs a command with `dangerouslyDisableSandbox`,
40	never installs anything. If a check fails, surface the failure
41	and point at the catalog entry; do not auto-fix.
42	- Run every probe, even on early failure. Do not stop at the
43	first ✗. The value of the report is in the full picture — a
44	user may have one of three independent restrictions, or all
45	three, and discovering them one re-run at a time is annoying.
46	- Distinguish ✗ (failing) from ⊘ (not applicable). ✗ means
47	the probe ran and the sandbox blocked it. ⊘ means the probe
48	was skipped because the prerequisite is absent (e.g. no
49	`docker` / `podman` on `PATH` → docker probe ⊘, not ✗).
50	- Surface evidence. Each report line names the probe command,
51	the exit code, and the relevant stderr snippet. "Looks
52	blocked" is not a useful report; "ssh-add -l → rc=2 →
53	`Could not open a connection to your authentication agent`" is.
54	- Map each ✗ to a catalog entry. The fail report includes a
55	direct link to the matching section of
56	[`docs/setup/sandbox-troubleshooting.md`](../../docs/setup/sandbox-troubleshooting.md).
57	Do not paraphrase the remediation — the catalog is the single
58	source of truth.
59
60	## The 3 probes
61
62	The current set covers the three failure modes the catalog
63	documents. New probes are added when new entries land in the
64	catalog; the two stay in lock-step.
65
66	### Probe 1 — SSH agent / Yubikey reachable
67
68	Tests whether `ssh-agent` is reachable from inside the sandbox.
69	Failure mode: `SSH_AUTH_SOCK` is passed through `claude-iso`'s
70	env whitelist but the socket file is not in
71	`sandbox.filesystem.allowRead`, so the agent's `ssh` /
72	`git push` subprocesses cannot `connect(2)` to the socket.
73
74	Command:
75
76	```bash
77	if [ -z "$SSH_AUTH_SOCK" ]; then
78	echo "PROBE: ssh-agent → ⊘ (SSH_AUTH_SOCK not set in env)"
79	elif [ ! -S "$SSH_AUTH_SOCK" ]; then
80	echo "PROBE: ssh-agent → ✗ (socket file at SSH_AUTH_SOCK not stat-able from inside sandbox)"
81	echo " SSH_AUTH_SOCK=$SSH_AUTH_SOCK"
82	else
83	ssh-add -l > /tmp/ssh-add.out 2>&1; rc=$?
84	case "$rc" in
85	0) echo "

People who liked this also viewed

6 picks

Type

setup-isolated-setup-doctor

68stars52forks

View on GitHub

How to install setup-isolated-setup-doctor?

apache/magpie/setup-isolated-setup-doctor

$npx -y skills add apache/magpie --skill setup-isolated-setup-doctor

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	<!-- Placeholder convention (see AGENTS.md#placeholder-convention-used-in-skill-files):
2	<project-config> → adopting project's `.apache-magpie/` directory -->
3
4	# setup-isolated-setup-doctor
5
6	The diagnostic layer over the secure agent setup. Complements
7	the existing setup skills:
8
9	- [`setup-isolated-setup-install`](../setup-isolated-setup-install/SKILL.md)
10	installs the secure setup.
11	- [`setup-isolated-setup-verify`](../setup-isolated-setup-verify/SKILL.md)
12	answers "is the secure setup installed* correctly?"* —
13	static checks on settings.json shape, hook wiring, pinned tool
14	versions. Catches drift and missing pieces.
15	- [`setup-isolated-setup-update`](../setup-isolated-setup-update/SKILL.md)
16	surfaces drift against the framework's latest.
17	- `setup-isolated-setup-doctor` (this skill) answers *"are
18	common workflows functionally blocked by the current
19	sandbox?"* — live probes of SSH agent, port binding, docker /
20	podman socket. Catches over-restrictive allowlists.
21
22	Run `verify` first when the install is in question (fresh
23	machine, recent framework upgrade, sandbox-state surprise). Run
24	`doctor` when the install is known good but a workflow fails in
25	a sandbox-shaped way — agent unreachable, socket error, port
26	permission error.
27
28	Every probe maps to a numbered entry in
29	[`docs/setup/sandbox-troubleshooting.md`](../../docs/setup/sandbox-troubleshooting.md);
30	the doctor's job is to identify which entry applies right now,
31	not to re-explain the remediation. If a fail surfaces a failure
32	mode not catalogued there, propose appending a new entry per the
33	catalog's Adding a new entry section.
34
35	## Golden rules
36
37	- Read-only. Each probe runs a small, deterministic,
38	side-effect-free check. The skill never edits any settings
39	file, never runs a command with `dangerouslyDisableSandbox`,
40	never installs anything. If a check fails, surface the failure
41	and point at the catalog entry; do not auto-fix.
42	- Run every probe, even on early failure. Do not stop at the
43	first ✗. The value of the report is in the full picture — a
44	user may have one of three independent restrictions, or all
45	three, and discovering them one re-run at a time is annoying.
46	- Distinguish ✗ (failing) from ⊘ (not applicable). ✗ means
47	the probe ran and the sandbox blocked it. ⊘ means the probe
48	was skipped because the prerequisite is absent (e.g. no
49	`docker` / `podman` on `PATH` → docker probe ⊘, not ✗).
50	- Surface evidence. Each report line names the probe command,
51	the exit code, and the relevant stderr snippet. "Looks
52	blocked" is not a useful report; "ssh-add -l → rc=2 →
53	`Could not open a connection to your authentication agent`" is.
54	- Map each ✗ to a catalog entry. The fail report includes a
55	direct link to the matching section of
56	[`docs/setup/sandbox-troubleshooting.md`](../../docs/setup/sandbox-troubleshooting.md).
57	Do not paraphrase the remediation — the catalog is the single
58	source of truth.
59
60	## The 3 probes
61
62	The current set covers the three failure modes the catalog
63	documents. New probes are added when new entries land in the
64	catalog; the two stay in lock-step.
65
66	### Probe 1 — SSH agent / Yubikey reachable
67
68	Tests whether `ssh-agent` is reachable from inside the sandbox.
69	Failure mode: `SSH_AUTH_SOCK` is passed through `claude-iso`'s
70	env whitelist but the socket file is not in
71	`sandbox.filesystem.allowRead`, so the agent's `ssh` /
72	`git push` subprocesses cannot `connect(2)` to the socket.
73
74	Command:
75
76	```bash
77	if [ -z "$SSH_AUTH_SOCK" ]; then
78	echo "PROBE: ssh-agent → ⊘ (SSH_AUTH_SOCK not set in env)"
79	elif [ ! -S "$SSH_AUTH_SOCK" ]; then
80	echo "PROBE: ssh-agent → ✗ (socket file at SSH_AUTH_SOCK not stat-able from inside sandbox)"
81	echo " SSH_AUTH_SOCK=$SSH_AUTH_SOCK"
82	else
83	ssh-add -l > /tmp/ssh-add.out 2>&1; rc=$?
84	case "$rc" in
85	0) echo "

People who liked this also viewed

6 picks

Type