From macOS Sandbox
Test, launch, debug, smoke-test, or validate a macOS .app or .pkg in a disposable local Tart VM via macbox CLI or MCP. Use when the user mentions macbox, macOS sandbox, VM smoke test, guest automation, or isolated app testing.
How this skill is triggered — by the user, by Claude, or both
Slash command
/macos-sandbox:macos-sandboxThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Use macbox when you need to validate a macOS app build in a clean local VM without touching the host.
Use macbox when you need to validate a macOS app build in a clean local VM without touching the host.
.app or .pkgmacos-sequoia-clean)~/.ssh/macbox_id installed in guest admin accountmacboxmacbox doctor --json
macbox status --json
Confirm doctor reports Tart, ssh/scp, SSH identity, and the state directory as OK.
Via MCP: create_sandbox(image="macos-sequoia-clean", headless=True)
Via CLI:
macbox start --image macos-sequoia-clean --name macbox-test-001 --headless --json
Save the returned vm name and run_id.
Upload only .app or .pkg files from explicit local paths.
Via MCP: upload_app(vm_name="macbox-test-001", app_path="/path/to/MyApp.app")
Via CLI:
macbox upload --name macbox-test-001 --path ./dist/MyApp.app --dest /Users/admin/Desktop/MyApp.app --json
Via MCP: run_app_smoke_test(vm_name="macbox-test-001", app_name="MyApp.app", timeout_seconds=120)
Via CLI:
macbox run-app --name macbox-test-001 --app /Users/admin/Desktop/MyApp.app --timeout 120 --json
Inspect JSON data:
launchedcrashedscreenshotlogscrash_reportsmacbox logs --name macbox-test-001 --last 5m --json
macbox screenshot --name macbox-test-001 --json
macbox collect-crashes --name macbox-test-001 --json
Or MCP equivalents: collect_logs, take_screenshot, collect_crashes.
If you need a custom interaction path inside the VM, use the guest-control tools:
exec_in_guestrun_applescript_in_guestrun_jxa_in_guestopen_guest_applist_guest_windowslist_guest_processesFor full GUI and file control inside the VM:
type_text_in_guest, send_keys_in_guest, click_in_guest (keyboard/mouse automation)push_file_to_guest, pull_file_from_guest (move any file in or out of the guest)Keyboard/mouse automation needs Accessibility permission granted in the guest template.
When finished, always clean up:
macbox destroy --name macbox-test-001 --json
Or reset_sandbox / destroy_sandbox via MCP.
Use reset when you need a fresh VM with the same name. Use destroy when you are done with it.
Summarize for the user:
~/.macbox/runs/<run_id>/~/.ssh, .env, keychains, tokens){
"mcpServers": {
"macbox": {
"command": "/absolute/path/to/macbox/.venv/bin/python",
"args": ["/absolute/path/to/macbox/mcp/macbox_mcp.py"]
}
}
}
Copy this file to:
.agents/skills/macos-sandbox/SKILL.md, or~/.agents/skills/macos-sandbox/SKILL.mdSearches MemPalace before answering questions about past work, people, projects, or prior decisions. Returns verbatim stored content instead of guessing from model memory.
Guides Payload CMS config (payload.config.ts), collections, fields, hooks, access control, APIs. Debugs validation errors, security, relationships, queries, transactions, hook behavior.
Implements vector databases with Pinecone, Weaviate, Qdrant, Milvus, pgvector for semantic search, RAG, recommendations, and similarity systems. Optimizes embeddings, indexing, and hybrid search.
npx claudepluginhub robzilla1738/roberts-skills --plugin macos-sandbox