{"owner":"superradcompany","repo":"microsandbox","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# AGENTS.md\n\nThese instructions are only for agents contributing changes to this repository.\nDo not apply them to other repositories or to general agent behavior outside this contribution workflow.\n\n## Scope\n\n- Follow these guidelines when editing code, docs, tests, examples, CI, or release files for microsandbox.\n- Prefer repository conventions over generic agent habits. When unsure, inspect nearby files and match their style.\n- Do not create branches, commit, push, tag, publish, or open pull requests unless the human explicitly asks.\n- Check `git status --short --branch` before making changes. Do not overwrite or revert user work unless explicitly asked.\n\n## Project Map\n\n- `sdk/rust` is the public Rust SDK crate.\n- `crates/cli` contains the `msb` CLI.\n- `crates/runtime` contains VM runtime integration.\n- `crates/filesystem`, `crates/image`, `crates/network`, `crates/db`, `crates/migration`, `crates/metrics`, `crates/metrics-collector`, `crates/protocol`, and `crates/utils` are shared internal crates.\n- `packages/agent-client` and `packages/microsandbox-types` are the shared agent-protocol client and wire-contract type packages, each with Rust and TypeScript implementations.\n- `crates/agentd` is the in-guest agent. It is a workspace member; the musl guest binary that ships in releases is built separately.\n- `sdk/python`, `sdk/node-ts`, and `sdk/go` contain the language SDKs and native bindings.\n- `docs/` contains the documentation site. Keep docs in sync with user-facing behavior.\n- `examples/` contains runnable examples. Add new example projects only when requested or clearly required by the contribution.\n- `mcp/` and `skills/` are submodules related to agent integrations.\n- `vendor/libkrunfw` is a submodule for the kernel firmware library.\n\nRepository layout:\n\n```text\n.\n|-- AGENTS.md\n|-- Cargo.lock\n|-- Cargo.toml\n|-- DEVELOPMENT.md\n|-- Dockerfile.agentd\n|-- justfile\n|-- msb-entitlements.plist\n|-- assets/\n|-- crates/\n|   |-- agentd/\n|   |-- cli/\n|   |-- db/\n|   |-- filesystem/\n|   |-- image/\n|   |-- metrics/\n|   |-- metrics-collector/\n|   |-- migration/\n|   |-- network/\n|   |-- protocol/\n|   |-- runtime/\n|   |-- testing/\n|   |   |-- init/\n|   |   |-- macros/\n|   |   `-- utils/\n|   `-- utils/\n|-- docs/\n|   |-- changelog/\n|   |-- cli/\n|   |-- getting-started/\n|   |-- images/\n|   |-- networking/\n|   |-- observability/\n|   |-- recipes/\n|   |-- sandboxes/\n|   |-- sdk/\n|   `-- security/\n|-- examples/\n|   |-- python/\n|   |-- rust/\n|   `-- typescript/\n|-- mcp/\n|   |-- bin/\n|   |-- src/\n|   `-- package.json\n|-- packages/\n|   |-- agent-client/\n|   `-- microsandbox-types/\n|-- packaging/\n|   `-- docker/\n|-- scripts/\n|   `-- smoke/\n|-- sdk/\n|   |-- go/\n|   |-- node-ts/\n|   |-- rust/\n|   `-- python/\n|-- skills/\n|   `-- microsandbox/\n`-- vendor/\n    `-- libkrunfw/\n```\n\n## Design Principles\n\n- Before making or continuing a change that may introduce a regression or breaking change, stop and alert the human with the likely impact and affected workflows.\n- Keep changes narrowly scoped to the requested behavior. Avoid drive-by refactors, unrelated formatting, or dependency churn.\n- Treat sandbox isolation, host filesystem access, networking, and secret handling as security-sensitive. Validate inputs at boundaries and avoid exposing host paths, credentials, or ambient privileges.\n- For public APIs, keep the Rust SDK, CLI, Python SDK, Node SDK, Go SDK, docs, and examples consistent when they describe the same capability.\n- Prefer explicit errors with useful context over silent fallbacks.\n\n## Rust Layout And Style\n\n- Most Rust crates use `lib/lib.rs` for library code and `bin/main.rs` for binaries. Keep using those paths for new crate entries unless the surrounding crate already does something different.\n- When adding a new library or binary target, declare the path explicitly in `Cargo.toml`:\n\n```toml\n[lib]\npath = \"lib/lib.rs\"\n\n[[bin]]\nname = \"example\"\npath = \"bin/main.rs\"\n```\n\n- Keep crate roots and module roots thin. `lib.rs` and `mod.rs` should declare modules, crate attributes, and exports only. Put implementation in leaf modules such as `sandbox/config.rs`, `policy/types.rs`, or `commands/run.rs`.\n- File order should be:\n  1. Module docs and crate/file attributes, such as `//! ...` and `#![warn(missing_docs)]`.\n  2. `use` imports.\n  3. Sectioned items.\n- Group imports by origin, separated by blank lines: standard library first, external crates second, then `crate::` and `super::` imports.\n- Do not put `use` statements inside sections unless there is a narrow local reason, such as a test module import.\n- Use the exact section delimiter shown below. Do not invent alternate Markdown-style, shorter, or decorative section headers.\n- Include only sections that contain items. Do not add empty sections just to satisfy the full order.\n- Organize Rust files with these section headers, in this order when applicable:\n\n```rust\n//--------------------------------------------------------------------------------------------------\n// Constants\n//--------------------------------------------------------------------------------------------------\n\n//--------------------------------------------------------------------------------------------------\n// Types\n//--------------------------------------------------------------------------------------------------\n\n//--------------------------------------------------------------------------------------------------\n// Methods\n//--------------------------------------------------------------------------------------------------\n\n//--------------------------------------------------------------------------------------------------\n// Trait Implementations\n//--------------------------------------------------------------------------------------------------\n\n//--------------------------------------------------------------------------------------------------\n// Functions\n//--------------------------------------------------------------------------------------------------\n\n//--------------------------------------------------------------------------------------------------\n// Macros\n//--------------------------------------------------------------------------------------------------\n\n//--------------------------------------------------------------------------------------------------\n// Tests\n//--------------------------------------------------------------------------------------------------\n\n//--------------------------------------------------------------------------------------------------\n// Re-Exports\n//--------------------------------------------------------------------------------------------------\n```\n\n- Aggregator files that only expose modules and public items may use `Exports` instead of `Re-Exports` when matching existing files.\n- Use qualified section labels only to split large sections into obvious groups, for example `Types: Identifiers`, `Functions: Handlers`, or `Functions: Helpers`.\n- Do not create a qualified section for one or two items unless the surrounding file already uses that pattern.\n- Put constants and statics under `Constants`.\n- Put `struct`, `enum`, `trait`, and `type` definitions under `Types`.\n- Put inherent `impl Type` blocks under `Methods`, directly after the related type definitions when practical.\n- Put `impl Trait for Type` blocks under `Trait Implementations`.\n- Put free functions under `Functions`. If a free function is only used by one public function, place it later in `Functions: Helpers`.\n- Put macros under `Macros`, not near the call site.\n- Put unit tests under `Tests`, usually as `#[cfg(test)] mod tests`. Keep test-only helpers in the same section.\n- Put public re-exports under `Re-Exports`, or `Exports` in root files that use the existing aggregator style.\n- Keep items in dependency order inside a section: public surface first, private helpers later.\n- Keep docs on public types, fields, methods, functions, and modules. This repo uses `#![warn(missing_docs)]` in public crates, so new public items should explain what they are for.\n- Prefer explicit domain types over loosely typed strings, booleans, or tuples when the value crosses an API or subsystem boundary.\n- During refactors, conflict resolution, bug fixes, and feature work, call out any expected behavior, API, or data-format changes and wait for direction when the risk is material.\n- Use `thiserror` or existing local error patterns for typed errors. Include enough context for callers to understand the failing operation.\n- In async code, avoid holding locks across `.await`. Prefer explicit ownership, short critical sections, and existing Tokio patterns in the surrounding module.\n- Keep feature-gated code close to the feature it gates and use existing `#[cfg(feature = \"...\")]` patterns.\n- Do not add examples under `examples/` unless requested or clearly required. Prefer tests and docs for small usage coverage.\n- Run `cargo fmt` before finalizing Rust changes.\n\n## Development Build Notes\n\n- If you build `msb` to run it locally on macOS, make sure the binary is codesigned with `msb-entitlements.plist`; otherwise VM/runtime failures may be caused by missing entitlements instead of your code change.\n- Prefer `just build` or `just build-msb` when producing a runnable local binary. The macOS recipe rebuilds `msb` and runs:\n\n```bash\ncodesign --entitlements msb-entitlements.plist --force -s - build/msb\n```\n\n- If you bypass `just` and call `cargo build` directly, manually codesign the exact `msb` binary you are going to run before testing sandbox startup, protocol, networking, or filesystem behavior.\n\n## Validation\n\nUse focused checks for the files you touched, then broader checks when the change crosses crate, SDK, CLI, or runtime boundaries.\n\nCommon Rust checks:\n\n```bash\ncargo fmt --all -- --check\ncargo clippy --workspace -- -D warnings\ncargo test --workspace\ncargo build -p microsandbox-cli\n```\n\n`agentd` is a workspace member, so the workspace-wide commands above cover it. The musl guest binary that ships in releases is built separately via `just build-agentd`.\n\nPython SDK checks:\n\n```bash\ncd sdk/python\nuv sync --group dev\nuv run maturin develop --release\nuv run pytest\nuv run ruff check .\n```\n\nNode SDK checks:\n\n```bash\ncd sdk/node-ts\nnpm ci\nnpm run build\nnpm test\nnpm run typecheck\n```\n\nGo SDK checks:\n\n```bash\ncd sdk/go\ngo test -count=1 .\ngo test -tags \"smoke microsandbox_ffi_path\" -count=1 -timeout 2m .\n```\n\nIntegration tests may require Linux with KVM or macOS Apple Silicon support. If a needed check cannot run in the current environment, say exactly which command was skipped and why.\n\nThe full local setup and build loop is documented in `DEVELOPMENT.md`. Use `just setup`, `just build`, and `just install` when you need the full local runtime, `agentd`, or `libkrunfw` artifacts.\n\n## Commits\n\n- Use Conventional Commits for commit titles: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `perf`, `ci`, or `build`.\n- Use a scope when it clarifies the affected area, for example `fix(network): ...` or `docs(sdk): ...`.\n- Keep the subject imperative, lowercase after the colon, no trailing period, and at most 72 characters.\n- Include a commit body for non-trivial changes. Explain what changed and why.\n- Use signed commits: `git commit -S`.\n- Before committing, inspect the actual diff, including new, modified, and deleted files. Do not write a commit message from filenames or previous commit messages alone.\n- If there is nothing to commit, say so rather than creating an empty commit.\n\nExample:\n\n```text\nfix(network): wake smoltcp after accepted host connections\n\nNotify the network loop after accepting a published-port connection so\npending guest traffic can make progress without waiting for another timer.\n```\n\n## Branches And Pull Requests\n\n- You may make local edits while on `main`, but do not commit directly to `main`. Start from the latest `main` when creating a contribution branch.\n- Use short, descriptive, kebab-case branch names. Avoid personal prefixes in shared documentation unless the maintainer asks for one.\n- Before opening a PR, compare against the intended base branch and inspect the actual diff:\n\n```bash\ngit log origin/main..HEAD --oneline\ngit diff origin/main..HEAD --stat\ngit diff origin/main..HEAD --name-status\n```\n\n- PR titles should follow Conventional Commit style and stay under 72 characters.\n- PR descriptions should be plain and accurate:\n  - `## TL;DR`: one or two short sentences.\n  - `## Description`: a flat bullet list of core changes.\n  - `## Test Plan`: concrete commands or observable checks.\n- Do not use emojis in PR titles or descriptions.\n- If a PR description includes an API example, verify every symbol, path, flag, type, field, and signature against the diff before writing it.\n\n## Version And Release Changes\n\n- Do not bump versions, publish packages, create release tags, or modify release automation unless explicitly asked.\n- All released packages share a version. When a version bump is requested, check `Cargo.toml`, `sdk/node-ts/package.json`, `mcp/package.json`, and any other package metadata touched by the release process in `DEVELOPMENT.md`.\n- For release or version PRs, summarize the user-visible changes since the previous version bump and run the relevant dry-run publish checks when practical.\n\n## Documentation And Examples\n\n- Update docs when behavior, configuration, CLI flags, SDK APIs, or examples change.\n- Keep examples realistic and runnable. Do not invent APIs or flags.\n- Prefer editing existing examples over adding new example projects unless the new example is requested or clearly fills a missing user workflow.\n- Documentation should describe current behavior, not future plans, unless the page is explicitly about roadmap work.\n\n## Agent Operating Rules\n\n- Use `rg` or `rg --files` for repository searches.\n- Read the relevant files before editing. Let existing module boundaries guide the change.\n- Make the smallest coherent change that satisfies the request.\n- Avoid destructive git commands such as `git reset --hard` and `git checkout --` unless explicitly requested.\n- Do not edit generated artifacts, lockfiles, or submodule pointers unless the change requires it.\n- If generated files or lockfiles must change, explain why in the final summary.\n- Report what changed, what validation ran, and any checks that were skipped.\n"},"files":{"AGENTS.md":"# AGENTS.md\n\nThese instructions are only for agents contributing changes to this repository.\nDo not apply them to other repositories or to general agent behavior outside this contribution workflow.\n\n## Scope\n\n- Follow these guidelines when editing code, docs, tests, examples, CI, or release files for microsandbox.\n- Prefer repository conventions over generic agent habits. When unsure, inspect nearby files and match their style.\n- Do not create branches, commit, push, tag, publish, or open pull requests unless the human explicitly asks.\n- Check `git status --short --branch` before making changes. Do not overwrite or revert user work unless explicitly asked.\n\n## Project Map\n\n- `sdk/rust` is the public Rust SDK crate.\n- `crates/cli` contains the `msb` CLI.\n- `crates/runtime` contains VM runtime integration.\n- `crates/filesystem`, `crates/image`, `crates/network`, `crates/db`, `crates/migration`, `crates/metrics`, `crates/metrics-collector`, `crates/protocol`, and `crates/utils` are shared internal crates.\n- `packages/agent-client` and `packages/microsandbox-types` are the shared agent-protocol client and wire-contract type packages, each with Rust and TypeScript implementations.\n- `crates/agentd` is the in-guest agent. It is a workspace member; the musl guest binary that ships in releases is built separately.\n- `sdk/python`, `sdk/node-ts`, and `sdk/go` contain the language SDKs and native bindings.\n- `docs/` contains the documentation site. Keep docs in sync with user-facing behavior.\n- `examples/` contains runnable examples. Add new example projects only when requested or clearly required by the contribution.\n- `mcp/` and `skills/` are submodules related to agent integrations.\n- `vendor/libkrunfw` is a submodule for the kernel firmware library.\n\nRepository layout:\n\n```text\n.\n|-- AGENTS.md\n|-- Cargo.lock\n|-- Cargo.toml\n|-- DEVELOPMENT.md\n|-- Dockerfile.agentd\n|-- justfile\n|-- msb-entitlements.plist\n|-- assets/\n|-- crates/\n|   |-- agentd/\n|   |-- cli/\n|   |-- db/\n|   |-- filesystem/\n|   |-- image/\n|   |-- metrics/\n|   |-- metrics-collector/\n|   |-- migration/\n|   |-- network/\n|   |-- protocol/\n|   |-- runtime/\n|   |-- testing/\n|   |   |-- init/\n|   |   |-- macros/\n|   |   `-- utils/\n|   `-- utils/\n|-- docs/\n|   |-- changelog/\n|   |-- cli/\n|   |-- getting-started/\n|   |-- images/\n|   |-- networking/\n|   |-- observability/\n|   |-- recipes/\n|   |-- sandboxes/\n|   |-- sdk/\n|   `-- security/\n|-- examples/\n|   |-- python/\n|   |-- rust/\n|   `-- typescript/\n|-- mcp/\n|   |-- bin/\n|   |-- src/\n|   `-- package.json\n|-- packages/\n|   |-- agent-client/\n|   `-- microsandbox-types/\n|-- packaging/\n|   `-- docker/\n|-- scripts/\n|   `-- smoke/\n|-- sdk/\n|   |-- go/\n|   |-- node-ts/\n|   |-- rust/\n|   `-- python/\n|-- skills/\n|   `-- microsandbox/\n`-- vendor/\n    `-- libkrunfw/\n```\n\n## Design Principles\n\n- Before making or continuing a change that may introduce a regression or breaking change, stop and alert the human with the likely impact and affected workflows.\n- Keep changes narrowly scoped to the requested behavior. Avoid drive-by refactors, unrelated formatting, or dependency churn.\n- Treat sandbox isolation, host filesystem access, networking, and secret handling as security-sensitive. Validate inputs at boundaries and avoid exposing host paths, credentials, or ambient privileges.\n- For public APIs, keep the Rust SDK, CLI, Python SDK, Node SDK, Go SDK, docs, and examples consistent when they describe the same capability.\n- Prefer explicit errors with useful context over silent fallbacks.\n\n## Rust Layout And Style\n\n- Most Rust crates use `lib/lib.rs` for library code and `bin/main.rs` for binaries. Keep using those paths for new crate entries unless the surrounding crate already does something different.\n- When adding a new library or binary target, declare the path explicitly in `Cargo.toml`:\n\n```toml\n[lib]\npath = \"lib/lib.rs\"\n\n[[bin]]\nname = \"example\"\npath = \"bin/main.rs\"\n```\n\n- Keep crate roots and module roots thin. `lib.rs` and `mod.rs` should declare modules, crate attributes, and exports only. Put implementation in leaf modules such as `sandbox/config.rs`, `policy/types.rs`, or `commands/run.rs`.\n- File order should be:\n  1. Module docs and crate/file attributes, such as `//! ...` and `#![warn(missing_docs)]`.\n  2. `use` imports.\n  3. Sectioned items.\n- Group imports by origin, separated by blank lines: standard library first, external crates second, then `crate::` and `super::` imports.\n- Do not put `use` statements inside sections unless there is a narrow local reason, such as a test module import.\n- Use the exact section delimiter shown below. Do not invent alternate Markdown-style, shorter, or decorative section headers.\n- Include only sections that contain items. Do not add empty sections just to satisfy the full order.\n- Organize Rust files with these section headers, in this order when applicable:\n\n```rust\n//--------------------------------------------------------------------------------------------------\n// Constants\n//--------------------------------------------------------------------------------------------------\n\n//--------------------------------------------------------------------------------------------------\n// Types\n//--------------------------------------------------------------------------------------------------\n\n//--------------------------------------------------------------------------------------------------\n// Methods\n//--------------------------------------------------------------------------------------------------\n\n//--------------------------------------------------------------------------------------------------\n// Trait Implementations\n//--------------------------------------------------------------------------------------------------\n\n//--------------------------------------------------------------------------------------------------\n// Functions\n//--------------------------------------------------------------------------------------------------\n\n//--------------------------------------------------------------------------------------------------\n// Macros\n//--------------------------------------------------------------------------------------------------\n\n//--------------------------------------------------------------------------------------------------\n// Tests\n//--------------------------------------------------------------------------------------------------\n\n//--------------------------------------------------------------------------------------------------\n// Re-Exports\n//--------------------------------------------------------------------------------------------------\n```\n\n- Aggregator files that only expose modules and public items may use `Exports` instead of `Re-Exports` when matching existing files.\n- Use qualified section labels only to split large sections into obvious groups, for example `Types: Identifiers`, `Functions: Handlers`, or `Functions: Helpers`.\n- Do not create a qualified section for one or two items unless the surrounding file already uses that pattern.\n- Put constants and statics under `Constants`.\n- Put `struct`, `enum`, `trait`, and `type` definitions under `Types`.\n- Put inherent `impl Type` blocks under `Methods`, directly after the related type definitions when practical.\n- Put `impl Trait for Type` blocks under `Trait Implementations`.\n- Put free functions under `Functions`. If a free function is only used by one public function, place it later in `Functions: Helpers`.\n- Put macros under `Macros`, not near the call site.\n- Put unit tests under `Tests`, usually as `#[cfg(test)] mod tests`. Keep test-only helpers in the same section.\n- Put public re-exports under `Re-Exports`, or `Exports` in root files that use the existing aggregator style.\n- Keep items in dependency order inside a section: public surface first, private helpers later.\n- Keep docs on public types, fields, methods, functions, and modules. This repo uses `#![warn(missing_docs)]` in public crates, so new public items should explain what they are for.\n- Prefer explicit domain types over loosely typed strings, booleans, or tuples when the value crosses an API or subsystem boundary.\n- During refactors, conflict resolution, bug fixes, and feature work, call out any expected behavior, API, or data-format changes and wait for direction when the risk is material.\n- Use `thiserror` or existing local error patterns for typed errors. Include enough context for callers to understand the failing operation.\n- In async code, avoid holding locks across `.await`. Prefer explicit ownership, short critical sections, and existing Tokio patterns in the surrounding module.\n- Keep feature-gated code close to the feature it gates and use existing `#[cfg(feature = \"...\")]` patterns.\n- Do not add examples under `examples/` unless requested or clearly required. Prefer tests and docs for small usage coverage.\n- Run `cargo fmt` before finalizing Rust changes.\n\n## Development Build Notes\n\n- If you build `msb` to run it locally on macOS, make sure the binary is codesigned with `msb-entitlements.plist`; otherwise VM/runtime failures may be caused by missing entitlements instead of your code change.\n- Prefer `just build` or `just build-msb` when producing a runnable local binary. The macOS recipe rebuilds `msb` and runs:\n\n```bash\ncodesign --entitlements msb-entitlements.plist --force -s - build/msb\n```\n\n- If you bypass `just` and call `cargo build` directly, manually codesign the exact `msb` binary you are going to run before testing sandbox startup, protocol, networking, or filesystem behavior.\n\n## Validation\n\nUse focused checks for the files you touched, then broader checks when the change crosses crate, SDK, CLI, or runtime boundaries.\n\nCommon Rust checks:\n\n```bash\ncargo fmt --all -- --check\ncargo clippy --workspace -- -D warnings\ncargo test --workspace\ncargo build -p microsandbox-cli\n```\n\n`agentd` is a workspace member, so the workspace-wide commands above cover it. The musl guest binary that ships in releases is built separately via `just build-agentd`.\n\nPython SDK checks:\n\n```bash\ncd sdk/python\nuv sync --group dev\nuv run maturin develop --release\nuv run pytest\nuv run ruff check .\n```\n\nNode SDK checks:\n\n```bash\ncd sdk/node-ts\nnpm ci\nnpm run build\nnpm test\nnpm run typecheck\n```\n\nGo SDK checks:\n\n```bash\ncd sdk/go\ngo test -count=1 .\ngo test -tags \"smoke microsandbox_ffi_path\" -count=1 -timeout 2m .\n```\n\nIntegration tests may require Linux with KVM or macOS Apple Silicon support. If a needed check cannot run in the current environment, say exactly which command was skipped and why.\n\nThe full local setup and build loop is documented in `DEVELOPMENT.md`. Use `just setup`, `just build`, and `just install` when you need the full local runtime, `agentd`, or `libkrunfw` artifacts.\n\n## Commits\n\n- Use Conventional Commits for commit titles: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `perf`, `ci`, or `build`.\n- Use a scope when it clarifies the affected area, for example `fix(network): ...` or `docs(sdk): ...`.\n- Keep the subject imperative, lowercase after the colon, no trailing period, and at most 72 characters.\n- Include a commit body for non-trivial changes. Explain what changed and why.\n- Use signed commits: `git commit -S`.\n- Before committing, inspect the actual diff, including new, modified, and deleted files. Do not write a commit message from filenames or previous commit messages alone.\n- If there is nothing to commit, say so rather than creating an empty commit.\n\nExample:\n\n```text\nfix(network): wake smoltcp after accepted host connections\n\nNotify the network loop after accepting a published-port connection so\npending guest traffic can make progress without waiting for another timer.\n```\n\n## Branches And Pull Requests\n\n- You may make local edits while on `main`, but do not commit directly to `main`. Start from the latest `main` when creating a contribution branch.\n- Use short, descriptive, kebab-case branch names. Avoid personal prefixes in shared documentation unless the maintainer asks for one.\n- Before opening a PR, compare against the intended base branch and inspect the actual diff:\n\n```bash\ngit log origin/main..HEAD --oneline\ngit diff origin/main..HEAD --stat\ngit diff origin/main..HEAD --name-status\n```\n\n- PR titles should follow Conventional Commit style and stay under 72 characters.\n- PR descriptions should be plain and accurate:\n  - `## TL;DR`: one or two short sentences.\n  - `## Description`: a flat bullet list of core changes.\n  - `## Test Plan`: concrete commands or observable checks.\n- Do not use emojis in PR titles or descriptions.\n- If a PR description includes an API example, verify every symbol, path, flag, type, field, and signature against the diff before writing it.\n\n## Version And Release Changes\n\n- Do not bump versions, publish packages, create release tags, or modify release automation unless explicitly asked.\n- All released packages share a version. When a version bump is requested, check `Cargo.toml`, `sdk/node-ts/package.json`, `mcp/package.json`, and any other package metadata touched by the release process in `DEVELOPMENT.md`.\n- For release or version PRs, summarize the user-visible changes since the previous version bump and run the relevant dry-run publish checks when practical.\n\n## Documentation And Examples\n\n- Update docs when behavior, configuration, CLI flags, SDK APIs, or examples change.\n- Keep examples realistic and runnable. Do not invent APIs or flags.\n- Prefer editing existing examples over adding new example projects unless the new example is requested or clearly fills a missing user workflow.\n- Documentation should describe current behavior, not future plans, unless the page is explicitly about roadmap work.\n\n## Agent Operating Rules\n\n- Use `rg` or `rg --files` for repository searches.\n- Read the relevant files before editing. Let existing module boundaries guide the change.\n- Make the smallest coherent change that satisfies the request.\n- Avoid destructive git commands such as `git reset --hard` and `git checkout --` unless explicitly requested.\n- Do not edit generated artifacts, lockfiles, or submodule pointers unless the change requires it.\n- If generated files or lockfiles must change, explain why in the final summary.\n- Report what changed, what validation ran, and any checks that were skipped.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# AGENTS.md\n\nThese instructions are only for agents contributing changes to this repository.\nDo not apply them to other repositories or to general agent behavior outside this contribution workflow.\n\n## Scope\n\n- Follow these guidelines when editing code, docs, tests, examples, CI, or release files for microsandbox.\n- Prefer repository conventions over generic agent habits. When unsure, inspect nearby files and match their style.\n- Do not create branches, commit, push, tag, publish, or open pull requests unless the human explicitly asks.\n- Check `git status --short --branch` before making changes. Do not overwrite or revert user work unless explicitly asked.\n\n## Project Map\n\n- `sdk/rust` is the public Rust SDK crate.\n- `crates/cli` contains the `msb` CLI.\n- `crates/runtime` contains VM runtime integration.\n- `crates/filesystem`, `crates/image`, `crates/network`, `crates/db`, `crates/migration`, `crates/metrics`, `crates/metrics-collector`, `crates/protocol`, and `crates/utils` are shared internal crates.\n- `packages/agent-client` and `packages/microsandbox-types` are the shared agent-protocol client and wire-contract type packages, each with Rust and TypeScript implementations.\n- `crates/agentd` is the in-guest agent. It is a workspace member; the musl guest binary that ships in releases is built separately.\n- `sdk/python`, `sdk/node-ts`, and `sdk/go` contain the language SDKs and native bindings.\n- `docs/` contains the documentation site. Keep docs in sync with user-facing behavior.\n- `examples/` contains runnable examples. Add new example projects only when requested or clearly required by the contribution.\n- `mcp/` and `skills/` are submodules related to agent integrations.\n- `vendor/libkrunfw` is a submodule for the kernel firmware library.\n\nRepository layout:\n\n```text\n.\n|-- AGENTS.md\n|-- Cargo.lock\n|-- Cargo.toml\n|-- DEVELOPMENT.md\n|-- Dockerfile.agentd\n|-- justfile\n|-- msb-entitlements.plist\n|-- assets/\n|-- crates/\n|   |-- agentd/\n|   |-- cli/\n|   |-- db/\n|   |-- filesystem/\n|   |-- image/\n|   |-- metrics/\n|   |-- metrics-collector/\n|   |-- migration/\n|   |-- network/\n|   |-- protocol/\n|   |-- runtime/\n|   |-- testing/\n|   |   |-- init/\n|   |   |-- macros/\n|   |   `-- utils/\n|   `-- utils/\n|-- docs/\n|   |-- changelog/\n|   |-- cli/\n|   |-- getting-started/\n|   |-- images/\n|   |-- networking/\n|   |-- observability/\n|   |-- recipes/\n|   |-- sandboxes/\n|   |-- sdk/\n|   `-- security/\n|-- examples/\n|   |-- python/\n|   |-- rust/\n|   `-- typescript/\n|-- mcp/\n|   |-- bin/\n|   |-- src/\n|   `-- package.json\n|-- packages/\n|   |-- agent-client/\n|   `-- microsandbox-types/\n|-- packaging/\n|   `-- docker/\n|-- scripts/\n|   `-- smoke/\n|-- sdk/\n|   |-- go/\n|   |-- node-ts/\n|   |-- rust/\n|   `-- python/\n|-- skills/\n|   `-- microsandbox/\n`-- vendor/\n    `-- libkrunfw/\n```\n\n## Design Principles\n\n- Before making or continuing a change that may introduce a regression or breaking change, stop and alert the human with the likely impact and affected workflows.\n- Keep changes narrowly scoped to the requested behavior. Avoid drive-by refactors, unrelated formatting, or dependency churn.\n- Treat sandbox isolation, host filesystem access, networking, and secret handling as security-sensitive. Validate inputs at boundaries and avoid exposing host paths, credentials, or ambient privileges.\n- For public APIs, keep the Rust SDK, CLI, Python SDK, Node SDK, Go SDK, docs, and examples consistent when they describe the same capability.\n- Prefer explicit errors with useful context over silent fallbacks.\n\n## Rust Layout And Style\n\n- Most Rust crates use `lib/lib.rs` for library code and `bin/main.rs` for binaries. Keep using those paths for new crate entries unless the surrounding crate already does something different.\n- When adding a new library or binary target, declare the path explicitly in `Cargo.toml`:\n\n```toml\n[lib]\npath = \"lib/lib.rs\"\n\n[[bin]]\nname = \"example\"\npath = \"bin/main.rs\"\n```\n\n- Keep crate roots and module roots thin. `lib.rs` and `mod.rs` should declare modules, crate attributes, and exports only. Put implementation in leaf modules such as `sandbox/config.rs`, `policy/types.rs`, or `commands/run.rs`.\n- File order should be:\n  1. Module docs and crate/file attributes, such as `//! ...` and `#![warn(missing_docs)]`.\n  2. `use` imports.\n  3. Sectioned items.\n- Group imports by origin, separated by blank lines: standard library first, external crates second, then `crate::` and `super::` imports.\n- Do not put `use` statements inside sections unless there is a narrow local reason, such as a test module import.\n- Use the exact section delimiter shown below. Do not invent alternate Markdown-style, shorter, or decorative section headers.\n- Include only sections that contain items. Do not add empty sections just to satisfy the full order.\n- Organize Rust files with these section headers, in this order when applicable:\n\n```rust\n//--------------------------------------------------------------------------------------------------\n// Constants\n//--------------------------------------------------------------------------------------------------\n\n//--------------------------------------------------------------------------------------------------\n// Types\n//--------------------------------------------------------------------------------------------------\n\n//--------------------------------------------------------------------------------------------------\n// Methods\n//--------------------------------------------------------------------------------------------------\n\n//--------------------------------------------------------------------------------------------------\n// Trait Implementations\n//--------------------------------------------------------------------------------------------------\n\n//--------------------------------------------------------------------------------------------------\n// Functions\n//--------------------------------------------------------------------------------------------------\n\n//--------------------------------------------------------------------------------------------------\n// Macros\n//--------------------------------------------------------------------------------------------------\n\n//--------------------------------------------------------------------------------------------------\n// Tests\n//--------------------------------------------------------------------------------------------------\n\n//--------------------------------------------------------------------------------------------------\n// Re-Exports\n//--------------------------------------------------------------------------------------------------\n```\n\n- Aggregator files that only expose modules and public items may use `Exports` instead of `Re-Exports` when matching existing files.\n- Use qualified section labels only to split large sections into obvious groups, for example `Types: Identifiers`, `Functions: Handlers`, or `Functions: Helpers`.\n- Do not create a qualified section for one or two items unless the surrounding file already uses that pattern.\n- Put constants and statics under `Constants`.\n- Put `struct`, `enum`, `trait`, and `type` definitions under `Types`.\n- Put inherent `impl Type` blocks under `Methods`, directly after the related type definitions when practical.\n- Put `impl Trait for Type` blocks under `Trait Implementations`.\n- Put free functions under `Functions`. If a free function is only used by one public function, place it later in `Functions: Helpers`.\n- Put macros under `Macros`, not near the call site.\n- Put unit tests under `Tests`, usually as `#[cfg(test)] mod tests`. Keep test-only helpers in the same section.\n- Put public re-exports under `Re-Exports`, or `Exports` in root files that use the existing aggregator style.\n- Keep items in dependency order inside a section: public surface first, private helpers later.\n- Keep docs on public types, fields, methods, functions, and modules. This repo uses `#![warn(missing_docs)]` in public crates, so new public items should explain what they are for.\n- Prefer explicit domain types over loosely typed strings, booleans, or tuples when the value crosses an API or subsystem boundary.\n- During refactors, conflict resolution, bug fixes, and feature work, call out any expected behavior, API, or data-format changes and wait for direction when the risk is material.\n- Use `thiserror` or existing local error patterns for typed errors. Include enough context for callers to understand the failing operation.\n- In async code, avoid holding locks across `.await`. Prefer explicit ownership, short critical sections, and existing Tokio patterns in the surrounding module.\n- Keep feature-gated code close to the feature it gates and use existing `#[cfg(feature = \"...\")]` patterns.\n- Do not add examples under `examples/` unless requested or clearly required. Prefer tests and docs for small usage coverage.\n- Run `cargo fmt` before finalizing Rust changes.\n\n## Development Build Notes\n\n- If you build `msb` to run it locally on macOS, make sure the binary is codesigned with `msb-entitlements.plist`; otherwise VM/runtime failures may be caused by missing entitlements instead of your code change.\n- Prefer `just build` or `just build-msb` when producing a runnable local binary. The macOS recipe rebuilds `msb` and runs:\n\n```bash\ncodesign --entitlements msb-entitlements.plist --force -s - build/msb\n```\n\n- If you bypass `just` and call `cargo build` directly, manually codesign the exact `msb` binary you are going to run before testing sandbox startup, protocol, networking, or filesystem behavior.\n\n## Validation\n\nUse focused checks for the files you touched, then broader checks when the change crosses crate, SDK, CLI, or runtime boundaries.\n\nCommon Rust checks:\n\n```bash\ncargo fmt --all -- --check\ncargo clippy --workspace -- -D warnings\ncargo test --workspace\ncargo build -p microsandbox-cli\n```\n\n`agentd` is a workspace member, so the workspace-wide commands above cover it. The musl guest binary that ships in releases is built separately via `just build-agentd`.\n\nPython SDK checks:\n\n```bash\ncd sdk/python\nuv sync --group dev\nuv run maturin develop --release\nuv run pytest\nuv run ruff check .\n```\n\nNode SDK checks:\n\n```bash\ncd sdk/node-ts\nnpm ci\nnpm run build\nnpm test\nnpm run typecheck\n```\n\nGo SDK checks:\n\n```bash\ncd sdk/go\ngo test -count=1 .\ngo test -tags \"smoke microsandbox_ffi_path\" -count=1 -timeout 2m .\n```\n\nIntegration tests may require Linux with KVM or macOS Apple Silicon support. If a needed check cannot run in the current environment, say exactly which command was skipped and why.\n\nThe full local setup and build loop is documented in `DEVELOPMENT.md`. Use `just setup`, `just build`, and `just install` when you need the full local runtime, `agentd`, or `libkrunfw` artifacts.\n\n## Commits\n\n- Use Conventional Commits for commit titles: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `perf`, `ci`, or `build`.\n- Use a scope when it clarifies the affected area, for example `fix(network): ...` or `docs(sdk): ...`.\n- Keep the subject imperative, lowercase after the colon, no trailing period, and at most 72 characters.\n- Include a commit body for non-trivial changes. Explain what changed and why.\n- Use signed commits: `git commit -S`.\n- Before committing, inspect the actual diff, including new, modified, and deleted files. Do not write a commit message from filenames or previous commit messages alone.\n- If there is nothing to commit, say so rather than creating an empty commit.\n\nExample:\n\n```text\nfix(network): wake smoltcp after accepted host connections\n\nNotify the network loop after accepting a published-port connection so\npending guest traffic can make progress without waiting for another timer.\n```\n\n## Branches And Pull Requests\n\n- You may make local edits while on `main`, but do not commit directly to `main`. Start from the latest `main` when creating a contribution branch.\n- Use short, descriptive, kebab-case branch names. Avoid personal prefixes in shared documentation unless the maintainer asks for one.\n- Before opening a PR, compare against the intended base branch and inspect the actual diff:\n\n```bash\ngit log origin/main..HEAD --oneline\ngit diff origin/main..HEAD --stat\ngit diff origin/main..HEAD --name-status\n```\n\n- PR titles should follow Conventional Commit style and stay under 72 characters.\n- PR descriptions should be plain and accurate:\n  - `## TL;DR`: one or two short sentences.\n  - `## Description`: a flat bullet list of core changes.\n  - `## Test Plan`: concrete commands or observable checks.\n- Do not use emojis in PR titles or descriptions.\n- If a PR description includes an API example, verify every symbol, path, flag, type, field, and signature against the diff before writing it.\n\n## Version And Release Changes\n\n- Do not bump versions, publish packages, create release tags, or modify release automation unless explicitly asked.\n- All released packages share a version. When a version bump is requested, check `Cargo.toml`, `sdk/node-ts/package.json`, `mcp/package.json`, and any other package metadata touched by the release process in `DEVELOPMENT.md`.\n- For release or version PRs, summarize the user-visible changes since the previous version bump and run the relevant dry-run publish checks when practical.\n\n## Documentation And Examples\n\n- Update docs when behavior, configuration, CLI flags, SDK APIs, or examples change.\n- Keep examples realistic and runnable. Do not invent APIs or flags.\n- Prefer editing existing examples over adding new example projects unless the new example is requested or clearly fills a missing user workflow.\n- Documentation should describe current behavior, not future plans, unless the page is explicitly about roadmap work.\n\n## Agent Operating Rules\n\n- Use `rg` or `rg --files` for repository searches.\n- Read the relevant files before editing. Let existing module boundaries guide the change.\n- Make the smallest coherent change that satisfies the request.\n- Avoid destructive git commands such as `git reset --hard` and `git checkout --` unless explicitly requested.\n- Do not edit generated artifacts, lockfiles, or submodule pointers unless the change requires it.\n- If generated files or lockfiles must change, explain why in the final summary.\n- Report what changed, what validation ran, and any checks that were skipped.\n","category":"root","tokens":3580}]}