BYOC Overview

How Bring Your Own Compute (BYOC) containers integrate with Livepeer orchestrators: the HTTP contract, capability registration, and payment flow.

---

BYOC (Bring Your Own Compute) is the mechanism for registering custom inference containers with a Livepeer orchestrator. The orchestrator discovers and routes jobs to BYOC containers through the same path as native ai-runner pipelines. Gateways select BYOC containers by their registered pipeline type and model ID via the AI Service Registry on-chain.

BYOC containers implement a small HTTP contract: a /health endpoint for liveness checks, and a pipeline-specific inference endpoint (e.g. /live/video-to-video or /text-to-image). The orchestrator manages the trickle protocol transport, payment tickets, and capability advertisement.

HTTP Contract

Every BYOC container must expose:

For real-time pipelines (live-video-to-video), the container additionally exposes:

Endpoint	Method	Purpose
/api/stream/start	POST	Start a processing session
/api/stream/stop	POST	Stop the active session
/api/stream/update	POST	Receive parameter updates
/api/stream/status	GET	Return session status

PyTrickle’s StreamServer implements all four real-time endpoints automatically. See for the implementation pattern.

Registering with an Orchestrator

BYOC containers are registered in the orchestrator’s aiModels.json file. Each entry maps a pipeline type and model ID to a container URL:

[
  {
    "pipeline": "live-video-to-video",
    "model_id": "comfystream",
    "url": "http://127.0.0.1:8188",
    "price_per_unit": 0,
    "warm": true
  },
  {
    "pipeline": "text-to-image",
    "model_id": "my-custom-diffusion",
    "url": "http://127.0.0.1:9000",
    "price_per_unit": 1000000,
    "warm": true
  }
]

Fields:

Field	Type	Description
pipeline	string	Pipeline type identifier matching the AI worker pipeline names
model_id	string	Model identifier advertised to gateways via the AI Service Registry
url	string	HTTP address of the BYOC container
price_per_unit	integer	Price in wei per unit of compute. 0 disables charging.
warm	boolean	Whether to advertise this as a warm capability on startup

After updating aiModels.json, restart the orchestrator to pick up the new registration.

Network Discovery

Once registered, the orchestrator advertises the BYOC capability to gateways via the AI Service Registry smart contract on Arbitrum One. Gateways query the registry when routing live-video-to-video or batch pipeline jobs.

The capability is advertised as pipeline/model_id, e.g. live-video-to-video/comfystream. Gateways that specify a model_id in their request body will only route to orchestrators advertising that model.

The network capability dashboard at tools.livepeer.cloud/ai/network-capabilities shows which BYOC capabilities are warm across the active set.

Payment Flow

BYOC containers receive the same probabilistic micropayment flow as native ai-runner pipelines. The orchestrator validates payment tickets from the gateway before forwarding jobs to the BYOC container. The BYOC container does not participate in payment logic directly; it receives jobs and returns results.

price_per_unit in aiModels.json sets the price the orchestrator charges the gateway per compute unit. For live-video-to-video, the unit is typically per-frame or per-second depending on orchestrator configuration. For batch pipelines, pricing follows the same per-output-unit model as native pipelines.

The BYOC quickstart walks through the full cycle from FrameProcessor to registered network capability in 25 minutes.

Related Pages

BYOC Architecture

Detailed container lifecycle, pipeline discovery, and the ai-runner integration.

BYOC Production

Deploying BYOC containers at scale: resource management, error handling, monitoring.

ComfyStream as BYOC

Worked example of registering a ComfyStream real-time pipeline as BYOC.

PyTrickle

Python SDK that implements the BYOC real-time container contract.