For AI agents: the complete documentation index is available at /en/llms.txt, the full documentation bundle is available at /en/llms-full.txt, and this page is available as Markdown at /en/guide/guides/private-market.md.
  • English
  • 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.

    How Octop loads the catalog

    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.

    OCTOP_PORTAL_ORIGIN=http://market.internal:9000
    OCTOP_MARKET_REMOTE_ORIGIN=http://market.internal:9000
    VariableMeaning
    OCTOP_PORTAL_ORIGINCatalog 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_ORIGINArchive 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:

    /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.

    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:

    /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:

    {
      "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:

    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 seeWhat to check
    Plugin market or Expert market says the catalog is temporarily unavailableThe 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 archiveThe scheme, host, or port of download_url does not match OCTOP_MARKET_REMOTE_ORIGIN.
    The installed version does not matchCatalog version differs from plugin.yaml, or the expert slug differs from id in manifest.json.
    The page stays the same after you edit the JSONThe process cache lasts about 30 seconds. Wait, or restart Octop.
    The icon is blankThe icon URL still points at the public internet. Use an emoji, icon_name, or an address the browser and Octop can both open.