Installing Packages

Marketplace packages install onto your Sophon instance through the Gateway. This page covers the three ways to install — Dashboard, CLI, and agent — plus updates, reviews, and configuration for air-gapped deployments.

How installs work

Your instance never talks to the marketplace registry directly — the Gateway mediates all marketplace traffic. Every install runs the same pipeline:

1. Download — the package archive is streamed to a staging area while its SHA-256 hash is computed.
2. Verify — the hash must match the registry's checksum. This is fail-closed: a missing or mismatched checksum rejects the install before anything is unpacked.
3. Extract — the archive is validated end-to-end before a single file is written (path traversal, oversized entries, and archive-bomb patterns are all rejected).
4. Validate — the package's manifest.json must match the requested name and version.
5. Register — the package moves atomically into ~/.sophon/skills/installed/. Skills register their tools live, with no restart; plugins start as separate local processes (off by default until an admin enables and allowlists them).

Any failure at any step rolls back completely. Each installed package keeps a provenance record of where it came from, which version, and its checksum — that's what powers update checks later.

From the Dashboard

Skills → Marketplace tab: search the catalog, filter by package type, and open a package's detail drawer to see its README, tools, and declared permissions. The install dialog shows a permissions summary — what network hosts and filesystem paths the package requests — before you confirm. See Dashboard.

From the CLI

sophon skills search pdf          # search the catalog
sophon skills marketplace         # browse (alias for search)
sophon skills install pdf-tools   # install a package by name
sophon skills list                # list installed skills
sophon skills update              # check all packages, apply updates
sophon skills uninstall pdf-tools

See CLI commands for the full reference.

From an agent

Agents get two marketplace tools:

• marketplace.search — low risk, executes without approval. Agents can freely look up what's available.
• marketplace.install — always gated behind your approval, no exceptions. The approval preview shows the package's requested permissions and tools. Installs are treated as High risk for skills and Critical for plugins.

So an agent can propose "there's a pdf-tools skill that would handle this — install it?", but only you can say yes. See Approval Gates.

Updates, deprecation, and revocation

The Gateway checks the registry for updates in the background (every 24 hours by default, configurable). The check is check-only — Sophon never auto-installs an update. When a newer version exists you'll see an "update available" badge in the Dashboard and in sophon skills list; applying it is always a human action (Dashboard button or sophon skills update).

• Latest means the highest approved version — there are no separate release channels.
• Deprecated versions stay installable and downloadable, with the publisher's deprecation message shown as a warning.
• Revoked versions are pulled: they can no longer be downloaded or installed.

Reviewing from your instance

To post a package review from the Dashboard, link your marketplace account once: Settings → Marketplace starts a device flow — you get a short user code and a verification URL, confirm in the browser, done. The resulting link token is stored server-side in the credential vault and is never sent to your browser or shared with agents. Linking is optional and only needed for reviews — browsing and installing work without it.

Configuration and air-gapped operation

Marketplace behavior is controlled by the Sophon:Marketplace configuration section:

{
  "Sophon": {
    "Marketplace": {
      "Enabled": true,
      "Url": "https://marketplace.sophon.buildersoft.io",
      "WebUrl": "https://marketplace.sophon.buildersoft.io",
      "ReportInstalls": true,
      "UpdateCheckInterval": "24:00:00",
      "ReviewPromptUseThreshold": 10
    }
  }
}

Each key can also be set as an environment variable (SOPHON__Marketplace__Enabled, SOPHON__Marketplace__Url, …).

• Enabled: false disables all marketplace UI and endpoints — the right setting for air-gapped deployments.
• Url can point at a private registry if your organization hosts its own catalog.
• ReportInstalls controls anonymous install telemetry (an instance identifier, hashed at rest by the registry). Set it to false to opt out.

See Configuration for the full settings reference.

Where to go next

• Sophon Marketplace overview — what's in the catalog
• Publishing Packages — ship your own skill or plugin
• Skills — enabling installed skills per agent