Build on Tellyport

Launch your first app connection

You configure Tellyport once inside your app. After that, backend changes happen in the console, the CLI, or CI, without changing the app's permanent Tellyport URL.

1. 1
   Add a backend server

   Open Backend servers and enter your current API base URL. No backend yet? Import an OpenAPI spec to mock it.

   Open servers
2. 2
   Create an app route

   Choose proxy for live backend data or custom for your own JSON response.

   Open routes
3. 3
   Create an app connection key

   Create a key for the app or platform. The raw value is shown only once.

   Open keys
4. 4
   Add the SDK

   Pick your platform below, bundle a safe default config, and test against staging.

   View SDKs
5. 5
   Run the risk check and publish

   Review what changes and who is affected before production clients receive it.

   Risk check

One permanent URL, movable infrastructure

Your app keeps one Tellyport address. Tellyport returns the currently published, signed configuration, or serves stable gateway routes that proxy to your backend or return mock responses.

Plans & limits

Plans are based on apps and active devices. Change plans any time under Settings › Plan & billing.

• Active devices are devices seen in the last 30 days (they fetched config, registered, or sent a heartbeat).
• Extra active devices on paid plans cost $8 per 1,000 per month, billed as a separate line item. Paid plans never block new devices.
• On the Free plan, new registrations stop at 500 devices with 402 PLAN_DEVICE_LIMIT. Devices already registered keep receiving config.
• Usage is shown in the console and returned by GET …/billing as usage: { activeDevices, includedDevices, overageUnits, overageAmount }.
• Older plan names map automatically: sandbox → Free, pilot → Starter, fleet → Growth.

Change a backend without updating the app

1. Edit draft
2. Risk check
3. Test staging
4. Publish
5. Monitor

Return your own response and data

Create a route, choose Custom JSON response, select an HTTP status, and enter any valid JSON. Path and query placeholders are resolved per request.

{
  "success": true,
  "profile_id": "{{params.id}}",
  "greeting": "Hello {{query.name}}",
  "data": { "plan": "premium" }
}

Mock a backend from OpenAPI

Your app can ship before its backend exists. Import an OpenAPI document and Tellyport creates a custom (mock) route for each operation. When the real backend is ready, switch each route to proxy.

1. 1
   Preview

   In Routes › Import OpenAPI, paste JSON or YAML. Preview shows the routes that would be created and anything skipped, and never writes.

2. 2
   Apply

   Apply adds the routes to the environment. Response bodies come from example / examples first, otherwise they are synthesized from the schema (types, formats, enums, arrays of two items).

3. 3
   Switch to proxy

   Point routes at a backend server one by one. The gateway path your app calls doesn't change.

// request
{ "spec": "<OpenAPI JSON or YAML string>", "mode": "preview", "prefix": "/" }

// response
{
  "routes": [
    { "method": "GET", "path": "/questions/:id", "mode": "mock", "status": 200,
      "body": { "id": "q_1", "text": "string" }, "source": "example" }
  ],
  "skipped": [ { "method": "GET", "path": "/health", "reason": "Route already exists" } ],
  "applied": 0
}

Fetch signed runtime configuration

Use an app connection key only for bootstrap, gateway, and initial device registration. Never embed operator credentials, service tokens, or the system admin token in an app.

Mobile & web SDKs

Every SDK lives in the repository's sdk/ folder. Each fetches the bootstrap config, verifies its signature, keeps a last-known-good copy, retries with backoff, registers devices, sends heartbeats, polls, and builds gateway URLs.

• Signature check is on by default. The native SDKs verify the signed payload bytes and read the configuration only from them.
• Revoked device tokens recover automatically in Swift, Kotlin, and Flutter: on a 401 the token is dropped and the request retries once with the client key. The JavaScript SDK does not do this yet.
• Kotlin on older Android: built-in Ed25519 needs Android API 33+. On older versions, pass a Bouncy Castle verifier.

TV SDKs

TV apps are the hardest to update, so every major TV platform has a client. Each one keeps a last-known-good config on the device, reports heartbeats, and answers remote diagnostics requests.

• Roku: copy sdk/roku/components/OriginMesh into your channel and include OriginMeshHelpers.brs in the scene. All network and registry work runs on the Task thread; observe its config field. Unset options fall back to the manifest keys originmesh_url, originmesh_project, originmesh_environment, and originmesh_key.
• Tizen and webOS: older TV browsers have no WebCrypto Ed25519. By default the helpers then accept config only over https:// and mark it verifiedBy: "https"; pass verifySignatures: true to require Ed25519.
• Country for the fleet map comes from the TV's locale setting when the edge doesn't provide it.

Your app survives Tellyport downtime

1. 1Live signed configFrom Tellyport, or the edge's last good copy
2. 2Last-known-good cachePreviously verified copy on the device
3. 3Bundled defaultSafe config shipped inside the app

The SDKs support ETag refresh, cache only valid responses, and fall back without making app startup depend on the control plane.

Edge delivery

An optional Cloudflare Worker in edge/worker.js sits in front of /api/v1/bootstrap and /api/v1/signing-key. When the origin answers 5xx/429, times out, or is unreachable, it serves the last good signed response it stored.

• Scoped copies: stored responses are keyed by URL and a hash of the caller's credential, and are only served to a caller presenting the same credential.
• Visible: stale answers carry x-originmesh-edge: stale and a reason; copies older than STALE_MAX_AGE_SECONDS (default 7 days) are never served.
• Deploy: copy edge/wrangler.toml.example, set ORIGIN_URL, optionally bind Workers KV for cross-region copies, then npx wrangler deploy. Full steps in edge/README.md.

Draft first, production second

Every edit goes into a draft. Publishing creates an immutable, signed version, so you can always see history or restore a known configuration.

Release risk check

Before publishing, Tellyport compares the draft with what devices run now and explains the impact in plain language: a level (low, medium, high), a score from 0 to 100, and the checks behind it.

{
  "level": "medium", "score": 48,
  "summary": "The API host changes for every device and 12 devices will be asked to update.",
  "impact": { "devicesTotal": 40, "devicesAffected": 40, "forcedUpdate": 12,
              "byPlatform": [ { "platform": "roku", "devices": 18 } ] },
  "checks": [ { "id": "endpoint_reachable", "status": "pass", "message": "api_base_url responded" } ],
  "changes": [ { "path": "endpoints.api_base_url", "before": "https://api.eu1…", "after": "https://api.eu2…" } ],
  "ai": { "available": false, "text": null }
}

Checks: config_valid, endpoint_host_changed, endpoint_reachable (probes new or changed endpoint URLs), forced_update, maintenance_enabled, features_removed, cache_ttl, and route_deletions when you send the proposed routes. The level is high if any check fails or the score reaches 50, and medium from 20.

Release to a few devices first

A canary sends a new version to a share of your devices, watches their telemetry, and stops itself if those devices start failing.

1. 1
   Start the canary

   In the publish dialog, choose Release to 5–50% of devices first.

2. 2
   Watch and widen

   Under Deployments, raise the percentage, choose Release to everyone, or Stop canary.

3. 3
   Let safety act

   If canary devices error too often, Tellyport stops the canary automatically.

Who is in the canary?

Devices are picked by a stable hash of their device ID, so a device stays in the canary as the percentage grows. Devices that send no device ID stay on the stable version. Only one canary runs at a time, and a rollback or scheduled publish stops it.

Automatic rollback

The worker compares heartbeat errors (playerState: "error" or an errorCode) from canary devices with stable devices over the last 15 minutes. When enough canary devices report and their error rate passes the threshold (default 20%, and at least 5 points above stable), it stops the canary, records it in the audit log, and sends canary.rolled_back to webhooks and alerts.

Require a second pair of eyes

Approvals are off by default, which suits one-person teams. Turn on Require a teammate to approve every publish when you want a review.

• Publish draft then opens a change request instead of publishing.
• A different teammate with publish permission approves or rejects it under Deployments. The publish button then goes live with the approved revision.
• Editing the draft after approval invalidates the approval. That includes drafts saved by the CLI or GitHub Action.
• Rollback never waits for approval, so incidents can always be undone.

Config as code

Keep each environment's config in your repository, review changes as diffs in pull requests, and release them from CI with the same rules as the console. The CLI is a single dependency-free Node script: cli/originmesh.mjs (Node 18+).

node cli/originmesh.mjs login                    # URL + service token, saved to ~/.originmesh/config.json
node cli/originmesh.mjs pull -p tv-app           # writes originmesh.json (draft config + routes)
$EDITOR originmesh.json
node cli/originmesh.mjs diff                     # what would change in the draft
node cli/originmesh.mjs push -m "Move API to eu2"   # saves the draft, never publishes
node cli/originmesh.mjs publish --reason "Move API to the eu2 cluster" --rollout 10

• In CI, set ORIGINMESH_URL and ORIGINMESH_TOKEN instead of running login. Project and environment come from --project/--env, the file, or ORIGINMESH_PROJECT/ORIGINMESH_ENV.
• Exit codes: 0 success, 1 changes found (diff --exit-code), 2 error. Add --json to any command for raw API output.

The file

{
  "project": "tv-app",
  "environment": "production",
  "version": 51,
  "config": {
    "endpoints": { "api_base_url": "https://api.eu2.streambox.tv" },
    "app": { "minimum_version": "3.2.0", "force_update": false },
    "maintenance": { "enabled": false },
    "features": { "new_home_enabled": true },
    "cache_ttl": 300
  },
  "routes": [
    { "name": "Catalog item", "method": "GET", "path": "/catalog/:id", "mode": "proxy", "upstreamKey": "api_base_url", "enabled": true }
  ]
}

• Routes are optional. If the document has routes, apply replaces the environment's routes with that list. Routes are live, so in production that needs publish permission. Leave routes out to keep them as they are.
• Conflicts: send revision to make apply fail with 409 REVISION_CONFLICT if someone changed the draft since your export.
• Change paths look like config.endpoints.api_base_url or routes.GET /catalog/:id.

GitHub Actions

Copy cli/github-action.example.yml to .github/workflows/originmesh.yml and cli/originmesh.mjs to tools/originmesh.mjs. Pull requests get a diff; pushes to main push the draft and publish it.

name: Tellyport config
on:
  push: { branches: [main], paths: [originmesh.json] }
  pull_request: { paths: [originmesh.json] }

jobs:
  originmesh:
    runs-on: ubuntu-latest
    env:
      ORIGINMESH_URL: ${{ vars.ORIGINMESH_URL }}
      ORIGINMESH_TOKEN: ${{ secrets.ORIGINMESH_TOKEN }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: node tools/originmesh.mjs diff --file originmesh.json
      - if: github.event_name == 'push'
        run: node tools/originmesh.mjs push --file originmesh.json --message "$COMMIT_TITLE"
        env: { COMMIT_TITLE: "${{ github.event.head_commit.message }}" }
      - if: github.event_name == 'push'
        run: node tools/originmesh.mjs publish --file originmesh.json --reason "GitHub $GITHUB_REPOSITORY@${GITHUB_SHA::7}"

Service tokens

Service tokens give CI access to named projects with the editor or viewer role. Only owners can create them (Organization settings › Service tokens), and the token is shown once.

{ "name": "github-ci", "role": "editor", "projects": ["tv-app"] }

→ 201 { "token": "om_st_…", "id": "…", "name": "github-ci", "prefix": "om_st_ab12cd",
        "role": "editor", "projects": ["tv-app"] }

# use it on project routes
Authorization: Bearer om_st_…

• Scope: projects: [] means every project in the organization. Tokens get 403 on anything outside project routes.
• Roles: editor can view, update, and publish config; viewer is read-only.
• Manage: GET on the same path lists tokens with lastUsedAt; DELETE …/tokens/:id revokes one immediately. Actions appear in the audit log as Service token <name>.

Analytics & fleet map

Each environment records hourly buckets of bootstrap requests, 304s, errors, gateway traffic, and distinct devices, kept for 30 days.

Remote diagnostics

Ask a specific device for its recent logs, app state, and a screenshot. The request is delivered on the device's next heartbeat and the SDK uploads the result.

1. 1
   Request

   Open a device and choose Request diagnostics, or call POST …/devices/:deviceId/diagnostics with { "include": ["logs","state","screenshot"] }.

2. 2
   Deliver

   The heartbeat response carries commands: [{ "type": "diagnostics", "id": "diag_…", "include": [...] }].

3. 3
   Upload

   The SDK posts to /api/v1/devices/diagnostics/:project/:env/:requestId with its device token. The request shows completed.

• Limits: up to 500 log lines, 2 MB per upload, PNG or JPEG screenshots only. Requests expire after 24 hours; the console lists the latest 20. Requests and uploads are audited.
• Screenshots depend on the platform. Where an app can't capture its own screen (for example Tizen web apps), the result says screenshotUnsupported: true.
• Your own context: SDKs let you add log lines and a state object, such as the current screen and player state.

Studio: build TV & OTT apps without a new build

Studio is a visual editor at /studio/. The design you publish travels inside the signed configuration, so every TV running the Studio app template renders it on its next check-in, with canary, rollback, approvals and config as code included.

1. 1
   Choose the kind of app and a template

   Streaming, IPTV player, Sports, News, Education, Restaurant menu, Hotel lobby signage, Gym schedule, Community board, Photo frame, Quiz night, Live poll, Kids storytime, or start blank.

2. 2
   Brand and content

   Name, logo, colours and fonts with a live preview. Point rows at a JSON feed, MRSS, RSS, YouTube channel, static items, or viewer-provided playlists.

3. 3
   Edit on the canvas

   Click a block in the TV preview to select it, drag to reorder, press + between blocks to add one. The inspector on the right edits the selected block, screen, theme or source.

4. 4
   Save and publish

   Save a draft, run the risk check, publish with a reason. Ship the app template once per platform; afterwards every change is a publish, not a store update.

Any kind of TV app

The wizard starts with What are you building? Each kind sets sensible defaults and a shortlist of blocks in Simple mode; everything stays available in Advanced mode.

• Streaming & media: movies, series, live TV, radio, podcasts, YouTube.
• Business & info: restaurant menus, hotels, clinics, schools, community centres, company TV.
• Digital signage: a hands-free loop of pages for lobbies, shop windows and waiting rooms.
• Games & interactive: quiz nights, polls, scoreboards and prize wheels driven by the remote.
• Utility (clock, weather, tickers, photo frame) and Kids & learning (big friendly buttons).

Blocks

• Content & promo: hero, rail, grid, banner, text, carousel, categories, video hero, countdown, QR code, button row.
• Business: menu & prices, schedule, contact & hours, notice. Signage: ticker, slideshow, clock, weather (Open-Meteo, no key).
• Games (plugin pack): quiz, poll, leaderboard, scoreboard, spin-the-wheel. Scores stay on the TV; results can be posted to your own API.
• Layout & advanced: tabs, columns, spacer, custom HTML/CSS (sandboxed, no scripts), plugin blocks registered by your app build.

Sources

Static lists, JSON feeds, MRSS, RSS, YouTube channels, M3U/Xtream/XMLTV (viewer-provided), and new in v3: CSV (a Google Sheet published to the web: menus, schedules, any list) and iCal calendars. Feeds without CORS are fetched through the Tellyport feed proxy, which only allows URLs that are part of the design.

Endless possibilities

• Rules (visibleIf): show a block only on certain platforms, countries, locales, rollout groups, feature flags, or during a time window.
• Languages: any text can be a per-locale map; the TV picks its own language and switches to right-to-left where needed.
• Experiments: A/B overrides by rollout group. Assets: a reusable library referenced as @asset:key.
• Theme extras: gradients, background images, logo position, card shadows, custom CSS.
• JSON view: edit the whole document as JSON, import/export it, restore a design from any published version, and compare the draft with what is live.

Publish to TV stores

Studio › Stores turns a published design into installable packages for each TV platform, creates the artwork every store asks for, and walks you through each store console step by step.

1. 1
   Listing

   Name, descriptions, category, age rating, privacy policy, version and the store ids (Android application id, Samsung package id, LG app id). One listing feeds every store.

2. 2
   Artwork

   One click creates every icon, banner and background at the exact size (Samsung 512×423, LG 80/130 + splash, Android launcher icons and the 320×180 TV banner, Play, Amazon, Roku and Apple TV art) from your brand colours and logo. Replace any with your own file: Studio fits it to the size.

3. 3
   Screenshots

   Capture the TV preview straight from Studio (the browser asks which tab to share) or upload your own; they are stored at 1920×1080.

4. 4
   Builds

   Each package ships the published design (shown offline before the first check-in) and its own client key, which you can revoke under Connect › Keys. After install the design keeps updating from Tellyport; rebuild only to change the name, icon or version.

5. 5
   Store steps

   Checklists for Google Play, Amazon Appstore, Samsung Seller Office, LG Seller Lounge, the Roku Channel Store, App Store Connect (Apple TV) and web hosting, with links to each console. Progress is saved on the listing.

What each TV draws

Samsung, LG, Android TV, Fire TV and web run the full web-TV runtime, so every block works there. Roku (SceneGraph) and Apple TV (SwiftUI) are native apps that draw the subset below. Studio shows the same chips on every block, screen and source, and the Roku and Apple TV build cards list what your design uses that they skip. Anything not drawn is left out; the rest of the screen still works.

Send releases to the stores

Studio › Stores › Release connects your store accounts once, then sends the app package, the listing text and the artwork in one click. Samsung, LG and Roku have no public submission API, so they keep their guided Store steps.

1. 1
   Connect

   Paste or choose the key file and press Test connection. Keys are encrypted at rest, never shown again and can be replaced or removed at any time.

2. 2
   Upload the package

   Run ./build.sh in the Android TV package and upload the .aab (Play) or .apk (Amazon). Uploads are kept for 7 days.

3. 3
   Send

   Choose the store, the track and what to send. The release runs on the server; its steps and any store error appear in Release history. A failed Play release discards its edit, so nothing half-done reaches the store.

Manage your content in one place

Studio › Content keeps collections of videos, live channels, menu items, classes, slides or news for this project. Every TV app (Samsung, LG, Android TV, Fire TV, Roku and Apple TV) reads them as a feed, so content changes need no new design and no new app build.

1. 1
   Create a collection

   Pick a kind (videos, live channels, menu, schedule, slides, news). The kind decides which fields the editor shows.

2. 2
   Add or import items

   Add items one by one (with image upload), or import a CSV (Google Sheets: File › Download › CSV), JSON, M3U playlist or RSS feed. Preview shows what will be imported and which rows are skipped.

3. 3
   Use it in the design

   “Use in design” adds the collection as a source. Choose it in any rail, grid, carousel, menu, schedule or slideshow and publish the design once.

4. 4
   Publish, schedule, reorder

   Drafts never reach TVs. Published items appear within about a minute; “Show from” and “Show until” put items on air for a time window (offers, events). Up/down arrows set the order on screen.

Give everyone the right controls

All people use the same login page. Their organization membership and role decide which data and actions the server allows.

Sign-in, email, and invitations

Turn on two-factor authentication

Anyone can protect their account with an authenticator app.

1. 1
   Open Account settings

   Add the setup key shown to your authenticator app (or open the link on this device), then enter the 6-digit code to turn it on.

2. 2
   Save your recovery codes

   Eight single-use recovery codes are shown once. Store them somewhere safe, such as a password manager.

Set up single sign-on (OIDC)

Let your team sign in through your company identity provider. Configure it under Team access.

1. 1
   Register the callback URL

   Copy the callback URL shown in Tellyport into your identity provider's app settings.

2. 2
   Add your email domains

   Add each email domain your team signs in with, and choose the default role for new SSO users.

3. 3
   Prove you own the domain

   Publish the DNS TXT record shown in the console, then click Check DNS.

_originmesh-challenge.example.com.  TXT  "originmesh-verification=<token shown in the console>"

Get alerts in Slack or PagerDuty

Go to Webhooks › Slack and PagerDuty alerts, add a destination, and click Send test to confirm it works.

Alerts cover endpoints going down and recovering, canary rollbacks, publishes, rollbacks, and change requests awaiting approval. Alert destinations are stored encrypted.

Scrape Prometheus metrics

Set ORIGINMESH_METRICS_TOKEN on the server, then scrape /metrics with that value as a bearer token.

scrape_configs:
  - job_name: originmesh
    scheme: https
    metrics_path: /metrics
    authorization:
      type: Bearer
      credentials: <ORIGINMESH_METRICS_TOKEN>
    static_configs:
      - targets: ["config.example.com"]

It reports request counts and latency, bootstrap responses by release, sign-ins, publishes, gateway upstream errors, devices online, canary share, and outbox backlog. Each API instance reports its own counters, so scrape every instance.

Verify the audit log

Each project's audit log is a hash chain. Open Audit log and click Verify integrity to check it.

Common errors and what to do

Common questions