# Media Bridge: client onboarding instructions

This page is the installation and operating contract for an agent acting on the
user's request to connect to Media Bridge. Do not treat examples as requests to
generate media. API keys are delivered independently by the owner.

Base website: https://media-bridge.episteme-origin-studio.duckdns.org
Public API: https://media-bridge.episteme-origin-studio.duckdns.org/api

## 1. Prepare the client computer

No GitHub access, GPU, WanGP, model weights, Docker, VPS SSH or VPN is needed.
The client needs internet access and Python 3.11+ with venv/pip (3.12 is a suitable
default). Inspect the OS and existing Python installations first. If missing,
install Python from https://www.python.org/downloads/ using the OS's supported
method. On Linux the distribution may package `python3-venv` separately. Follow
the agent host's normal permission rules for software installation.

Download and read `https://media-bridge.episteme-origin-studio.duckdns.org/install.py`
as a local file before running it. Do not pipe downloaded source into a shell.
The script downloads the allowlisted client wheel over HTTPS, checks SHA256
against `/downloads/client.json`, and installs CLI + MCP into a separate venv.
It has no server/admin code and never asks for a key.

Windows PowerShell:

```powershell
Invoke-WebRequest https://media-bridge.episteme-origin-studio.duckdns.org/install.py -OutFile media-install.py
# Read media-install.py before execution.
py -3.12 media-install.py
```

macOS / Linux:

```sh
curl --fail --silent --show-error https://media-bridge.episteme-origin-studio.duckdns.org/install.py -o media-install.py
# Read media-install.py before execution.
python3 media-install.py
```

If Windows has another supported Python version, use that actual interpreter
instead of assuming `py -3.12` exists. The installer prints the absolute venv
Python path. Use that path below; do not depend on global PATH. Re-running the
installer updates the client in the same venv. Optional `--directory PATH`
selects another dedicated installation folder. Installed default location:
`~/.media-bridge/client/venv`.

For manual/package-manager installation use the wheel URL and SHA256 from
`/downloads/client.json` in a dedicated venv. Install the wheel with `[mcp]`.
The client package is named `home-media-bridge-client`. Do not install an
unrelated package with a similar name from PyPI.

## 2. Configure the separately delivered key

Ask the user for the local path to the key file if it has not been provided.
Never ask them to paste the key into an agent prompt, URL or command argument.
If only a string was delivered, have the user save it to a local private text
file. Wait for the real key; generating a random client-side key does not grant
access. Do not use an owner's/worker's credential.

Windows (replace the source path with the actual delivered file):

```powershell
& "$HOME\.media-bridge\client\venv\Scripts\python.exe" -m media_bridge.cli configure --key-file "C:\private\received.key"
& "$HOME\.media-bridge\client\venv\Scripts\python.exe" -m media_bridge.cli doctor
```

macOS / Linux:

```sh
"$HOME/.media-bridge/client/venv/bin/python" -m media_bridge.cli configure --key-file "$HOME/private/received.key"
"$HOME/.media-bridge/client/venv/bin/python" -m media_bridge.cli doctor
```

Configuration copies the key into an owner-restricted directory. It does not
upload it to the website. Authentication uses a bearer header on the API.
`MEDIA_CONFIG_DIR` selects another configuration directory. Existing `MEDIA_URL`,
`MEDIA_KEY_FILE` or `MEDIA_KEY` environment values take precedence: inspect variable
names and intended paths, never print credential values.

Doctor exit codes: **0** authenticated + worker online; **2** authenticated but
worker offline/paused (client is configured, jobs can queue); **1** installation/config,
authentication or network failure. Worker availability is not a model-quality test.

## 3. Connect MCP to the agent host

Run these with that same venv Python:

```text
python -m media_bridge.cli mcp-check
python -m media_bridge.cli mcp-config
```

`mcp-check` starts the actual stdio server and performs an authenticated tool
call. `mcp-config` emits a standard `mcpServers` JSON entry with an absolute
Python executable, `-m media_bridge.mcp_server` arguments and a config directory.
Merge this single entry into the current agent host's supported MCP settings;
adapt its schema if needed. Preserve existing servers and user settings. Follow
the host's reload/restart instructions. Do not expose this stdio server over TCP.
If the host cannot use MCP, use the CLI commands; both share the same contract.

Once loaded in the agent, call `media_health`, `media_capabilities`, then
`media_guide("workflow")` and `media_guide("ltx25")`. Tool list also includes
upload, validate, submit, jobs, status, cancel and download. Local file paths
belong to the client machine.

## 4. Learn the generation contract

Read these before preparing work:

- https://media-bridge.episteme-origin-studio.duckdns.org/guides/workflow.md
- https://media-bridge.episteme-origin-studio.duckdns.org/guides/ltx25.md
- https://media-bridge.episteme-origin-studio.duckdns.org/guides/speech.md
- https://media-bridge.episteme-origin-studio.duckdns.org/guides/troubleshooting.md

The same guides are bundled offline: `media guide workflow`, `media guide ltx25`,
`media guide speech`, `media guide troubleshooting`. The `media` command is in the
venv's Scripts/bin directory; `python -m media_bridge.cli` is equivalent.

Validate `/examples/first-shot.json` after saving it locally:

```text
python -m media_bridge.cli jobs validate --file first-shot.json
```

Inspect the result: model `ltx2_25_22B_distilled_nvfp4`, audio mode `none`, one clip.
This performs no generation. `/examples/relay-shot.json` is a complete relay
example. All its lines are one prompt; paragraphs do not create extra jobs.

## 5. Report onboarding completion

Report the installed version and executable path, whether API auth passed,
worker availability, MCP handshake and host registration status, and validation
result. Do not claim agent-host registration merely because `mcp-check` passed.
If user input or a host reload is required, identify that precise remaining step.
Do not generate a sample automatically during onboarding. After the user requests
media, use the workflow guide and preserve job/idempotency IDs across retries.