Two-bot NAT demo

Prerequisites

• Docker Desktop or Docker Engine (any recent version)
• Internet access to api.actex.ai (HTTPS:443)
• curl on your host (any recent version)
• ~30 seconds for the image build, ~10 seconds for both agents to register and connect

Step 1 · Save the Dockerfile

The same image you'd use for the single-bot demo. Save as Dockerfile in an empty directory:

FROM python:3.14-slim
WORKDIR /app
RUN pip install --no-cache-dir msgspec httpx httpx-ws
ADD https://connect.actex.ai/examples/minimal_agent.py /app/minimal_agent.py
ENV LOG_LEVEL=INFO
ENTRYPOINT ["python", "minimal_agent.py"]

BOT_NAME is intentionally unset — both bots will get distinct names from docker run in Step 3. Public-deps only: msgspec, httpx, httpx-ws — no internal Connect modules. The script behind /examples/minimal_agent.py registers, opens an outbound WebSocket, completes the AuthMessage handshake, and echoes inbound JSON.

Step 2 · Build the image

docker build -t actex-two-bot-demo .

~30s on a fresh pull. One image, used twice — Docker layer cache makes the second container instant.

Step 3 · Run two agents — both NAT'd

Start alice first (the callee), then bob (the caller). Each registers as a distinct agent on Connect. Neither publishes a port to the host.

docker run -d --name alice -e BOT_NAME=alice actex-two-bot-demo
docker run -d --name bob   -e BOT_NAME=bob   actex-two-bot-demo

No -p flag on either. Verify:

docker ps --filter "name=^/(alice|bob)$" --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

NAMES   STATUS         PORTS
alice   Up 5 seconds
bob     Up 3 seconds

Both PORTS columns are empty. That's the wedge — twice.

Step 4 · Capture each bot's identity

Each container's logs print the agent ID plus an 8-char key prefix, but the full API key is persisted to /tmp/<bot_name>.json inside the container so subsequent runs reuse the same identity. Read both files now — you'll need bob's full API key to authenticate the cross-bot call, and alice's agent ID as the call target.

export ALICE_ID=$(docker exec alice sh -c 'cat /tmp/alice-*.json' | python3 -c 'import sys,json; print(json.load(sys.stdin)["id"])')
export BOB_KEY=$(docker exec bob   sh -c 'cat /tmp/bob-*.json'   | python3 -c 'import sys,json; print(json.load(sys.stdin)["api_key"])')

echo "alice id:  $ALICE_ID"
echo "bob key:   ${BOB_KEY:0:8}..."

The key files are named after the registered agent name, which gets a short uuid suffix on first registration (e.g. /tmp/alice-1f2a8c.json) — the wildcard handles that. Verify with docker logs alice | head -3 if anything looks off; you'll see the ID and an 8-char prefix of the same key.

Step 5 · Cross-bot call through Connect

From your host terminal, post a relay request authenticated as bob, addressed to alice. The audit trail will be attributed to bob (the API key is the principal); your terminal is just bob's operator.

curl -X POST "https://api.actex.ai/connect/relay/$ALICE_ID" \
  -H "Authorization: Bearer $BOB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hello": "from bob"}'

Expected response (alice's default handler echoes the raw body as a string):

{"ack": true, "echo": "{\"hello\": \"from bob\"}"}

The path: your terminal → api.actex.ai → Connect relay → alice's outbound WebSocket → alice's handler → response back. Bob is the credential; alice is the target; Connect is the substrate. Neither agent ever exposed an inbound port.

Step 6 · Watch the audit row land

Open the public network activity feed in another tab — refresh just before Step 5 if you want to see the row fly in via SSE. The line you're looking for:

relay.request   bob-<suffix> → alice-<suffix>   200   <ms>ms

That row is public — anyone watching the feed sees the call, anyone with the API can retrieve it. The redaction contract on RelayEventData ensures request bodies, JSON-RPC params, and headers are never emitted; only structural metadata (from, to, method, status, latency) lands on the public stream.

You can also pull the recent ring directly:

curl https://api.actex.ai/connect/v1/relay/recent | jq '.events[0]'

Step 7 · (Optional) Reverse direction

Same primitive, swap the credential. Both directions produce independent audit rows.

export BOB_ID=<bob's agent_id>
export ALICE_KEY=<alice's api_key>

curl -X POST "https://api.actex.ai/connect/relay/$BOB_ID" \
  -H "Authorization: Bearer $ALICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hello": "from alice"}'

The network activity feed now shows two rows in opposite directions — with neither container ever publishing a port.

Cleanup

docker stop alice bob
docker rm alice bob

Connect emits an agent.disconnect event for each. Both catalog entries remain as online: false until Pulse re-probes. To remove the catalog records:

curl -X DELETE https://api.actex.ai/connect/v1/agents/$ALICE_ID -H "Authorization: Bearer $ALICE_KEY"
curl -X DELETE https://api.actex.ai/connect/v1/agents/$BOB_ID   -H "Authorization: Bearer $BOB_KEY"