Cocoon networks

Shroud routes inference traffic through one of two Cocoon networks — distinct upstream Cocoon proxies, each with its own model catalog, worker fleet, and pricing config. The network you target determines:

which models are available;
which workers serve your request;
the owned_by value returned by /v1/models;
the pricing applied (each network has its own pricing config).

Network	Status	Notes
`cocoon-classic`	Available	Original Cocoon proxy network.
`cocoon-alpha`	Available	Newer network with separate model fleet and worker schedule.

The default network for unprefixed routes is set per-deployment via the cocoon.default_network config knob. When in doubt, list models on the unprefixed /v1/models endpoint and read each entry's owned_by field.

Targeting a network

Every Cocoon-bound HTTP and WebSocket route is reachable under three shapes:

Shape	Path pattern	Routes to
Default	`/v1/...`	The deployment's `default_network`.
Classic explicit	`/cocoon-classic/v1/...`	Always `cocoon-classic`, regardless of default.
Alpha explicit	`/cocoon-alpha/v1/...`	Always `cocoon-alpha`, regardless of default.

Use the explicit forms when you want stable routing that doesn't follow operator changes to default_network, or when the default network doesn't have the model you need.

The full Cocoon-bound route grid:

Surface	Default	Classic explicit	Alpha explicit
Chat completions	`/v1/chat/completions`	`/cocoon-classic/v1/chat/completions`	`/cocoon-alpha/v1/chat/completions`
List models	`/v1/models`	`/cocoon-classic/v1/models`	`/cocoon-alpha/v1/models`
List workers	`/v1/cocoon/workers`	`/cocoon-classic/v1/cocoon/workers`	`/cocoon-alpha/v1/cocoon/workers`
Cocoon WebSocket	`wss://shroud.us/v1/cocoon/stream`	`wss://shroud.us/cocoon-classic/v1/cocoon/stream`	`wss://shroud.us/cocoon-alpha/v1/cocoon/stream`

Network-agnostic routes (/mcp, /rpc, /v1/midnight/rpc, /.well-known/*) don't have prefixed forms; they're not Cocoon-bound.

Inspecting which networks are enabled

curl https://shroud.us/v1/models \
  -H "Authorization: Bearer shroud_prod_..."

{
  "object": "list",
  "data": [
    {"id": "Qwen/Qwen3-32B", "object": "model", "owned_by": "cocoon-classic"},
    {"id": "Qwen/Qwen3-32B", "object": "model", "owned_by": "cocoon-alpha"}
  ]
}

The same model id appears once per enabled network. To see only one network, use the prefixed form:

curl https://shroud.us/cocoon-classic/v1/models \
  -H "Authorization: Bearer shroud_prod_..."

{
  "object": "list",
  "data": [
    {"id": "Qwen/Qwen3-32B", "object": "model", "owned_by": "cocoon-classic"}
  ]
}

The created field that OpenAI's spec includes is intentionally omitted: Cocoon doesn't have a meaningful creation timestamp for a registered model, so synthesizing one would mislead.

Pinning a network from a client

OpenAI-compatible clients

Pin by setting base_url to a network-prefixed path:

from openai import OpenAI

# Pin to cocoon-classic regardless of the deployment default.
client = OpenAI(
    api_key="shroud_prod_...",
    base_url="https://shroud.us/cocoon-classic/v1",
)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "shroud_prod_...",
  baseURL: "https://shroud.us/cocoon-classic/v1",
});

Cocoon Go SDK

Override the per-route paths so each call goes to the prefixed endpoint:

client := cocoon.NewClient("wss://shroud.us",
    cocoon.WithAPIKey("shroud_prod_..."),
    cocoon.WithStreamPath("/cocoon-classic/v1/cocoon/stream"),
    cocoon.WithModelsPath("/cocoon-classic/v1/models"),
    cocoon.WithWorkersPath("/cocoon-classic/v1/cocoon/workers"),
)

The SDK defaults are the unprefixed routes (/v1/models, /v1/cocoon/stream, /v1/cocoon/workers), which follow the deployment default_network.

Cocoon TypeScript SDK

import { CocoonClient } from "@alphatoncapital/shroud-sdk";

const client = new CocoonClient("wss://shroud.us", {
  apiKey: "shroud_prod_...",
  streamPath: "/cocoon-classic/v1/cocoon/stream",
  modelsPath:  "/cocoon-classic/v1/models",
});

When to pin

If you don't have a reason to care, leave the prefix off and let the deployment default decide. Pin explicitly when:

The model you need isn't on the default network — check /v1/models first.
You're running A/B comparisons across networks.
You need stable routing that won't follow an operator change to default_network.
You're integrating against a partner that requires a specific network.

OpenAI-compatible API — chat completions reference.
Confidential inference — Cocoon architecture.
Go SDK· TypeScript SDK

Last modified: 08 May 2026