BYOC architecture

BYOC (Bring Your Own Container) lets you deploy custom AI models on the Livepeer Network. The architecture has three layers: your model code wrapped in a FrameProcessor, a StreamServer that handles trickle transport, and a Docker container that the Orchestrator manages.

Three-layer architecture

Gateway
  │ live-video-to-video request
  ▼
Orchestrator (go-livepeer)
  │ routes to container via Docker socket
  ▼
BYOC Container (Docker)
  ├── StreamServer (PyTrickle)
  │     ├── trickle subscribe (input frames)
  │     └── trickle publish (output frames)
  └── FrameProcessor (your model code)
        └── process_frame(VideoFrame) -> VideoFrame

FrameProcessor is the interface you implement. It receives VideoFrame objects (raw pixel data + PTS timestamp) and returns processed VideoFrame objects. Your model logic goes in process_frame(). StreamServer wraps the FrameProcessor and handles trickle transport: subscribing to input frames, calling your processor, and publishing output frames. PyTrickle provides this out of the box. Docker container packages the StreamServer, FrameProcessor, model weights, and dependencies. The Orchestrator manages the container lifecycle via the Docker socket.

Capability registration

The Orchestrator advertises your container’s capabilities to the network through aiModels.json:

{
  "pipeline": "live-video-to-video",
  "model_id": "my-custom-model",
  "price_per_unit": 3000,
  "warm": true,
  "container": "my-registry/my-model:latest",
  "url": "http://localhost:8100"
}

Field	Description
`pipeline`	Always `live-video-to-video` for BYOC containers
`model_id`	Your chosen model identifier; Gateways use this to route requests
`price_per_unit`	Wei per compute unit (Orchestrator-set)
`warm`	Whether the model is pre-loaded in GPU memory
`container`	Docker image reference
`url`	Local HTTP endpoint where the container listens

Gateways discover your capability through the AI Service Registry on-chain and the Orchestrator’s GetOrchestratorInfo response.

Health check contract

Every BYOC container must expose a /health endpoint:

@app.get("/health")
async def health():
    return {"status": "ok"}

The Orchestrator polls /health to determine container readiness. A container that does not return {"status": "ok"} is not advertised to Gateways. The BYOC quickstart walks through building and registering a container. The FrameProcessor reference covers the processing API.

Start here

Concepts

Learn

Build

Guides

Resources

Three-layer architecture

Capability registration

Health check contract

​Three-layer architecture

​Capability registration

​Health check contract

Three-layer architecture

Capability registration

Health check contract