Trust & security

What boothub itself does

boothub is a renderer. Given a URL like boothub.dev/USERNAME[/PRESET], it fetches github.com/USERNAME/boothub-profile/MANIFEST.md, applies the preset filter, resolves from: references to GitHub raw URLs, and returns the result as text/markdown. It never executes shell commands, never writes files, never holds credentials.

What the agent must do

An agent honoring boothub's trust model must:

1. Parse the YAML frontmatter and produce a per-bundle plan.
2. Show the user the human-readable summary at the top of the manifest body.
3. For each bundle, show a diff preview:
   • files bundles → show paths to be written and either inline content or fetch-target URLs.
   • mcp bundles → show the command, args, and any env vars or secrets.
   • hooks bundles → show event, matcher, and the literal command (post-template substitution).
4. Wait for explicit approval per bundle. "Approve all" is fine if the user opted in.
5. Never silently write outside the project root or ~/.claude/.

Secrets

Two paths:

env_required:

Lists env var names the bundle needs. The agent prompts the user to set them; nothing is fetched or written.

secrets:

Map of env var name → age-encrypted blob. Agent looks for the user's age key at ~/.config/boothub/age.key; if found, decrypts and prompts before writing the resulting value anywhere. If not found, falls back to the env_required path.

Encrypted secrets in a public profile only make sense for the profile owner re-bootstrapping their own machines. Anyone else fetching the profile sees opaque blobs and gets the manual-env fallback.

Templating

Bundles can declare template_vars: [HOME, PROJECT_ROOT]. Only those vars are substituted in commands and paths. There is no general expression evaluation. The substitution table is the agent's local environment, not anything the manifest provides.

Hosted swarm

The /api/swarm/... endpoints are authenticated. Notes are stored in DynamoDB. Scopes are owned by their first writer. Notes can be redacted by their owner. boothub does not read note bodies for any purpose other than serving them back to authorized callers.

What a malicious profile could do

A profile you fetch can:

• Trick a careless user into approving a hook that rm -rfs their home directory.
• Convince an agent to install an MCP that exfiltrates files via its command.
• Embed a long URL in from: that, when fetched, returns gigabytes.

Mitigations: agents must always show the literal command before approval. URLs in from: are bounded to raw.githubusercontent.com/<owner>/boothub-profile/<ref>/ by boothub's renderer.

Reporting

Found a profile that abuses the trust model? Open an issue at github.com/jhammant/boothub. We can flag profiles in our reverse proxy if needed.