From 9c611d6129b3c2b24d6409fd7f3d8f88029f5ab2 Mon Sep 17 00:00:00 2001
From: "molecule-ai[bot]" <276602405+molecule-ai[bot]@users.noreply.github.com>
Date: Tue, 21 Apr 2026 03:14:01 +0000
Subject: [PATCH] =?UTF-8?q?docs:=20update=20docs/quickstart.md=20=E2=80=94?=
 =?UTF-8?q?=20Phase=2030=20remote=20agent=20registration?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 docs/quickstart.md | 119 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 119 insertions(+)

diff --git a/docs/quickstart.md b/docs/quickstart.md
index 7dbb19b7..337c168c 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -90,6 +90,125 @@ What can you help me with in this workspace?
 
 Responses are delivered through the platform A2A proxy and pushed back to the canvas through WebSocket events, with polling kept only as recovery fallback.
 
+
+---
+
+## Path 2: Remote Agent (run anywhere)
+
+A remote agent runs on your own machine or a cloud VM — no Docker on the platform side. The agent registers with the platform via API, pulls its secrets at boot, and sends heartbeats to stay live on the canvas.
+
+**Use this path if you:**
+- want to run an agent on your laptop for local development
+- need an agent on a machine with specific hardware (GPU, on-prem)
+- have a data-residency requirement that keeps agent compute off the platform's infra
+
+### Step 0: Prerequisites
+
+- Python 3.10+ and `pip install molecule-agent-sdk`
+- Outbound HTTPS access from the agent machine to `https://<your-org>.moleculesai.app`
+- A platform admin token (from the canvas, under `Config → Secrets & API Keys → Global`)
+
+### Step 1: Create the workspace
+
+```bash
+PLATFORM="https://acme.moleculesai.app"
+ADMIN_TOKEN="your-admin-token"
+
+curl -X POST "$PLATFORM/workspaces" \
+  -H "Authorization: Bearer $ADMIN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "my-remote-agent",
+    "runtime": "external",
+    "external": true,
+    "url": "https://my-agent.example.com/a2a",
+    "parent_id": null
+  }'
+```
+
+Save the returned `workspace_id`.
+
+### Step 2: Register the agent
+
+```bash
+WORKSPACE_ID="ws-xyz"
+
+curl -X POST "$PLATFORM/registry/register" \
+  -H "Authorization: Bearer $ADMIN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d "{
+    \"workspace_id\": \"$WORKSPACE_ID\",
+    \"name\": \"my-remote-agent\",
+    \"description\": \"Runs on a cloud VM in us-east-1\",
+    \"skills\": [\"research\"],
+    \"url\": \"https://my-agent.example.com/a2a\"
+  }"
+```
+
+The response includes your bearer token — save it now. It is shown only once.
+
+### Step 3: Pull secrets at boot
+
+```bash
+AGENT_TOKEN="the-token-from-step-2"
+
+curl "$PLATFORM/workspaces/$WORKSPACE_ID/secrets/values" \
+  -H "Authorization: Bearer $AGENT_TOKEN"
+```
+
+Store the returned secrets in your environment before starting the agent.
+
+### Step 4: Run the agent
+
+```bash
+molecule-agent run \
+  --workspace-id "$WORKSPACE_ID" \
+  --platform-url "$PLATFORM" \
+  --agent-token "$AGENT_TOKEN"
+```
+
+The agent connects to the platform, appears on the canvas within ~10 seconds, and starts processing tasks.
+
+### Step 5: Configure the agent
+
+Edit `config.yaml` in the agent's working directory:
+
+```yaml
+name: my-remote-agent
+role: researcher
+runtime: python
+platform_url: https://acme.moleculesai.app
+a2a:
+  port: 8000
+```
+
+### Step 6: Inspect and iterate
+
+The agent appears on the canvas as a workspace card with a **REMOTE** badge. Open the chat tab, send a task, and watch it work. To iterate, stop and restart the agent — it re-registers with the same `workspace_id` and token.
+
+### Behind NAT (no public IP)
+
+If the agent machine has no public IP, use a tunnel:
+
+```bash
+# Terminal 1: start a tunnel
+ngrok http 8000 --url https://my-agent.ngrok.io
+
+# Update the registered URL
+curl -X POST "$PLATFORM/registry/update-card" \
+  -H "Authorization: Bearer $AGENT_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"workspace_id": "'"$WORKSPACE_ID"'", "url": "https://my-agent.ngrok.io/a2a"}'
+```
+
+No inbound firewall rules needed — the agent initiates the outbound WebSocket connection.
+
+### Next steps
+
+- [Register a Remote Agent](../tutorials/register-remote-agent.md) — full tutorial with CI/CD examples
+- [External Agent Registration Guide](../guides/external-agent-registration.md) — detailed reference
+- [Remote Workspaces FAQ](../guides/remote-workspaces-faq.md) — common questions
+
 ## What To Try Next
 
 - **Expand to a team:** right-click a workspace and choose `Expand to Team`.