sbx CLI를 사용하여 AI 코딩 에이전트용 격리된 microVM sandbox의 라이프사이클을 관리합니다.
- GitHub 스타
- 626
- 파일
- 6
- 마지막 커밋
- 2026년 11월 10일
- 라이선스
- Apache-2.0
- 허용된 도구
- —
docker-sandboxes-lifecycle skill은 무엇을 하나요?
docker-sandboxes-lifecycle은(는) agent skill입니다. sbx CLI를 사용하여 AI 코딩 에이전트용 격리된 microVM sandbox의 라이프사이클을 관리합니다.
skill의 SKILL.md에서 생성된 요약입니다.
docker-sandboxes-lifecycle skill 정보
격리된 환경에서 AI 코딩 에이전트를 실행해야 하는 개발자는 이 SKILL을 사용하여 Docker Sandboxes의 전체 라이프사이클을 관리할 수 있습니다. 이 SKILL은 독립적인 sbx CLI를 직접 제어하여 microVM sandboxes를 생성, 실행, 재연결, 중지 및 제거할 수 있는 기능을 제공합니다. 이는 Claude, Gemini 또는 Cursor와 같은 에이전트에게 호스트 머신으로부터의 엄격한 격리를 유지하면서 고유한 filesystem과 network를 제공하려는 사용자에게 필수적입니다.
이 SKILL은 직접적인 bind mount 또는 컨테이너 내부의 프라이빗 Git repository를 생성하는 --clone flag를 통해 에이전트가 로컬 코드와 상호작용하는 방식을 관리합니다. 또한 특정 디렉토리에 대한 실수로 인한 수정을 방지하기 위해 읽기 전용 workspace를 추가할 수 있습니다. 기본적인 라이프사이클 관리를 넘어, 호스트와 sandbox 간의 파일 복사, sbx exec를 통한 임시 명령 실행, 게시된 포트 관리가 가능합니다. 사용자는 특정 시간 필터를 적용한 prune 명령을 사용하여 중지된 sandboxes를 일괄 정리할 수도 있습니다.
agent가 수행할 수 있는 작업
- 1에이전트를 repository로부터 격리AI 에이전트가 호스트 working tree에 직접 쓰는 것을 방지하기 위해 Git repository의 컨테이너 내부 프라이빗 복제본에서 작업할 수 있습니다.
- 2sandbox로 파일 전송로컬 머신과 격리된 microVM 환경 간에 설정 파일이나 로그를 이동합니다.
skill의 SKILL.md를 기반으로 작성되었습니다. 모든 사용 사례는 해당 문서의 인용구와 대조 확인되었습니다.
docker-sandboxes-lifecycle skill 설치 방법
각 명령은 skill 폴더를 클라이언트의 skills 디렉터리에 복사합니다. 클라이언트를 재시작하거나 새 세션을 시작하여 로드하세요.플러그인에 docker-sandboxes-lifecycle skill 설치
/plugin marketplace add docker/skills /plugin install docker-skills@docker
Claude Code에 docker-sandboxes-lifecycle skill 설치
~/.claude/skills/docker-sandboxes-lifecycle/SKILL.md
$ npx degit docker/skills/skills/docker-sandboxes-lifecycle ~/.claude/skills/docker-sandboxes-lifecycleClaude Code (project)에 docker-sandboxes-lifecycle skill 설치
.claude/skills/docker-sandboxes-lifecycle/SKILL.md
$ npx degit docker/skills/skills/docker-sandboxes-lifecycle .claude/skills/docker-sandboxes-lifecycleCodex에 docker-sandboxes-lifecycle skill 설치
~/.agents/skills/docker-sandboxes-lifecycle/SKILL.md
$ npx degit docker/skills/skills/docker-sandboxes-lifecycle ~/.agents/skills/docker-sandboxes-lifecycleGemini CLI에 docker-sandboxes-lifecycle skill 설치
~/.gemini/skills/docker-sandboxes-lifecycle/SKILL.md
$ npx degit docker/skills/skills/docker-sandboxes-lifecycle ~/.gemini/skills/docker-sandboxes-lifecycleClaude.ai에 docker-sandboxes-lifecycle skill 설치
npx degit docker/skills/skills/docker-sandboxes-lifecycle docker-sandboxes-lifecycle && zip -r docker-sandboxes-lifecycle.zip docker-sandboxes-lifecycle # claude.ai → Customize → Skills → + → Create skill → Upload a skill → docker-sandboxes-lifecycle.zip
자동 검사
2026년 11월 15일에 실행됨전체 보고서 →자동 검사를 통과했습니다. 보안 감사는 아닙니다. 에이전트가 실행하기 전에 스크립트를 읽어 보세요. 검사 방식
- 소스 저장소 연결 및 접근 가능docker/skills/skills/docker-sandboxes-lifecycle is public and reachablegithub.com/docker/skills/tree/HEAD/skills/docker-sandboxes-l ↗통과
- 오픈 소스 라이선스 (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗통과
- 최근 1년 내 커밋 또는 릴리스Last commit 2026-11-10github.com/docker/skills/commits ↗통과
- 스크립트에 다운로드 후 실행이나 자격 증명 탈취가 없음No scripts in the skill folder통과
- SKILL.md에 숨겨진 지침 없음No override phrases, safeguard switches, credential requests or hidden charactersgithub.com/docker/skills/blob/HEAD/skills/docker-sandboxes-l ↗통과
- 사전 허용 도구가 제한됨No pre-approved tools; the agent asks before using onegithub.com/docker/skills/blob/HEAD/skills/docker-sandboxes-l ↗통과
- SKILL.md가 Agent Skills 형식을 따름Valid name and description; says when to use it; 238 linesgithub.com/docker/skills/blob/HEAD/skills/docker-sandboxes-l ↗통과
SKILL.md
GitHub에서 보기Docker Sandboxes: Local Lifecycle & Workspace Isolation
Overview
Docker Sandboxes (sbx) runs an AI coding agent inside an isolated microVM with
its own filesystem, network, and Docker daemon. This skill owns the local
sandbox lifecycle — creating, reattaching to, listing, stopping, and removing
sandboxes — and the workspace isolation choice (direct bind mount vs.
--clone). It does not cover network policy, credentials, sbxenv.yaml, or
kit authoring — see Related skills.
When to use this skill
Activate this skill when:
- The user wants to start, reattach to, stop, or remove a local
sbxsandbox. - The user wants an agent to work on a repository without giving it a
writable bind mount of the host working tree (
--clone). - The user wants extra read-only (or write-restricted) workspaces mounted alongside the primary one.
- The user is copying files between host and sandbox, publishing a sandbox
port, or running an ad-hoc command inside a sandbox (
sbx exec). - The user wants to clean up stopped sandboxes (
sbx prune) or remove a specific one (sbx rm), with the destructive consequences understood.
Do not use this skill when
Do not use this skill when:
- The task is running
docker agent run --sandboxor managing itsdocker agent sandboxallowlist — usedocker-agent-run. If the CLI is unclear, establish whether the user runs Docker Agent or standalonesbxbefore choosing commands. - The task is about what a sandbox can reach on the network or which
credentials it uses — use
docker-sandboxes-network-credentials. - The task is authoring or running a declarative
sbxenv.yamlfile — usedocker-sandboxes-env. - The task is authoring, packaging, signing, or composing a kit
spec.yaml— usedocker-sandboxes-kits. - The task is about
sbx --cloud(Docker Cloud Sandboxes) — out of scope for this skill set, which covers the local daemon only.
Core guidance
Creating vs. running
- Use
sbx run AGENT [PATH...]to create-if-needed and attach in one step. Usesbx create AGENT [PATH...]to create without attaching, thensbx run --name SANDBOXto attach later. Pass--detached/-dtosbx runto print the sandbox ID and exit without an interactive session.sbx run shell # create (if needed) and attach, cwd mounted sbx create shell . # create only, cwd mounted, do not attach sbx run --name my-sandbox # reattach later AGENTis a built-in name (claude,codex,cursor,devin,docker-agent,gemini,opencode,shell) or a sandbox kit reference (local directory, ZIP, git, or OCI). A relative local kit reference MUST be an explicit path (./my-kit, a parent-relative.zippath) — a baremy-kitis read as an agent/sandbox name, never a directory beside the cwd.- Omitting the path is not the same for every subcommand.
sbx run claudewith no path mounts the current directory.sbx create claudewith no path mounts nothing at all — the agent then works only in the container's own filesystem. Always pass a path explicitly withsbx createif you intend to give the agent a workspace. - Prefer
--nameto reattach; a bare positional name still works but is deprecated.sbx run --name NAME(agent positional optional, read from the sandbox's own spec) is the recommended form. A baresbx run NAME— a positional that is neither a known agent nor an explicit kit reference — is still accepted as a legacy re-attach shorthand, but prints a deprecation warning ("sbx run NAMEis deprecated; usesbx run --name NAMEinstead") and may be removed in a future release. Always write--nameexplicitly rather than relying on the legacy form.sbx run --name existing-sandbox # reattach, agent read from spec sbx run claude --name existing-sandbox # reattach, verify expected agent
Workspace isolation: bind mount vs. --clone
- Default (bind mount): the workspace path is mounted read/write inside the sandbox at the same path as on the host. The agent can write directly to your working tree.
--clone(creation-time only): the agent runs against a private in-container clone of the host Git repository. The host repo is mounted read-only; the agent's commits land in the in-container clone and are reachable from the host via asandbox-<name>git remote — fetch or pull from it to bring commits back.sbx create --clone --name demo claude . # on the host, later: git fetch sandbox-demo--clonehas real preconditions, checked at creation time, and fails loudly if any is unmet:- an explicit
PATHmust be given (there must be a workspace to clone from); - that path must be inside a Git repository;
- it must NOT be a Git worktree (the in-container clone cannot follow a
worktree's
.gitpointer out to a common dir elsewhere); - its
.gitmust be a real directory, not a file (a submodule or a--separate-git-dirsetup points.gitelsewhere, which the read-only source mount would not include).
- an explicit
--cloneonsbx runwhen reattaching is a no-op ONLY on a sandbox already created in clone mode — it re-validates nothing new and simply keeps running the existing in-container clone. Passing--clonewhile reattaching to a sandbox that was created without it (a plain bind-mounted sandbox) is not a silent no-op: it fails with an error telling you to recreate the sandbox withsbx create --clone .... Neither form can convert an existing sandbox's mode after creation.- Removing or pruning a clone-mode sandbox permanently discards every
commit the agent made that was never fetched back to the host — the
in-container clone lives on the sandbox's own filesystem and is deleted
with it. Before removing a clone-mode sandbox, fetch its work first:
Fetching populates two refspecs: the ordinarygit fetch sandbox-demorefs/remotes/sandbox-demo/*(deleted along with the remote when the sandbox is removed) and a survivor copy atrefs/sandboxes/demo/*(outside the remote namespace, so it is not deleted when the remote goes). Recover a branch from the survivor copy after removal with:git branch <local-name> refs/sandboxes/demo/<branch>sbx rm/sbx pruneprint this warning automatically for any clone-mode sandbox they are about to remove; read it before confirming, don't suppress it with--forceout of habit. - Additional workspaces are extra positional paths after the first. Append
:roto mount one read-only.:roblocks writes, not reads — the sandbox can still read every file under a:romount; it is not a way to hide sensitive content, only to stop the sandbox from modifying it. A read-only argument may name a single file rather than a directory, holding just that one path out of reach for writes inside a workspace the sandbox can otherwise write.
Never mount a secrets/credentials file this way (sbx run claude . /path/to/docs:ro:roor otherwise) — a read-only mount still lets the sandbox (and, through it, the proxy-less agent process) read the secret in the clear. Use the credential store instead; seedocker-sandboxes-network-credentials.
Reattaching, stopping, and removing
sbx lslists sandboxes with agent, status, published ports, and workspace (--json,-q/--quietfor scripting).sbx stop SANDBOX [SANDBOX...]stops without removing; state is retained and the sandbox restarts withsbx run --name.sbx rm [SANDBOX...] [--all] [--force]removes sandboxes, their containers, Git worktrees, state, and sandbox-scoped secrets. This cannot be undone, and for a clone-mode sandbox it discards every unfetched commit (see above). Only use--forcewhen you have already reviewed what will be destroyed and consented — for scripted teardown of resources this session itself created and uniquely named, not as a default habit.sbx prune [--dry-run] [--filter until=VALUE] [--force]removes only stopped sandboxes — a running sandbox is never touched — but this is still a destructive, irreversible bulk removal: every matching stopped sandbox's state, secrets, and (for clone-mode sandboxes) any unfetched commits are gone. Always preview with--dry-runfirst and read the clone-commit warning it prints before removing for real; do not pass--forceas a default.- Current source flag is
--filter until=VALUE, notsince=.VALUEmay be an RFC 3339 timestamp, a Unix timestamp, or a Go duration relative to now (e.g.until=168hkeeps anything stopped within the last week — i.e. prunes what stopped before that point). This is a source-only behavior at the pinned commit that differs from some installed builds: an older installedsbxmay still advertise--filter since=DURATIONas a legacy alias; preferuntil=and treatsince=as legacy-only if your installed--helpoutput does not showuntil=.
sbx prune --dry-run --filter until=168h # after reviewing the dry-run output and any clone-commit warnings: sbx prune --filter until=168h- Current source flag is
Copying files and running ad-hoc commands
sbx cp SRC DSTcopies between host and sandbox; exactly one side must beSANDBOX:PATH. Copying between two sandboxes is not supported.sbx cp ./config.json my-sandbox:/home/agent/ sbx cp my-sandbox:/home/agent/output.log ./sbx exec [flags] SANDBOX COMMAND [ARG...]runs a command in a sandbox (starting it first if stopped); flags mirrordocker exec(-it,-d,-u,-w,-e,--env-file,--privileged).sbx exec -it my-sandbox bash sbx exec -u root my-sandbox apt-get updatesbx ports SANDBOX [--publish SPEC] [--unpublish SPEC]manages published ports after creation;-p/--publishonsbx create/sbx runonly takes effect when the sandbox is created, not on reattach.
Sizing and naming
--cpus(0 = auto: all host CPUs) and--memory/-m(default 50% of host memory, clamped 512 MiB–32 GiB) are create-time-only knobs.--namesets the sandbox name (default<agent>-<workdir>); at least two characters, starting with a letter or number, letters/numbers/hyphens/ periods only, at most 63 ASCII characters, ending in a letter or number;defaultis reserved.
Related skills
-
For
docker agent run --sandboxanddocker agent sandboxcommands, usedocker-agent-run. -
For network egress policy and service/registry credentials, use
docker-sandboxes-network-credentials. -
For declarative, checked-in
sbxenv.yamlenvironments that wrap this same create/run/rm lifecycle, usedocker-sandboxes-env. -
For authoring or composing the kit
spec.yamlanAGENTreference can point to, usedocker-sandboxes-kits.
References
references/sources.md— provenance for every rule above (help captures, source paths, docs URLs).
Assets
- None.
Checks
checks/verification.md— Verification runbook for sandbox lifecycle commands (unexecuted runbook; run manually with an isolated--app-name, never with--forceexcept consented cleanup of the runbook's own uniquely-named test sandboxes).
이 스킬의 파일
6docker-sandboxes-lifecycle skill 질문
Claude Code에 docker-sandboxes-lifecycle skill을 어떻게 설치하나요?
npx degit docker/skills/skills/docker-sandboxes-lifecycle ~/.claude/skills/docker-sandboxes-lifecycle를 실행합니다. Claude Code는 ~/.claude/skills(모든 프로젝트) 또는 .claude/skills(한 프로젝트)에서 skills를 로드하며, 설명이 작업과 일치할 때 skill을 사용합니다.
docker-sandboxes-lifecycle skill을 사용할 수 있는 클라이언트는 무엇인가요?
Agent Skills 형식을 읽는 모든 클라이언트(Claude Code, Codex, Gemini CLI, claude.ai(ZIP으로 업로드))가 사용할 수 있습니다. skill 내 스크립트는 클라이언트가 코드 실행을 허용하는 경우에만 실행됩니다.
호스트 파일에 쓰기 권한을 주지 않고 sandbox에서 에이전트를 실행하려면 어떻게 하나요?
생성 시 --clone flag를 사용하면 컨테이너 내부의 프라이빗 Git repository 복제본을 대상으로 에이전트를 실행할 수 있습니다. 이 경우 호스트 repository는 읽기 전용 상태로 유지됩니다.
sbx run과 sbx create의 차이점은 무엇인가요?
sbx run은 sandbox가 존재하지 않으면 생성한 후 즉시 연결하지만, sbx create는 연결 없이 sandbox만 생성합니다.
clone-mode sandbox를 삭제하면 에이전트가 작업한 내용이 사라지나요?
네, clone-mode sandbox를 삭제하면 호스트로 가져오지 않은 에이전트의 모든 commit이 영구적으로 삭제됩니다.
sandbox에서 디렉토리를 읽기 전용으로 마운트하려면 어떻게 하나요?
workspace path 인자 끝에 ':ro'를 추가합니다.