box/CLIENT-ONBOARDING-RUNBOOK.md

Client Onboarding & Fleet Runbook (CLIENT-ONBOARDING-RUNBOOK.md)

1. Overview & Agency Context

This document defines the complete standard operating procedure (SOP) and automated runbook for provisioning, authenticating, and onboarding client agency profiles (nodes) into the NetVM multi-tenant fleet on bl.

In accordance with the NetVM Ethics Charter (https://start.muse-dev.online/ethics.html):

• Managed services are strictly run for consenting clients with explicit authority.
• Every client receives a completely isolated network namespace (warp-<node>), dedicated WireGuard tunnel identity, isolated Chrome profile, and separate credentials.
• Canonical Naming Convention: node == agent == profile == API account.

---

2. Fleet Architecture & Port Allocation

The fleet uses a deterministic 94x0 CDP port and warp-<node> naming convention:

Node	CDP Port	Netns	Egress IP	Purpose / Profile
muse	9410	warp-muse	Dedicated WARP	Primary Dev / Orchestrator
pip	9420	warp-pip	Dedicated WARP	Production Agent
646	9430	warp-646	Dedicated WARP	Production Agent
opm	9440	warp-opm	Dedicated WARP	Production Agent
def	9450	warp-def	Dedicated WARP	Production Agent
<new>	9460+	warp-<new>	Dedicated WARP	Next provisioned client node

---

3. Step-by-Step Client Onboarding SOP

Phase 1: Infrastructure Provisioning (Automated)

Run the idempotent node provisioning script to generate the WireGuard identity, network namespace, CDP relay, and chrome-box profile:

# Example: Provisioning node 'dev1'
./bin/netvm-provision-node.sh dev1

Verification:

• Namespace created: ip netns list | grep warp-dev1
• Registry updated in NODES.md and ACCOUNTS.md.

---

Phase 2: Sign-in Initiation (super cred initiate)

Launch the client login flow without handling raw passwords or secrets:

# For email OTP login:
super cred initiate --node dev1 --email client@domain.com

# Or via Python Agent API:
python3 bin/cred-client.py initiate --node dev1 --email client@domain.com

• If already authenticated, exits 0 (active).
• If awaiting verification code, exits 2 (awaiting_otp).

---

Phase 3: Submitting Transient OTP (super cred submit-otp)

When the client or operator receives the 6-digit email OTP:

super cred submit-otp --node dev1 --otp 123456

• The code is submitted transiently and is never persisted to disk or logs.
• If the account directly enters chat, status transitions to active.
• If the account requires age verification, it advances to Phase 4.

---

Phase 4: Resolving the Age Verification Gate (/access/verification)

When a brand-new or unlinked client profile reaches the Muse age verification gate:

Method A: Instagram Linking (Recommended)

1. Run:

   super cred link-instagram --node dev1 [--notify]
   

2. The system provides a one-tap Tailscale portal URL: http://bl.tailfb5960.ts.net:8765/verify/dev1
3. Crucial Rule: The operator or client must link an established / aged Instagram profile (not created within minutes). Brand-new Instagram accounts lack mature age signals, causing Meta Accounts Center to disable the Confirm button.
4. If completed via mobile/desktop browser, use an Incognito/Private window to prevent ambient Meta cookie bleed.
5. If executing automated RPA in-browser, inject the Instagram credentials and security code directly into the container's CDP session.

Method B: Credit Card Verification (Fallback)

If Instagram linking is not available, operator can complete the verification using a client payment card on /access/verification.

---

Phase 4.1: Edge Gate — Hard Audience Lockout (/access vs /access/verification)

• Observed Behavior: If an account routes to https://muse.ai/access with the text "Muse isn't available to all audiences." instead of https://muse.ai/access/verification:
  • The Meta account is temporarily unverified or lacks linked identity signals.
  • The in-app endpoint (/api/hatch/age-confirmation/linking-web-auth) returns 403 Forbidden.
  • Reloading or navigating directly to / or /access/verification immediately redirects back to /access.
• Root Cause:
  • Meta accounts without an active linked profile (Facebook or Instagram) trigger Meta's general audience filter on Muse before the conversational AI product can be initialized.
  • In addition, attempting automated sign-in on low-reputation / unverified identities directly from server/VPN IPs will trigger Google reCAPTCHA Enterprise checkpoints (auth_platform/recaptcha).
• Proven Unblocking SOP (The Direct Meta Accounts Center Flow):
  1. Open a clean browser session with the target Meta Account signed in (https://accountscenter.meta.com/).
  2. Navigate to Accounts → Add Accounts (/add_accounts/).
  3. Enter the Instagram credentials for an older/established IG profile (veryraremeta, paradahub, etc.) and submit any required 2FA/email OTP.
  4. If returned to Accounts Center, click Add Instagram again to initiate the OAuth handoff: https://www.instagram.com/fxcal/auth/login/?app_id=633385687760560...&flow=igcalcomet&entry_point=frl_web_settings
  5. On the "Meta needs to access info from your Instagram account" prompt, click [Continue].
  6. Accounts Center returns to the confirmation screen (/add/?auth_flow=ig_linking&token=...&blob=...) → click [Confirm].
  7. Meta sends security confirmation: "Did you just move your profiles into the same Meta Account?".
  8. Once confirmed in Accounts Center, simply navigate back or reload https://muse.ai/ inside the NetVM node. The /access lockout drops immediately, and the node enters active chat ("Hey! I'm your personal agent...").

---

Phase 5: Vitality & Status Monitoring

Query individual or fleet-wide health:

# Check single node
super cred status --node dev1

# Check entire fleet
super cred list

---

4. Rate-Limiting & Operational Safety Rules

To avoid platform anti-automation challenges and maintain high reputation:

1. Pacing / Spacing: Space new node creations and Instagram authorizations by at least 15–20 minutes per IP/session.
2. Namespace Isolation: Never attempt multi-account auth inside the same browser profile. Always execute inside the client's dedicated warp-<node> netns.
3. No Credential Logging: Never print plain text passwords or authentication tokens to stdout, git-tracked markdown, or plain text logs.