샌드박싱, 승인 시스템, 클린 환경을 포함한 보안 에이전트 레이어의 초기 설치 과정을 안내합니다.
- GitHub 스타
- 145
- 파일
- 7
- 마지막 커밋
- 2026년 11월 12일
- 라이선스
- Apache-2.0
- 허용된 도구
- —
isolated-setup-install skill은 무엇을 하나요?
isolated-setup-install은(는) agent skill입니다. 샌드박싱, 승인 시스템, 클린 환경을 포함한 보안 에이전트 레이어의 초기 설치 과정을 안내합니다.
skill의 SKILL.md에서 생성된 요약입니다.
isolated-setup-install skill 정보
이 SKILL은 Claude Code, Codex, Antigravity, Pi 또는 Goose를 사용하는 개발자가 샌드박싱 및 승인 시스템과 같은 보안 에이전트 레이어를 설정할 수 있도록 지원합니다. 처음 설치하는 사용자나 기존 설정이 없는 새로운 클론 및 신규 장비에서 작업하는 사용자를 위한 대화형 온램프(on-ramp) 역할을 합니다. 이 SKILL은 sudo를 실행하거나 쉘 rc 파일을 자동으로 수정하지 않고도 클린 환경과 보안 구성을 구축할 수 있도록 단계별 가이드를 제공합니다.
사용자가 새로운 세션에서 보안 설정을 요청할 때 에이전트가 이 SKILL을 로드해야 합니다. 환경이 보안 요구 사항을 충족하는지 확인하기 위해 로컬 설정 파일, 프로젝트별 설정 및 프레임워크 제공 스크립트에 의존합니다. 프로세스에는 에이전트 하네스 버전을 최소 요구 버전과 대조하여 확인하고 샌드박스 허용 목록을 관리하는 작업이 포함됩니다. 보안 유지를 위해 이 SKILL은 권한 상승 명령을 직접 실행하는 대신 사용자가 터미널에 복사하여 붙여넣을 수 있는 정확한 명령어를 제공합니다.
agent가 수행할 수 있는 작업
- 1최초 보안 에이전트 설치새로운 에이전트 환경을 위한 샌드박싱 및 승인 레이어의 초기 설정을 안내합니다.
- 2샌드박스 파일 시스템 액세스 구성샌드박스가 프로젝트 파일을 읽을 수 있도록 프로젝트 루트를 로컬 설정에 절대 경로로 추가합니다.
- 3기존 보안 설정 확인현재 설치 상태가 올바른지, 그리고 프로젝트 핀(pin)에 따라 최신 상태인지 확인합니다.
- 4구성 드리프트(drift) 처리로컬 머신 락(lock)과 커밋된 프로젝트 핀 사이의 불일치를 감지하여 필요한 업데이트를 제안합니다.
skill의 SKILL.md를 기반으로 작성되었습니다. 모든 사용 사례는 해당 문서의 인용구와 대조 확인되었습니다.
isolated-setup-install skill 설치 방법
각 명령은 skill 폴더를 클라이언트의 skills 디렉터리에 복사합니다. 클라이언트를 재시작하거나 새 세션을 시작하여 로드하세요.플러그인에 isolated-setup-install skill 설치
/plugin marketplace add apache/magpie /plugin install magpie-setup@apache-magpie
Claude Code에 isolated-setup-install skill 설치
~/.claude/skills/isolated-setup-install/SKILL.md
$ npx degit apache/magpie/plugins/magpie-setup/skills/isolated-setup-install ~/.claude/skills/isolated-setup-installClaude Code (project)에 isolated-setup-install skill 설치
.claude/skills/isolated-setup-install/SKILL.md
$ npx degit apache/magpie/plugins/magpie-setup/skills/isolated-setup-install .claude/skills/isolated-setup-installCodex에 isolated-setup-install skill 설치
~/.agents/skills/isolated-setup-install/SKILL.md
$ npx degit apache/magpie/plugins/magpie-setup/skills/isolated-setup-install ~/.agents/skills/isolated-setup-installGemini CLI에 isolated-setup-install skill 설치
~/.gemini/skills/isolated-setup-install/SKILL.md
$ npx degit apache/magpie/plugins/magpie-setup/skills/isolated-setup-install ~/.gemini/skills/isolated-setup-installClaude.ai에 isolated-setup-install skill 설치
npx degit apache/magpie/plugins/magpie-setup/skills/isolated-setup-install isolated-setup-install && zip -r isolated-setup-install.zip isolated-setup-install # claude.ai → Customize → Skills → + → Create skill → Upload a skill → isolated-setup-install.zip
자동 검사
2026년 11월 14일에 실행됨전체 보고서 →자동 검사를 통과했습니다. 보안 감사는 아닙니다. 에이전트가 실행하기 전에 스크립트를 읽어 보세요. 검사 방식 · 점수를 높이기 위해 수정할 항목
- 소스 저장소 연결 및 접근 가능apache/magpie/plugins/magpie-setup/skills/isolated-setup-install is public and reachablegithub.com/apache/magpie/tree/HEAD/plugins/magpie-setup/skil ↗통과
- 오픈 소스 라이선스 (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗통과
- 최근 1년 내 커밋 또는 릴리스Last commit 2026-11-12github.com/apache/magpie/commits ↗통과
- 스크립트에 다운로드 후 실행이나 자격 증명 탈취가 없음1 script read; no download-and-run, remote eval, base64 execution or credential upload통과
- SKILL.md에 숨겨진 지침 없음No override phrases, safeguard switches, credential requests or hidden charactersgithub.com/apache/magpie/blob/HEAD/plugins/magpie-setup/skil ↗통과
- 사전 허용 도구가 제한됨No pre-approved tools; the agent asks before using onegithub.com/apache/magpie/blob/HEAD/plugins/magpie-setup/skil ↗통과
- SKILL.md가 Agent Skills 형식을 따름the description does not say when to use the skillgithub.com/apache/magpie/blob/HEAD/plugins/magpie-setup/skil ↗결함 발견
SKILL.md
GitHub에서 보기setup-isolated-setup-install
Runtime routing (run before the Claude-specific procedure)
Use the operator's explicitly requested runtime when supplied; otherwise use the active session's runtime. An installed executable or configuration directory alone does not select a runtime. For the routing below, treat that selection as the active harness.
Determine the active harness from the session metadata and executable.
When it is Codex, Antigravity, Pi, Goose or Copilot CLI, follow that harness's paragraph in runtime-routing.md.
When the harness is Claude Code, continue below. If the harness cannot be determined from the session or executable, stop and report that; never guess and never prompt.
This skill is the on-ramp for adopters who do not yet have the
secure setup running. It is a thin walkthrough wrapper around the
canonical install path documented in
docs/setup/secure-agent-setup.md. The
authoritative content lives there; this skill exists so an adopter
can say "set up the secure agent setup" in a fresh session and
land in the right step-by-step flow without first reading the
document.
Adopter overrides
Before running its default behaviour, this skill consults
setup-isolated-setup-install.md in the personal layer
(.apache-magpie-local/ when the project adopted Magpie, falling back to the main checkout's in a linked worktree,
or <git-common-dir>/apache-magpie/ when Magpie is only installed; applied first, wins on conflict) and
.apache-magpie-overrides/setup-isolated-setup-install.md (committed, project-wide)
in the adopter repo, if present, and applies any agent-readable overrides it finds.
See docs/setup/agentic-overrides.md for the contract.
Hard rule: agents NEVER modify the snapshot under <adopter-repo>/.apache-magpie/.
Local modifications go in the override file; framework changes go via PR to apache/magpie.
Snapshot drift
Also at the top of every run, this skill compares the
gitignored .apache-magpie.local.lock (per-machine
fetch) against the committed .apache-magpie.lock
(the project pin). On mismatch the skill surfaces the
gap and proposes
setup update.
The proposal is non-blocking — the user may defer if
they want to run with the local snapshot for now. See
docs/setup/install-recipes.md § Subsequent runs and drift detection
for the full flow.
Drift severity:
- method or URL differ → ✗ full re-install needed.
- ref differs (project bumped tag, or
git-branchlocal is behind upstream tip) → ⚠ sync needed. svn-zipSHA-512 mismatches the committed anchor → ✗ security-flagged; investigate before upgrading.
Golden rules
- Do not auto-run privilege-elevating commands. Anything that
needs
sudo(apt / dnf installs, system-wide writes) is printed for the user to copy-paste into their own terminal. The skill never invokessudoitself. - Do not edit shell rc files without approval.
~/.bashrc/~/.zshrcmodifications (sourcingagent-iso.sh, the optionalalias claude='claude-iso') are surfaced as the exact line to add; the user pastes it themselves. The skill confirms the rc file path with the user first; it does not assume. - Do not overwrite an existing settings file silently. If the
user already has a project
.claude/settings.jsonor a user-scope~/.claude/settings.json, the skill diffs the desired merge against the existing file and asks for explicit approval before writing. The merge carries the framework'spermissions.allowset (the read-only reads:ghreads, the vetted-ops read dispatcher, archive / mailbox / roster MCP reads, registryWebFetchhosts) alongsidedenyandask— leaving it out makes every skill read prompt. Only read-only entries belong inallow. Re-installs / partial-state recoveries are common — the skill must not blow away an unrelated pre-existing hook orpermissions.askrule. The desired merge includes the agent-guardhooks.PreToolUseentry (matcherBash, command running the user-scope~/.claude/scripts/agent-guard.py) — the deterministic guard fromtools/agent-guard. Install the script as~/.claude/scripts/agent-guard.pyand populate~/.claude/scripts/guards.d/from both the engine's bundledguards.d/*.pyand every skill-ownedskills/*/guards/*.py(so skill-owned guards likemention/mark-readyare active), alongside the other user-scope scripts (Step P); wire thePreToolUseentry once, and preserve any pre-existinghooksentries. - Stop on the first failure. If a step fails (manifest read fails, framework path wrong, an existing file conflicts in a way the user has not yet decided about), stop and report. Do not push past a failure to the next step.
Up-front confirmations
Before walking any install step, confirm with the user:
- OS / distro. macOS, Ubuntu / Debian (apt), Fedora / RHEL (dnf), or Arch / NixOS / other. macOS skips bubblewrap + socat (Seatbelt is built-in); Linux installs both per the distro shortcut.
- Framework checkout path. The path to the user's local
magpieclone. Required to readtools/agent-isolation/pinned-versions.toml,.claude/settings.json, and thetools/agent-isolation/*.shscripts. If the user does not have a clone, walk them throughgit clonefirst. - Fresh install or re-install. For a re-install on a partial
existing state, the skill must enumerate the existing wiring
(project settings.json, user settings.json, hooks dir, the
agent-guard
hooks.PreToolUseentry +~/.claude/scripts/agent-guard.py, shell rc) before any merge so the user knows what is being preserved vs replaced. - Sync repo (optional). Whether the user maintains a
private dotfile-style
~/.claude-configrepo per Syncing user-scope config across machines. If yes, the skill installs user-scope scripts as symlinks into~/.claude-config/scripts/rather thancp-ing into~/.claude/scripts/— the symlink approach is what makes sync push the upgrades to other machines automatically. Exceptcontainer-gateway-hook.sh, which is always a plain copy owned by the user: the managed-settings dispatcher that runs it refuses a symlink, whose target could be swapped after the checks. A symlink already in its place is replaced by a copy (rmthe link first — acponto it would write through it into the sync repo), andsetup-isolated-setup-updatereports the copy when it drifts from the framework's.
Walk-through
Follow the canonical step list at docs/setup/secure-agent-setup.md → Adopter setup → Via a Claude Code prompt. Each step in that list maps 1:1 to a step in this skill. Do not re-write the list here — read the doc, follow it, and surface each sub-step with the user. The doc names are the source of truth; the skill is the runner.
For the verification step at the end, hand off to the
setup-isolated-setup-verify skill rather than re-walking the checklist
inline.
Agent harness — install @latest, enforce the floor
claude-code is not pinned to an exact version. Install it with
npm install -g --no-save @anthropic-ai/claude-code@latest (the
command in the doc's install list) — latest always carries the newest
permission-rule / sandbox / prompt-injection fixes. The manifest's
[tools.claude-code] table in
pinned-versions.toml
declares a min_version floor, not a pin. Because this install is
driven from Claude Code, apply the same hard gate
setup-isolated-setup-verify check 5 applies: read the running
version (command claude --version, which skips an
alias claude=claude-iso) and, if it is below min_version,
hard-fail — stop the install, tell the operator to upgrade to
@latest, and have them re-run. The secure setup must not be stood up
on a below-floor runtime.
Step P — Project-root coverage in the sandbox allowlists
The harness drops the literal . when it pre-resolves
sandbox.filesystem.allowRead: ["."], so a session in a fresh clone can
write to the project root but not read from it. The fix is to add the root
as an absolute path to the project-local settings.local.json.
This step asks one question first — per-project or whole-user scope — and the whole-user answer overrides git's hook lookup for every repository on the machine, so it carries a disclosure the operator has to acknowledge.
Full procedure, both scopes and both whole-user flavours:
step-p-sandbox-allowlists.md.
Step V — The vetted-ops split and exclusion
Only applies when the adopter routes forge operations through the
vetted-ops dispatcher — i.e. the repo has
.apache-magpie-overrides/tools/vetted-ops/config.toml, the maintainer
keeps a personal one (<personal layer>/tools/vetted-ops/config.toml,
for a project that has not adopted Magpie), or the operator asks for the
dispatcher to be wired now. If neither is
true, skip this step, report it as n/a, and continue with the
next step: a missing policy is never a blocker for this install.
Do not create a policy the project has not asked for.
Only with the sandbox on. The allow rules and sandbox exclusions
below are a permission bypass: they let the dispatcher run without a
prompt, and outside the sandbox. They are safe only because the sandbox
confines everything else. If the sandbox is not enabled for this
session (Step P declined, or sandbox.enabled is not true in the
scope being wired), skip this step, say so, and leave every vetted
operation behind its normal prompt.
Full procedure, including Step V.1 (read-only vetted ops never prompt):
step-v-vetted-ops.md.
Step R — The adversarial-review exclusion
Only applies when the magpie-adversarial-review plugin is installed. If it
is not, skip this step and say so.
Full procedure: step-r-adversarial-review.md.
Step W — Working directories for the read block
Where the vetted-ops dispatcher is used, Step V.1 already requires
permissions.blockReadsOutsideWorkingDirectories to be off, and these
entries cannot stand in for that: they do not stop the vetted-op-read
prompt. They remain useful for the agent's own reads of the scratch root
where the block is on for other reasons.
Nothing extra to write: the sandbox-add-project-root.sh run in Step P also
adds /tmp/claude-<uid>, resolved, to permissions.additionalDirectories of
each worktree's project-local settings.local.json. Under
permissions.blockReadsOutsideWorkingDirectories the skills read it on every
run; without the entry each read prompts, and a bulk sync multiplies that by
its gatherer agents. The script also removes $HOME/.claude/magpie where an
earlier version added it.
After Step P, show the operator the resulting additionalDirectories list and
check three things:
-
Never
~/.claude/magpie. If any scope lists$HOME/.claude/magpieor a parent of it, propose removing it. A working directory is writable to sandboxed Bash, and the vetted-ops commands run from that checkout outside the sandbox./add-dirhas the same effect for a session. -
No glob and no
~. If the operator already has an entry such as/tmp/claude-*in any scope, say it does nothing: the setting matches literal paths only, so the glob is listed but never matched. -
Nothing per-host in a synced or committed file. If the operator put the paths in a user-scope
~/.claude/settings.jsonthat is synced across machines, or in the committed project settings, suggest moving them: they name this host's uid.
Rationale and the rules in full:
docs/setup/secure-agent-setup.md → Working directories under the read-outside-working-directories block.
Step U — Host-only uv state
The excluded uvx / uv run commands, MCP servers launched with uv, hooks
that call python3 and the operator's own terminal all run uv-managed code
outside the sandbox. None of it may come from a directory a sandboxed command
can write:
-
~/.local/share/uvis read-only to the sandbox. No scope may list it, or a parent of it, inallowWriteoradditionalDirectories. The Step P helper removes the write an earlier version added; propose removing any other by hand. -
The host gets its own uv cache. Read
~/.config/uv/uv.toml. Unless it sets acache-dirthat is absolute and, symlinks resolved, outside every directory a sandboxed command can write (everyallowWriteandadditionalDirectoriesentry in any scope, every project root, and the roots the sandbox writes without a grant (/tmp,/private/tmp,/var/folders,/private/var/folders,$TMPDIR)), stage it withcache-dir = "<resolved $HOME>/.local/share/uv-host/cache"added, keeping every other setting, and give the operator the copy command:Edit(~/.config/uv/**)keeps the agent from writing it. Never~(uv does not expand it there) and never a relative path. -
The sandbox cannot read that file.
permissions.denycarriesRead(~/.config/uv/uv.toml)andEdit(~/.config/uv/**)(both in the framework's.claude/settings.json, so Step 2's copy brings them). Sandboxed uv then keeps its default, writable cache. -
Sandboxed prek gets its own home. The
enventry is needed only where a repository uses prek (aprek.toml,.pre-commit-config.yamlor.pre-commit-config.yml, or a hook that runs it: detection); the deny is always kept, since the default home is per-user. The settings carry"env": {"PREK_HOME": "~/.cache/prek-sandbox"}andpermissions.denycarriesEdit(~/.cache/prek/**)(both in the framework's.claude/settings.json): a terminal's git hooks run prek outside the sandbox from~/.cache/prek. The whole-user dispatcher (Step P) gives hooks that Claude Code runs outside the sandbox a host-only home and cache root too; if a repository sets its owncore.hooksPath, propose unsetting it so the dispatcher runs there.
Then hand the operator the reinstall commands from the doc to run in a
terminal: interpreters and tools the sandbox could write before may already
have been changed. Rationale and commands:
docs/setup/secure-agent-setup.md → Host-only uv state.
Step T — Local agent settings
The committed .claude/settings.json is only the shared floor; the rest
of a working setup is personal and goes in .claude/settings.local.json.
Build and hand over that file exactly as
setup update → Reconcile the local agent settings
does: the MCP tools for families installed here but not adopted by the
project and, only when this project is the Magpie framework checkout,
its template (tools/agent-isolation/claude-settings.local.template.json).
Never stage that template into another project: it would widen that
project's sandbox beyond what its maintainers configured. An agent
cannot write that file, so stage it and give the user the copy command.
ASF network fragment selection: Follow
setup update → ASF network fragment selection
when building the proposed local settings. Select the reviewed ASF
fragment only for an explicitly declared ASF project. Preserve the
existing staged-copy and user-approval process. Never install ASF
network grants in user-scope settings or the shared gateway baseline.
Steps K, L, M and B — optional extras
None of these is needed for a working install. Walk the one the operator
asks for: a hardware security key (K), the container gateway (L), the
eval-harness exclusion (M), or the exclusion for the third-party
roborev CLI (B) — offer B
unprompted when command -v roborev finds it.
Procedures: optional-steps.md.
After the install lands
Tell the operator what to look for in the footer, and what each state means. This is the one piece of the install they will see on every render afterwards, so a wrong reading here persists:
| Tag | Means |
|---|---|
[sandbox] green |
sandboxed, and still prompting per command |
[sandbox-auto] yellow |
sandboxed, not prompting per command — auto-allow; wider blast radius, which is why it is not green |
[NO SANDBOX] bold red |
not sandboxed; the state this install exists to make impossible to miss |
Captures of each are in What a session looks like; point the operator there rather than describing the colours twice.
Two things to say explicitly, because both are counter-intuitive:
- The tag reads the settings files, not the running process. A CLI flag that disables sandboxing mid-session is not visible here. Pair it with the bypass-warn hook, which fires per call.
- Yellow is not a warning that something is broken. Auto-allow is a deliberate, common choice; the colour distinguishes two postures rather than flagging a fault.
Suggest two follow-up routines the user can wire later:
setup-isolated-setup-verify— re-run after every Claude Code upgrade or settings-file edit, to confirm denials still fire as expected. The "did a denial silently turn into an allow?" signal is exactly what this skill exists for.setup-isolated-setup-update— periodic check for framework updates, pinned-tool upgrade candidates, and drift between the installed user-scope copies and the framework's source-of-truth. The pre-flight of every skill proposes it for them once the install is recorded (below): after an upgrade that changes the secure-setup files, and weekly otherwise.
Record the install so that pre-flight knows the isolated setup is used on this machine and what it was installed against:
PYTHONPATH="$HOME/.cache/apache-magpie/preflight" \
python3 -P -m setup_preflight.isolated record-update
It writes the isolated_setup block of the personal layer's
reconciled.json (<git-common-dir>/apache-magpie/ when the project has
not adopted Magpie, .apache-magpie-local/ when it has) and nothing
else. Skip it when the command cannot find setup_preflight — say that
/magpie-setup:setup config installs the checker, and that the reminders start
once it is there.
Check that the vetted-ops plugin is installed. magpie-vetted-ops
is part of the baseline: the family skills run their forge operations
through its dispatcher, and Step V's permission rules point at it.
If the harness's plugin listing lacks it, propose
claude plugin install magpie-vetted-ops@apache-magpie
(codex plugin add magpie-vetted-ops@apache-magpie on Codex) and run it once the operator confirms.
Where the harness has no plugin CLI, print the command instead of running it.
Always propose shared-config sync once the install lands.
Regardless of whether the operator already maintains the
~/.claude-config sync repo, proactively offer to run
setup-shared-config-sync as a follow-up:
- If the
~/.claude-configsync repo is already in place, the skill commits + pushes the local modifications (the user-scope scripts, hooks, and settings this install just wired up) so the other machines pick them up. - If the operator does not yet have
~/.claude-config, thesetup-shared-config-syncskill bootstraps it (clones the default private remote if it exists, or creates a fresh private remote and scaffolds the layout). Mention this so a first-time operator knows the follow-up will set sync up from scratch — the point of proposing it is precisely so the just-installed config does not stay machine-local.
Surface it as an offer for the operator to accept, not an auto-run — the sync skill has its own confirmation gates before it commits or pushes anything.
이 스킬의 파일
7isolated-setup-install skill 질문
Claude Code에 isolated-setup-install skill을 어떻게 설치하나요?
npx degit apache/magpie/plugins/magpie-setup/skills/isolated-setup-install ~/.claude/skills/isolated-setup-install를 실행합니다. Claude Code는 ~/.claude/skills(모든 프로젝트) 또는 .claude/skills(한 프로젝트)에서 skills를 로드하며, 설명이 작업과 일치할 때 skill을 사용합니다.
isolated-setup-install skill을 사용할 수 있는 클라이언트는 무엇인가요?
Agent Skills 형식을 읽는 모든 클라이언트(Claude Code, Codex, Gemini CLI, claude.ai(ZIP으로 업로드))가 사용할 수 있습니다. skill 내 스크립트는 클라이언트가 코드 실행을 허용하는 경우에만 실행됩니다.
쉘 설정 파일을 수정하게 되나요?
사용자의 승인 없이 쉘 rc 파일을 편집하지 않습니다. 추가해야 할 정확한 라인을 보여주고 사용자가 직접 붙여넣도록 요청합니다.
이미 Claude 설정이 구성되어 있으면 어떻게 되나요?
기존 설정을 몰래 덮어쓰지 않습니다. 원하는 병합 내용과 기존 파일 간의 차이점(diff)을 수행한 후, 쓰기 작업을 하기 전에 명시적인 승인을 요청합니다.