Paid Pilot Operator Runbook¶

Date: 2026-05-18 Status: protected-preview operator checklist Linear: TIN-1391

Use this checklist before a TubeBrain paid design-partner call. It consolidates the hosted preview deployment runbook, hosted pilot policy, GStack demo script, paid-discovery offer, and validation commands into one go/no-go artifact.

This is not a public self-serve SaaS launch checklist. The current hosted path is a controlled, bearer-authenticated preview for design partners. Keep the local MCP binary first-class, keep tubebrain.ai as the buyer-facing static surface, and keep the protected API on the approved preview route unless a separate public API launch is approved.

Hosted runtime state is owned by the Blahaj OpenTofu stack tofu/stacks/tubebrain-preview. This repo owns the TubeBrain binaries, GHCR image workflow, API contract, docs, smoke scripts, and legacy/manual recovery manifests. Do not treat tubebrain.ai or deploy/hosted-preview as the normal state owner for the protected preview.

Operator Inputs¶

Fill these in before running commands:

Field	Value
Pilot or call id
Operator
Partner/contact
Date/time
Hosted base URL	`https://tubebrain-preview.taila4c78d.ts.net`
GStack demo URL	`https://www.youtube.com/watch?v=Rzi7oFTzjac&t=2449s`
Live/radio proof URL	`https://ice1.somafm.com/groovesalad-128-mp3`
Local binary version
Hosted image tag
Internal STT image tag
Managed STT mode	`disabled` unless buyer-approved
Package band	Starter / Standard / Expanded
Quote or invoice id

Secrets stay in the operator environment or cluster secret store. Do not write raw bearer tokens, API keys, cookies, signed media URLs, PoTokens, BotGuard internals, or raw audio into evidence files.

Evidence Directory¶

Create one evidence directory for the call:

export PILOT_ID="pilot-YYYYMMDD-name"
export TUBEBRAIN_PILOT_EVIDENCE="target/pilots/$PILOT_ID"
mkdir -p "$TUBEBRAIN_PILOT_EVIDENCE"

Save command output there. If an output could contain sensitive data, save only the redacted or summarized form.

Go/No-Go Summary¶

The pilot is ready only when every required row is green or has a written exception:

Gate	Required evidence	Go condition
Public buyer surface	`curl -I https://tubebrain.ai` and `curl -I https://www.tubebrain.ai`	Both return HTTP 200 or a deliberate redirect
Protected API health	`GET /v1/health`	Returns `status=ok` and `service=tubebrain-hosted`
Main deploy authority	GitHub `main` CI, Docs, and Hosted Image	Latest relevant runs are success
Hosted state authority	Blahaj/OpenTofu and live Kubernetes readback	Preview resources are present, rolled out, labeled `managed-by=blahaj-opentofu`, and STT remains ClusterIP-only
API key posture	Operator confirms account-scoped key record	Key has intended scopes and is not raw-stored in artifacts
Quota posture	`GET /v1/admin/usage`	Limits and remaining counters are visible for the pilot account
STT posture	Hosted plus internal STT workloads healthy	Remote STT is healthy, or live/radio is intentionally out of scope
Managed fallback posture	Env/config review	Disabled unless buyer-approved with explicit hour cap
Billing package	Quote worksheet from `docs/paid-pilot-package.md`	Package band, source count, hosted hours, fallback cap, support limit, and exclusions are accepted
SLO/non-SLA posture	`docs/paid-pilot-slo.md`	Buyer-facing language stays pilot-only, non-SLA, and fallback-aware
COGS/margin posture	`python3 scripts/pilot_cogs_model.py --band <band>`	Quote passes margin gates or has a written scope/price exception
Local MCP demo	`just gstack-demo-script` local packet	Local packet and harness prompt exist
Hosted preview demo	`just gstack-demo-script` with token	Hosted section packet exists or is explicitly skipped
Stream proof	`just hosted-preview-smoke`	Stream start, poll, list, and stop succeed for the selected source
Redaction	Smoke output and error checks	No source URL, token, cookie, PoToken, BotGuard detail, signed media URL, or raw audio leak
Retention boundary	Hosted policy reviewed	Partner accepts no raw-audio archive by default

Preflight: Source And CI Truth¶

Review Paid Pilot Package before quoting the call. The package is the source of truth for price bands, included source count, hosted hours, managed fallback caps, support limits, billing evidence, and exclusions. Review Paid Pilot SLO And Non-SLA Posture before making customer-facing reliability statements, and run the Paid Pilot COGS And Margin Model before quoting scope that changes hosted hours, fallback hours, source count, or support time.

From the tubebrain repo:

git status --short --branch | tee "$TUBEBRAIN_PILOT_EVIDENCE/git-status.txt"
git log -1 --oneline | tee "$TUBEBRAIN_PILOT_EVIDENCE/git-head.txt"
gh pr list --state open --limit 20 | tee "$TUBEBRAIN_PILOT_EVIDENCE/open-prs.txt"
gh issue list --state open --limit 20 | tee "$TUBEBRAIN_PILOT_EVIDENCE/open-gh-issues.txt"
gh run list --branch main --limit 10 | tee "$TUBEBRAIN_PILOT_EVIDENCE/main-runs.txt"

Go conditions:

working tree is clean or every local change is unrelated and documented
no open PR blocks the pilot path
latest relevant main Docs, CI, and Hosted Image runs are successful
Hosted Image failures caused by registry transport, such as GHCR 502, have been rerun successfully before the call

Preflight: DNS And Surfaces¶

Check the static buyer surface and protected API:

curl -fsS -I https://tubebrain.ai \
  | tee "$TUBEBRAIN_PILOT_EVIDENCE/tubebrain-ai.headers"
curl -fsS -I https://www.tubebrain.ai \
  | tee "$TUBEBRAIN_PILOT_EVIDENCE/www-tubebrain-ai.headers"
curl -fsS https://tubebrain-preview.taila4c78d.ts.net/v1/health \
  | tee "$TUBEBRAIN_PILOT_EVIDENCE/hosted-health.json"

If working in the tubebrain.ai site repo, also run its launch DNS check and save the output with the site evidence. Do not treat the static site as proof that the protected API is ready; check both surfaces separately.

Preflight: API Key And Quota¶

Load the pilot bearer token into the shell without printing it:

export TUBEBRAIN_API_KEY
test -n "$TUBEBRAIN_API_KEY"

For local operator tests, prefer TUBEBRAIN_API_KEYS_JSON over a single shared token so each pilot key carries account_id, key_id, scopes, status, and label. Required scopes for the full operator smoke are:

transcript:read
stream:read
stream:write
admin:read

Confirm the cluster secrets exist without printing their values:

kubectl -n tubebrain-preview get secret tubebrain-hosted-api tubebrain-stt-api \
  | tee "$TUBEBRAIN_PILOT_EVIDENCE/secret-presence.txt"

If a token needs to be created or rotated, use the Blahaj OpenTofu secret path described in Hosted Preview Runbook. Do not save secret creation output or raw environment dumps in the pilot evidence directory.

Check the authenticated usage snapshot:

curl -fsS https://tubebrain-preview.taila4c78d.ts.net/v1/admin/usage \
  -H "authorization: Bearer $TUBEBRAIN_API_KEY" \
  | tee "$TUBEBRAIN_PILOT_EVIDENCE/admin-usage.json"

Go conditions:

account_id, api_key_id, and optional key_label match the intended pilot
quota limits match the pilot package
remaining counters are sufficient for the call
recent events do not contain raw source URLs or token material

Preflight: Hosted And STT Workloads¶

On the honey Kubernetes context:

kubectl config current-context \
  | tee "$TUBEBRAIN_PILOT_EVIDENCE/kube-context.txt"
kubectl -n tubebrain-preview get deploy,svc,ingress,networkpolicy \
  | tee "$TUBEBRAIN_PILOT_EVIDENCE/kube-objects.txt"
kubectl -n tubebrain-preview rollout status deployment/tubebrain-hosted \
  | tee "$TUBEBRAIN_PILOT_EVIDENCE/hosted-rollout.txt"
kubectl -n tubebrain-preview rollout status deployment/tubebrain-stt \
  | tee "$TUBEBRAIN_PILOT_EVIDENCE/stt-rollout.txt"

Confirm Blahaj/OpenTofu ownership and the internal STT boundary:

kubectl -n tubebrain-preview get deploy tubebrain-hosted \
  -o jsonpath='{.metadata.labels.app\.kubernetes\.io/managed-by}{"\n"}' \
  | tee "$TUBEBRAIN_PILOT_EVIDENCE/hosted-managed-by.txt"
kubectl -n tubebrain-preview get ingress tubebrain-preview \
  -o jsonpath='{.metadata.annotations.tailscale\.com/proxy-class}{"\n"}' \
  | tee "$TUBEBRAIN_PILOT_EVIDENCE/tailscale-proxy-class.txt"
kubectl -n tubebrain-preview get svc tubebrain-stt \
  -o jsonpath='{.spec.type}{"\n"}' \
  | tee "$TUBEBRAIN_PILOT_EVIDENCE/stt-service-type.txt"
kubectl -n tubebrain-preview get pvc tubebrain-whisper-model-cache \
  -o jsonpath='{.status.phase}{"\n"}' \
  | tee "$TUBEBRAIN_PILOT_EVIDENCE/stt-model-cache-pvc.txt"

If rollout state or ownership labels drift, plan and apply from tinyland-inc/blahaj, not from the tubebrain.ai static site repo. The deploy/hosted-preview manifests in this repo are manual recovery references, not the default paid-pilot state authority.

Confirm remote STT wiring without printing secret values:

kubectl -n tubebrain-preview exec deployment/tubebrain-hosted -- \
  sh -c 'printf "TUBEBRAIN_STT_BACKEND=%s\nTUBEBRAIN_REMOTE_STT_URL=%s\n" "$TUBEBRAIN_STT_BACKEND" "$TUBEBRAIN_REMOTE_STT_URL"' \
  | tee "$TUBEBRAIN_PILOT_EVIDENCE/hosted-stt-env.txt"

Go conditions:

hosted and STT deployments are available
hosted resources are Blahaj/OpenTofu-owned
TUBEBRAIN_STT_BACKEND=remote for live/radio preview traffic
TUBEBRAIN_REMOTE_STT_URL points to the cluster-local STT service
STT service is not publicly exposed
Whisper model cache is present as cache-only state, not customer-data storage

If live/radio is not part of the pilot call, document that scope decision and do not block a deterministic YouTube section demo on STT readiness.

Preflight: Managed STT Fallback¶

Managed third-party STT is disabled by default. It may be enabled only for a buyer-approved pilot proof with an explicit fallback-hour cap.

Check posture:

kubectl -n tubebrain-preview exec deployment/tubebrain-hosted -- \
  sh -c 'printf "TUBEBRAIN_MANAGED_STT_MODE=%s\nTUBEBRAIN_MANAGED_STT_PROVIDER=%s\nTUBEBRAIN_MANAGED_STT_FALLBACK_HOURS=%s\n" "${TUBEBRAIN_MANAGED_STT_MODE:-disabled}" "${TUBEBRAIN_MANAGED_STT_PROVIDER:-}" "${TUBEBRAIN_MANAGED_STT_FALLBACK_HOURS:-0}"' \
  | tee "$TUBEBRAIN_PILOT_EVIDENCE/managed-stt-posture.txt"

Go conditions:

default pilot: mode is disabled
managed pilot: mode is opt-in or forced, provider is approved, and fallback hours are capped
provider calls receive only short audio chunks plus timing/format hints
provider calls do not receive TubeBrain API keys, cookies, signed media URLs, PoTokens, BotGuard details, session IDs, or account metadata

Demo: Local MCP Path¶

Generate the deterministic local packet and harness prompt:

TUBEBRAIN_DEMO_OUT_DIR="$TUBEBRAIN_PILOT_EVIDENCE/gstack" \
TUBEBRAIN_DEMO_USE_NIX=auto \
TUBEBRAIN_DEMO_TIMEOUT_SECS=600 \
just gstack-demo-script \
  | tee "$TUBEBRAIN_PILOT_EVIDENCE/gstack-local-summary.json"

test -s "$TUBEBRAIN_PILOT_EVIDENCE/gstack/local-gstack-demo-packet.json"
test -s "$TUBEBRAIN_PILOT_EVIDENCE/gstack/calling-harness-prompt.txt"

The runner uses nix develop by default when Nix is available and the caller is not already inside a dev shell. Set TUBEBRAIN_DEMO_USE_NIX=false only when the current shell already has the required toolchain. A timeout is a failed evidence run and must not leave a partial packet as acceptance evidence.

Useful knobs:

TUBEBRAIN_DEMO_OUT_DIR: artifact directory
TUBEBRAIN_GSTACK_DEMO_URL: timestamped demo source URL
TUBEBRAIN_HOSTED_PREVIEW_URL: hosted preview base URL
TUBEBRAIN_DEMO_TIMEOUT_SECS: local packet command timeout
TUBEBRAIN_DEMO_USE_NIX: auto, true, or false

Acceptance criteria:

timestamped YouTube URL is accepted
local packet contains a structured transcript section
harness prompt asks the caller model to summarize the GStack section and open referenced articles through the caller's browser permission model
TubeBrain itself does not claim to browse or open tabs

Demo: Hosted Preview Path¶

With TUBEBRAIN_API_KEY set:

TUBEBRAIN_DEMO_OUT_DIR="$TUBEBRAIN_PILOT_EVIDENCE/gstack" \
TUBEBRAIN_HOSTED_PREVIEW_URL="https://tubebrain-preview.taila4c78d.ts.net" \
TUBEBRAIN_DEMO_USE_NIX=auto \
TUBEBRAIN_DEMO_TIMEOUT_SECS=600 \
just gstack-demo-script \
  | tee "$TUBEBRAIN_PILOT_EVIDENCE/gstack-hosted-summary.json"

test -s "$TUBEBRAIN_PILOT_EVIDENCE/gstack/hosted-section-request.json"
test -s "$TUBEBRAIN_PILOT_EVIDENCE/gstack/hosted-section-packet.json"

Acceptance criteria:

hosted response includes request_id
hosted response includes the same section packet shape as the local path
rate-limit headers are present on metered responses
raw token material and source secrets are absent from response bodies

If the hosted token is unavailable, keep the local MCP path as the primary demo and mark the hosted preview as skipped, not failed.

Demo: Stream Proof¶

Run the tailnet preview smoke:

TUBEBRAIN_DEMO_URL="https://www.youtube.com/watch?v=Rzi7oFTzjac&t=2449s" \
TUBEBRAIN_PROOF_RADIO_URL="https://ice1.somafm.com/groovesalad-128-mp3" \
just hosted-preview-smoke \
  | tee "$TUBEBRAIN_PILOT_EVIDENCE/hosted-preview-smoke.txt"

Acceptance criteria:

health returns ok
unauthenticated transcript call returns 401 without leaking source or token material
authenticated transcript section returns the agent section contract
stream start, bounded poll, list, and stop are reachable
stream session ownership and post-restart limits are described accurately: sessions are in-memory, account-scoped, and sticky to the active worker

Use the stream proof as a short buyer proof unless the exact source has been smoked before the call. The deterministic GStack section path remains the primary demo anchor.

Redaction And Retention Checks¶

Before the call, review:

Operator acceptance criteria:

public responses may include request IDs, stable error codes, source kind, stream health, cursors, buffer metadata, and sanitized diagnostics
public responses must not include raw API keys, bearer tokens, cookies, signed media URL path/query values, PoTokens, BotGuard details, or raw audio
usage events may include account/key IDs, endpoint, source kind, outcome, status, duration, stream/STT timing, retry count, estimated cost, and public error code
usage events must not store raw source URLs or replayable source material
raw audio is not persisted by default
live buffers are active-session operational state, not a product archive

Incident And Fallback Paths¶

STT Unavailable¶

Symptoms:

poll returns degraded stream health
stream diagnostics mention STT unavailable or remote STT failure
deployment/tubebrain-stt is not available

Actions:

Keep the deterministic YouTube section demo as the primary path.
Run kubectl -n tubebrain-preview rollout status deployment/tubebrain-stt.
If the STT deployment is broken, either rollback STT or mark live/radio out of scope for the call.
Do not enable managed STT fallback unless the buyer explicitly approved it and the fallback-hour cap is configured.

YouTube Source Blocked¶

Symptoms:

stable source or resolver error from transcript or stream endpoints
YouTube live HLS segment fetches fail
PoToken or player challenge diagnostics appear in sanitized logs

Actions:

Retry once with the deterministic GStack URL if the failing source is a different buyer source.
If the GStack URL fails, switch to local MCP proof if available and record the hosted source failure as an incident.
Use a known public radio stream for stream proof if the pilot does not require YouTube Live.
Do not expose PoToken values, BotGuard internals, signed Googlevideo URLs, or cookies to the buyer.

Quota Exceeded¶

Symptoms:

HTTP 429
error code rate_limited
x-ratelimit-remaining: 0

Actions:

Save the redacted response headers and body.
Check GET /v1/admin/usage for the authenticated account.
If this is expected pilot usage, raise the static cap before the call and document the exception.
If this is unexpected, keep the cap and narrow the demo scope.

Malformed Source Input¶

Symptoms:

HTTP 400
error code invalid_request
missing timestamp for section extraction

Actions:

Confirm the URL and timestamp shape.
For the GStack demo, use https://www.youtube.com/watch?v=Rzi7oFTzjac&t=2449s.
For hosted section calls, include either at_s or a YouTube timestamp.
Treat malformed buyer inputs as product feedback; do not hand-edit hidden state to make the demo pass.

Customer-Facing Acceptance Criteria¶

Use these statements in the call only if the matching evidence exists:

Surface	Acceptance statement
Local MCP	"The local TubeBrain path can produce a structured section packet from the timestamped GStack URL."
Hosted preview	"The protected hosted preview can produce the same section packet behind bearer-token auth."
Stream proof	"The preview can start, poll, list, and stop an HTTP audio stream session for this selected source."
Structured output	"The output is JSON with stable request/session IDs, transcript segments, cursors, health, and an agent contract."
Browser action boundary	"The caller harness decides whether to open browser tabs; TubeBrain only provides structured media context."
Retention	"Raw audio is not persisted by default, and sensitive source/token material is not stored in usage events."
Current limits	"This is a protected design-partner preview, not public self-serve SaaS. Multi-replica stream durability, billing database, and self-serve account management are follow-up work."

Closeout¶

After the call:

Move the evidence directory out of target/ only if it has been reviewed for secrets.
Attach a redacted summary to the relevant Linear issue or customer note.
Record whether the partner should continue with local MCP only, hosted preview, or a custom integration.
File follow-up issues for source failures, missing payload fields, quota changes, or acceptance gaps.