Skip to content
Last updated

Self-Hosting Best Practices

Patterns for running a licensed Bria model in production. The examples use RMBG 2.0; the same shape applies to Fibo 2 and any other self-hosted model.

The Big Picture: Treat the Model as a Long-Lived Service

A self-hosted model is a service you start once and keep warm, not a function you call cold. Think in four stages:

  1. Start — setup() downloads the weights (first run) and loads the model onto the GPU.
  2. Warm up — one throwaway inference so the first real request isn't the slow one.
  3. Serve — reuse the pipeline for every request.
  4. Stop — cleanup() on shutdown to free the GPU.
setup() is the expensive step

setup() downloads weights and loads the model to the GPU. Run it once at startup and reuse the pipeline — never call it per request.

import os
from remove_bg import RemoveBG, RemoveBGConfig, RemoveBGInput

# Start: once at import/startup.
_pipe = RemoveBG(config=RemoveBGConfig(compile_model=False, api_token=os.environ["BRIA_API_TOKEN"]))
_pipe.setup()
# Warm up.
_pipe.execute([RemoveBGInput(image="https://bria-test-images.s3.us-east-1.amazonaws.com/strawberry.jpg")])

def remove_background(image):
    # Serve: reuses the already-loaded model.
    return _pipe.execute([RemoveBGInput(image=image)])[0].image

# Stop: _pipe.cleanup() on shutdown.
Q: Why does loading once matter so much?

Loading the model is seconds-to-minutes of GPU work, and the weights are large (Fibo 2 is about 26 GB). A service that calls setup() per request re-pays that cost every time and can exhaust GPU memory. Load once, hold the pipeline, and reuse execute().

Weights and Startup

Weights download once into BRIA_HOME (default ~/.bria/models) and are reused on later runs. Persist that directory so a restart or a new container doesn't re-download them.

docker run --gpus all \
  -e BRIA_API_TOKEN \
  -v bria-weights:/root/.bria \
  your-image
Q: How do I avoid re-downloading 26 GB on every deploy?

Mount a persistent volume at ~/.bria (as above), or bake the weights into your image after a first setup(). For many replicas, point them all at the same cached weights — a shared read-only volume works well.

Q: How do I make the first request fast?

The first inference after setup() is slower (CUDA graphs, caches warming). Run one throwaway call at startup, as in the service example above, so a real user never hits the cold path.

Licensing and Reliability

The model checks your entitlement when it starts. A cancelled or ended license makes setup() raise LicenseError; a card retry (past_due) stays active.

from common.outpost import LicenseError

try:
    _pipe.setup()
except LicenseError as e:
    # e.url links to the Licenses tab. Page a human and stop.
    raise RuntimeError(f"Self-hosted license problem: {e}. Renew at {e.url}") from e
A restart applies a renewal

A long-running process keeps serving after a license lapses until its next restart — so a restart is also how you apply a renewal. Keep a model restart in your runbook.

Q: Should I auto-retry on a license error?

No. A LicenseError won't clear by retrying — it needs the license renewed on the Licenses tab. Alert instead of looping, and surface e.url so whoever responds lands on the right page.

Versions and Secrets

Q: Should I pin the package version?

Install a floor during setup (remove_bg>=0.5.0), but pin an exact version in production and upgrade deliberately — a new package can change behavior. Model-version upgrades are sold separately from package updates, so pinning also keeps the model version stable.

pip install "remove_bg==0.5.0" --extra-index-url "<registry-url-from-the-console>"
Q: How do I handle BRIA_API_TOKEN safely?

Pass it as an environment variable or secret at runtime — never bake it into an image, commit it, or log it. Rotate keys on the API keys page; any active key of the organization works. In a Dockerfile, use a build-time ARG only to install the package (see the RMBG manual install), and provide the token at runtime for the model itself.

Networking and Attribution

Self-hosted models keep your images local, but the process still talks to Bria.

Q: What outbound access does a self-hosted model need?

On a restricted network, allow outbound HTTPS to:

  • the Bria Engine (engine.prod.bria-api.com) — license checks and the registry credential exchange
  • AWS CodeArtifact and Bria's weights CDN — installing the package and downloading weights
  • the attribution endpoint — the per-run vector that keeps outputs licensed
  • for Fibo 2 only, Google Vertex AI — prompt expansion runs on your own Vertex project
Keep attribution on

Every generation sends a small, irreversible attribution vector to Bria — never your images. It is what keeps your outputs covered by Bria's licensing terms, and what records your usage. Don't disable it.

Usage and Scaling

Q: How do I keep an eye on usage and overage?

Self-hosted runs show in Usage & billing in the Console, tagged as self-hosted, and count against your plan. Calls above the plan are billed, never blocked — watch the trend and upgrade (Starter → Scale) before overage adds up.

Q: How do I run multiple replicas?

Give each replica its own GPU and let each load the model once at startup. Point them all at a shared weights cache (a read-only ~/.bria volume, or weights baked into the image) so only the first download pays the full cost.

Overview

Fibo 2