molecule-sdk-python/examples/remote-agent

Remote agent demo

A ~100-line Python script that registers with a Molecule AI platform from outside its Docker network, pulls its secrets, and heartbeats — exercising the Phase 30.1 / 30.2 / 30.4 endpoints end-to-end.

Prerequisites

• A running Molecule AI platform (./infra/scripts/setup.sh + go run ./cmd/server from platform/)
• pip install requests in your Python environment

Quick start

# 1. Create the workspace row on the platform. `external` runtime keeps
#    the provisioner from trying to start a Docker container:
curl -s -X POST http://localhost:8080/workspaces \
    -H 'Content-Type: application/json' \
    -d '{"name":"remote-demo","tier":2,"runtime":"external"}'
# → {"id":"<UUID>", ...}

# 2. (Optional) seed a secret so `pull_secrets` has something to return:
curl -s -X POST http://localhost:8080/workspaces/<UUID>/secrets \
    -H 'Content-Type: application/json' \
    -d '{"key":"REMOTE_DEMO_KEY","value":"hello-from-remote"}'

# 3. Run the demo from any machine that can reach the platform:
WORKSPACE_ID=<UUID> PLATFORM_URL=http://localhost:8080 \
    python3 sdk/python/examples/remote-agent/run.py

You should see log lines for each of the three phases, and then heartbeat lines every 5s. The workspace should appear online on the canvas. Pause or delete it from the canvas / via API, and the script exits cleanly.

What this demonstrates

Phase	Endpoint	Shown in the demo
30.1	POST /registry/register	Token issuance + on-disk caching
30.1	POST /registry/heartbeat	Bearer-authenticated liveness report
30.2	GET /workspaces/:id/secrets/values	Token-gated decrypted-secrets pull
30.4	GET /workspaces/:id/state	Token-gated pause/delete detection

What it doesn't do yet

• No inbound A2A server. Other agents can't initiate calls back to this remote agent. Future 30.8b adds an optional HTTP server helper.
• No sibling discovery. Future 30.6 adds peer URL caching so this agent can call siblings directly instead of going through the proxy.

Troubleshooting

• 401 missing workspace auth token on the secrets/state calls — your cached token is stale (workspace was recreated). Delete ~/.molecule/<workspace_id>/.auth_token and re-run.
• connection refused — double-check PLATFORM_URL and that the platform is actually listening.
• Workspace never appears as online on the canvas — confirm it was created with runtime: external (otherwise the provisioner will try to start a local container and fail).