> For AI agents: the complete documentation index is available at /en/llms.txt, the full documentation bundle is available at /en/llms-full.txt.

# Host a plugin and expert market

When the machine that runs Octop cannot reach `octop.cloud` or `download.octop.cloud`, host both catalogs on your own network. Octop reads two JSON lists, then downloads each archive from that item's `download_url`. You do not need to run the public portal.

The skill market is a separate service. See [Skill market](/en/guide/guides/skill-market.md).

## How Octop loads the catalog

```text
Open Plugin market or Expert market
        │
        ▼
Octop process   GET {OCTOP_PORTAL_ORIGIN}/api/market/plugins
                GET {OCTOP_PORTAL_ORIGIN}/api/market/experts
        │
        │  On success, cache data.items for 30 seconds
        ▼
You click Install
        │
        ▼
Octop process   GET that item's download_url
                (scheme, host, and port must match OCTOP_MARKET_REMOTE_ORIGIN)
```

Both lists are full snapshots. Octop does not send query parameters. Expert search and scene filters run locally, so each expert item must already include `content` and `quick_prompts`. The detail view reads that same cache. Octop does not request `/{id}`.

Requests are unauthenticated. Put the market on a private network. Octop does not send a token.

One catalog response must be at most **1 MiB** and return within **8 seconds**. Octop sends `Accept: application/json` and `User-Agent: Octop`. `success` must be the JSON boolean `true`. `data.items` must be an array. Entries that are not objects are dropped. An HTTP error, a timeout, an empty portal origin, or any `success` value other than `true` marks the catalog unavailable. **Plugin market** and **Expert market** then show that the catalog is temporarily unavailable.

Octop caches a successful response for 30 seconds. After you edit the JSON, wait or restart Octop, then refresh the page.

## Point Octop at your market

Set these variables on the machine that runs `octop run`, then restart the process. Write them in `~/.octop/env`, which the service loads at startup, or in a systemd `Environment=` line.

```bash
OCTOP_PORTAL_ORIGIN=http://market.internal:9000
OCTOP_MARKET_REMOTE_ORIGIN=http://market.internal:9000
```

| Variable                     | Meaning                                                                                                                                             |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OCTOP_PORTAL_ORIGIN`        | Catalog origin: scheme, host, and port only. Do not add a path. The default is `https://octop.cloud`. An empty string turns the remote catalog off. |
| `OCTOP_MARKET_REMOTE_ORIGIN` | Archive origin, also scheme, host, and port only. The default is `https://download.octop.cloud` when the variable is unset or cannot be parsed.     |

The catalog and the archives can live on the same host, so the two values can match. The scheme, host, and port of each `download_url` must match `OCTOP_MARKET_REMOTE_ORIGIN`. When the variable includes a port, the URL must use that port. When it omits the port, Octop uses the default port for the scheme. The path and query string are unrestricted.

One way to lay out static archives:

```text
/octop/market/plugins/{id}/{version}/{id}-{version}.zip
/octop/market/experts/{slug}/{version}/{slug}-{version}.zip
```

Do not point icons at the public internet. The browser loads a plugin card's `icon` itself. When an expert `icon_url` is an `http` or `https` image, the Octop process downloads it while creating the expert. If that download fails, creation continues without the image. Use an address your network can open, or set `icon_name`.

## HTTP API

Octop calls only the two list operations below. Archive bytes come from `download_url`.

```yaml
openapi: 3.0.3
info:
  title: Octop private plugin and expert market
  version: "1"
  description: >
    Catalog read by the Octop server. Octop calls only the two list
    operations. Archive bytes are fetched from download_url.
servers:
  - url: http://market.internal:9000
paths:
  /api/market/plugins:
    get:
      operationId: listMarketPlugins
      summary: Full plugin catalog
      responses:
        "200":
          description: Catalog envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PluginCatalog"
  /api/market/experts:
    get:
      operationId: listMarketExperts
      summary: Full expert catalog
      responses:
        "200":
          description: Catalog envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExpertCatalog"
components:
  schemas:
    Localized:
      oneOf:
        - type: string
        - type: object
          properties:
            zh: { type: string }
            en: { type: string }
    PluginCatalog:
      type: object
      required: [success, data]
      properties:
        success: { type: boolean, enum: [true] }
        data:
          type: object
          required: [items]
          properties:
            items:
              type: array
              items: { $ref: "#/components/schemas/Plugin" }
    ExpertCatalog:
      type: object
      required: [success, data]
      properties:
        success: { type: boolean, enum: [true] }
        data:
          type: object
          required: [items]
          properties:
            items:
              type: array
              items: { $ref: "#/components/schemas/Expert" }
    Plugin:
      type: object
      required: [id, version, download_url]
      properties:
        id: { type: string, pattern: "^[A-Za-z0-9][A-Za-z0-9._-]{0,80}$" }
        version: { type: string }
        name: { $ref: "#/components/schemas/Localized" }
        description: { $ref: "#/components/schemas/Localized" }
        kind: { type: string, default: tool }
        icon: { type: string, description: "Emoji, or an http(s) URL the browser can load" }
        group: { type: string }
        requires:
          type: array
          items: { type: string }
        download_url: { type: string, format: uri }
        updated_at: { type: string, description: "ISO-8601. Octop sorts newer stamps first." }
    Expert:
      type: object
      required: [slug, download_url]
      properties:
        id: { type: string }
        slug: { type: string, pattern: "^[A-Za-z0-9][A-Za-z0-9._-]{0,80}$" }
        label: { $ref: "#/components/schemas/Localized" }
        description: { $ref: "#/components/schemas/Localized" }
        scene: { type: string }
        sub_scene: { type: string }
        icon_url: { type: string, description: "http(s) raster image, or omit and use icon_name" }
        icon_name: { type: string }
        color: { type: string }
        skill_slugs:
          type: array
          items: { type: string }
        skill_count: { type: integer }
        content: { $ref: "#/components/schemas/Localized" }
        quick_prompts:
          type: array
          items:
            type: object
            properties:
              title: { $ref: "#/components/schemas/Localized" }
              description: { $ref: "#/components/schemas/Localized" }
              prompt: { $ref: "#/components/schemas/Localized" }
              color: { type: string }
              icon_name: { type: string }
        task_examples:
          type: object
          properties:
            zh: { type: array, items: { type: string } }
            en: { type: array, items: { type: string } }
        download_url: { type: string, format: uri }
        updated_at: { type: string }
```

`id` and `slug` start with a letter or digit. The rest may be letters, digits, `.`, `_`, or `-`. The whole value is at most 81 characters.

On plugin install, catalog `version` must match `version` in the archive's `plugin.yaml` character for character, and `id` must match too. On expert install, `id` in the archive's `manifest.json` must equal the catalog `slug`.

Use one ISO-8601 form for every `updated_at`, such as `2026-10-26T00:00:00Z`. Octop sorts those strings in reverse order.

Known plugin groups get a translated label. Any other string is filed under **Other**: `lifestyle`, `news`, `finance`, `media`, `fun`, `games`, `tools`, `ops`.

Known expert scenes are translated. Any other string is shown as written: `ecommerce`, `finance`, `content-creation`, `lifestyle`, `marketing`, `mysticism`, `academic`, `legal`, `tech`, `education`, `healthcare`, `hr`, `media`, `design`.

## Minimal deployment

When one origin serves both the catalog and the files, a directory can look like this:

```text
/srv/market/
├── api/market/plugins          # Content-Type: application/json
├── api/market/experts
└── octop/market/
    ├── plugins/weather/0.1.0/weather-0.1.0.zip
    └── experts/ops-engineer/1.0.0/ops-engineer-1.0.0.zip
```

Body of `api/market/plugins`:

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "weather",
        "version": "0.1.0",
        "name": { "zh": "天气", "en": "Weather" },
        "description": { "zh": "查询城市天气", "en": "City weather" },
        "kind": "tool",
        "icon": "☀️",
        "group": "lifestyle",
        "requires": [],
        "download_url": "http://market.internal:9000/octop/market/plugins/weather/0.1.0/weather-0.1.0.zip",
        "updated_at": "2026-10-26T00:00:00Z"
      }
    ]
  }
}
```

Publish that directory with Nginx on any port. `9000` below is only an example. If you change the port, change it in the environment variables and in every `download_url`. `api/market/plugins` and `api/market/experts` have no file extension, so set the JSON type yourself:

```nginx
server {
    listen 9000;
    server_name market.internal;
    root /srv/market;
    location /api/market/ {
        default_type application/json;
    }
}
```

Restart Octop after you set the two variables. **Plugin market** and **Expert market** should list your items. Install requests go only to `market.internal` for the ZIP.

## When the market does not load

| What you see                                                               | What to check                                                                                                                                                                     |
| -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Plugin market or Expert market says the catalog is temporarily unavailable | The list request failed, timed out, or `OCTOP_PORTAL_ORIGIN` is empty. From the Octop machine, `curl` both list URLs and confirm each returns `"success": true` within 8 seconds. |
| The card is there, but install says there is no archive                    | The scheme, host, or port of `download_url` does not match `OCTOP_MARKET_REMOTE_ORIGIN`.                                                                                          |
| The installed version does not match                                       | Catalog `version` differs from `plugin.yaml`, or the expert `slug` differs from `id` in `manifest.json`.                                                                          |
| The page stays the same after you edit the JSON                            | The process cache lasts about 30 seconds. Wait, or restart Octop.                                                                                                                 |
| The icon is blank                                                          | The icon URL still points at the public internet. Use an emoji, `icon_name`, or an address the browser and Octop can both open.                                                   |
