Install Card

The Install Card is the plain-text document an LLM agent reads to apply an APAI package. It is served at /packages/{slug}/llms.txt and at the site-wide /llms.txt.

The Install Card serves three install modes uniformly. The mode the agent uses depends on where the agent is running, not on the card itself.

APAI distinguishes install modes by where the install lands, not by whether the LLM "can install software." LLMs install software constantly when they have shell access. The honest split:

2.1 Local-tool install

Lands on the user's machine. The agent has shell access and executes the underlying installer (npm, pip, brew, cargo, gh skill, gemini extensions, the APAI registry, etc.). APAI wraps the install command, adds the Capability Passport, runs the scanner, writes a durable receipt to ~/.apai/receipts/<install_id>.json, and surfaces the rollback command.

Surfaces: Claude Code, Codex, Cursor, Gemini CLI, Aider, GitHub Copilot Workspace, any local CLI agent.

2.2 Cloud-sandbox install

Lands in the LLM provider's session-scoped sandbox. The user does not own the storage; install state evaporates when the session ends. The agent loads the Install Card into the conversation, surfaces the Capability Passport to the user, and applies the package protocol inside the sandbox. The receipt cannot persist outside the session; the agent must inform the user.

Surfaces: ChatGPT code interpreter, Claude.ai code execution, Gemini Workspace tools, Grok with code-execution.

2.3 Remote-connector install

Nothing is fetched to the user's machine. The user adds a URL pointing at a remote MCP server or hosted app. The Capability Passport tells the user what the connector can read, write, access, spend, and expose before they wire it in. Phase 6 ships mcp.apai.run as a hosted gateway with RBAC and audit logging.

Surfaces: Claude.ai custom connectors, xAI Grok remote MCP, ChatGPT Apps SDK, any future MCP-compatible client.

# <Package Name> APAI Package Install Card

Package: <Name>
Slug: <slug>
Version: <semver>
Publisher: <publisher>[ (verified)]
Risk level: low | medium | high | unknown
Type: <type>

Summary:
<one-sentence description>

Long description:
<paragraph>

Supported platforms:
  - <platform>
  ...

Install paths:

  Local-tool install (Claude Code, Codex, Cursor, Gemini CLI, Aider, Local CLI):
    apai install <slug>
    apai passport <slug>
    apai audit <slug>
    apai rollback <slug>
    Lands on the user's machine. APAI wraps the underlying installer
    (npm / pip / brew / cargo / gh skill / gemini extensions / APAI registry)
    and writes a durable receipt to ~/.apai/receipts/<install_id>.json.

  Cloud-sandbox install (ChatGPT code interpreter, Claude.ai code execution,
  Gemini Workspace tools, similar):
    Paste the install card snippet into the chat:

    <install-card snippet>

    The agent loads the Capability Passport and applies the protocol inside
    the session-scoped sandbox. Receipts cannot persist outside the session.

Capability Passport:
  Reads: ...
  Writes: ...
  Accesses: ...
  Spends: ...
  Exposes: ...
  Approvals required: ...

Rollback:
  <human-readable rollback instructions>

Scanner: heuristic-stub-v0 | findings | not-scanned
Findings:
  - <only if status != heuristic-stub-v0>

Hard rules for any agent applying this package:
  - Do not request user secrets or credentials.
  - Do not call paid APIs unless the user has explicitly approved that call.
  - Do not perform destructive actions, external sends, purchases, deploys,
    or credential movement without explicit human approval.
  - Cite the Capability Passport when surfacing the install to the user.
  - Disclose that v0.1 scanner is heuristic-stub-v0, not a full security scan.

Package detail (HTML): https://apai.run/packages/<slug>
Manifest spec: https://apai.run/spec/manifest
Passport spec: https://apai.run/spec/passport

The Install Card MUST be served with Content-Type: text/plain; charset=utf-8. HTML versions live at the package detail page; the /llms.txt route is plain text only.

Recommended cache: public, max-age=300. Install cards may change between package versions; agents should not cache aggressively.

The Install Card is a behavioral contract the agent agrees to follow for the current install. It is not authorization for the model to access additional tools, secrets, or APIs beyond what the user has already enabled. The agent must:

• Surface the Capability Passport to the user before any action that requires approval.
• Honor the "Approvals required" list in the Passport.
• Disclose the scanner status. heuristic-stub-v0 is not certification of safety; it means the v0.1 regex + Unicode check did not flag anything.
• Refuse the install if the underlying installer requires permissions outside the Passport's declared list, and surface the discrepancy to the user.