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