TODO 180.C.29.07 — runnable examples driving the remote gateway through the Bellona remote SDKs.
These examples drive a remote creative host (Blender / Unreal / a managed
browser / a desktop) through the Bellona remote gateway
(apps/bellona/remote-gateway) using the typed SDKs:
- Python —
@bellona-remote(TODO 180.C.29.05) - TypeScript —
@oshun/bellona-client→/remote(TODO 180.C.29.04)
Each example is a real script: it builds validated command envelopes (the SDK
enforces the protocol's id-format / command-name / risk / approval / rollback /
dry-run invariants client-side, mirrored from @bellona/remote-protocol) and
submits them to the gateway's REST API (/v1/sessions, /v1/commands,
/v1/artifacts, /v1/approvals, /v1/timeline, …). None of them fabricate a
result: where a step needs a live Blender / Unreal / Mac host that is not on this
box, the script is still correct and would run against a live host — it documents
the prerequisite honestly and fails loud (e.g. a gateway 409 "no connected host")
rather than pretending the work happened.
The five flows#
| # | Flow | Python | TypeScript |
|---|---|---|---|
| 1 | Blender create → render → export (+ fetch & verify the artifact) | python/blender_create_render_export.py |
typescript/blender-create-render-export.ts |
| 2 | Unreal import → place → capture (map create, asset transfer, spawn + transform, world query, save) | python/unreal_import_place_capture.py |
typescript/unreal-import-place-capture.ts |
| 3 | Browser production-board update (launch, navigate, DOM click/type/submit, screenshot) | python/browser_production_board.py |
typescript/browser-production-board.ts |
| 4 | Cloud-agent control — drive a session via the cloud-gateway tunnel as an orchestrator agent (operator→agent delegation chain) | python/cloud_agent_control.py |
typescript/cloud-agent-control.ts |
| 5 | Desktop fallback dialog handling — drive a native OS dialog with privileged desktop.* commands + the human-approval gate |
python/desktop_dialog_fallback.py |
typescript/desktop-dialog-fallback.ts |
Running the Python examples#
The Python examples run here, with no live host, against an in-process
DemoGatewayTransport (a labelled test double at the SDK's RemoteTransport
seam — the same role as httpx.MockTransport in the SDK tests). The SDK code
path (envelope construction + validation + result parsing) is exercised for real;
only the gateway+host are simulated, and the simulation echoes the submitted
command rather than inventing host work.
# No live host needed (demo mode):
python3 examples/bellona-remote/python/blender_create_render_export.py --demo
# Against a real gateway + paired host:
python3 examples/bellona-remote/python/blender_create_render_export.py \
--gateway http://localhost:4100 --host-token "bellona-host-token-v1.…"
The example code is byte-identical between demo and live — only the transport
differs (--gateway builds a real httpx client; --demo injects the double).
(The SDK is added to sys.path automatically from the repo checkout; for an
installed SDK, cd libs/bellona/sdk-python && poetry install first.)
Running the TypeScript examples#
The TS examples talk to a real gateway over HTTP (the 29.04 SDK's
HttpRemoteTransport). They require a running gateway and a paired host; supply
the URL + host token via env vars:
BELLONA_GATEWAY_URL=http://localhost:4100 \
BELLONA_HOST_TOKEN="bellona-host-token-v1.…" \
npx tsx examples/bellona-remote/typescript/blender-create-render-export.ts
Without a connected host the gateway rejects the command (HTTP 409) and the
script prints a clean ✗ gateway error and exits non-zero — it does not
fabricate success.
What each example needs#
| Flow | Live prerequisite (beyond the gateway) |
|---|---|
| 1 Blender | a paired host running Blender + the Bellona host app / Blender adapter |
| 2 Unreal | a paired host running Unreal Editor 5.x with the Bellona Unreal adapter / Remote Control enabled |
| 3 Browser | a paired host with the Bellona browser adapter + a managed Chromium |
| 4 Cloud-agent | a host paired in cloud-gateway network mode (reachable over the relay tunnel) |
| 5 Desktop | a paired host with the desktop adapter + macOS Accessibility / Screen-Recording (or Windows UIA) permissions, and a human approver for the privileged commands |
Verifying the examples#
# Python: every example compiles and runs in demo mode.
python3 -m py_compile examples/bellona-remote/python/*.py
for f in examples/bellona-remote/python/*_*.py; do python3 "$f" --demo; done
# TypeScript: every example typechecks against the real SDK types.
cd examples/bellona-remote/typescript && npx tsc --noEmit -p tsconfig.json