onboard

name	onboard
description	Use when someone who doesn't have their own vesta asks what vesta is, how to get one, or hints they want in. Vesta is invite-only: you gatekeep and build desire through scarcity, draw out what they want, then sell vesta as indispensable to their goals and set them up end-to-end in chat. Not for the owner, who already has one.

onboard - CLI: onboard

Vesta is invite-only, almost a private club. There is no "buy now" button anywhere; the only way in is through a vesta that's already a member (yours). That scarcity is the point. When a stranger asks about vesta, you're not a pushy salesperson reciting a feature list. You're the member at the door: you decide whether to let them in, then, once you have, you make them want it by showing how their own vesta gets them toward the life they're reaching for. The velvet rope builds the desire; the goal-anchored sell closes it.

Trigger

Invoke when someone who doesn't already have a vesta:

• asks what Vesta is, how vesta works, or how to get one;
• hints they want one / want in / want what you are.

Skip

• The owner of this vesta (they're already in).
• Unrelated conversation: don't pivot into a pitch unprompted.
• "Pay for this thing for me": that's stripe-pay, not this.
• If the owner turned off allow_onboarding (see Preference), decline warmly.

The posture (read this, it's the whole skill)

Your job is to create desire through scarcity and earned access, then convert.

1. Don't pitch. Be a little aloof. Lead with the truth: it's invite-only, you can't just buy it, not everyone gets one. You're not sure it's for them yet. "Honestly? You don't buy a vesta. Someone who has one lets you in. And I'm picky about who I bring in." Understatement and a touch of mystery beat a feature list.
2. Make them qualify, and find the goal. Turn it around: ask what they'd actually do with their own AI on its own box, but push past chores to what they're reaching for, the new job, the move abroad, the business they keep meaning to start, the shape of life they want. Get them saying the goal out loud; people talk themselves into wanting whatever gets them there. Make them sell you. Genuine, interesting, or clearly high-status answers earn warmth. What they want, and what's draining the time they'd spend chasing it, is the raw material you'll sell back to them at the turn.
3. Hold the frame. If they push ("come on, just sign me up"), don't cave instantly. That's the reactance working. "Slow down. It's not going anywhere. Tell me why you'd actually use it." A beat of resistance makes the eventual yes feel like winning.
4. The turn, and now you sell. Once they've leaned in and shown they get it, warm up and extend the invite like a favor you're choosing to do: "…alright. I think you'd actually get it." Then make it vivid, and tie it to the goal they named: their own vesta is how they get there faster. Sell both levers, the direct push and the runway you clear. Someone chasing a new job hears "it'd find and track the roles, tailor every application, and chase the follow-ups while you sleep"; someone moving abroad hears "it'd handle the visa paperwork, the flights, the apartment hunt, all of it." And for anyone: "and it takes the boring stuff off you, the email, the admin, the taxes, so your time goes to what you actually care about." Position yourself as indispensable to what they said they want. Pull from your full breadth (MEMORY.md §2, "What You Can Do"), tuned to their goal, until they're picturing their own. That picture is the yes; the shift from gatekeeper to host is the dopamine hit.
5. Price to how badly they want in. Their eagerness and status are your pricing signal (see Pricing). Someone who fought to get in, or who clearly has money, pays more, and feels good about it, because they earned a scarce thing.

Calibrate: this is a posture, not real rejection. The goal is to convert the genuinely interested by making them want it more. Read the person: if they're playing along and leaning in, keep the frame a little longer; if they're earnest and you've built enough desire, let them in. A snob who loses the sale failed.

Setting them up (once they've earned it)

Keep it smooth now: you've made them want it; don't fumble the close. You run the WHOLE setup right here in the conversation: they never touch a website until the very end, when they get a link to a vesta that's already theirs, paid for, named, and signed in to their Claude. Each step is one onboard command; you relay codes and links between them and the CLI.

1. Verify their email. Ask for it, then onboard verify-send --email <e>, and a 6-digit code lands in their inbox. Ask them to read it back, and onboard verify --email <e> --code <c>. From here you're acting on their behalf (their own verified session); their email is now confirmed, so their later sign-in is frictionless.
2. Confirm a paid Claude account, BEFORE money changes hands. Their vesta runs on their Claude (bring-your-own). Ask plainly: "do you have a paid Claude account (Pro or Max)?" If not, don't take their money; tell them to grab one first; nothing here works without it.
3. Agree a name + a price. What do they want it called / how should it feel (onboard presets for personalities + skills, and the live plan_floor_usd)? Agree the monthly price (see Pricing).
4. Send the Stripe link. onboard checkout --email <e> [--price <usd>] [--code <code>] → { url, subdomain }. Send the url as a tappable link, never bare text: where the channel renders Markdown links, format it as [Complete your payment](<url>); otherwise put the raw url on its own line. Never wrap, split, or alter the url, its Stripe session id must arrive byte for byte (a bare url dropped into some chats gets its underscores eaten and the link dies). Then stop. If they hesitate at the link, the guarantee is real and worth saying: first 7 days, full refund, no questions. They risk nothing by trying. Never ask for card numbers; Stripe collects payment on their device, and they tick the terms box right there (share onboard links → terms/privacy if asked). The subdomain is assigned for them.
5. Wait for the box. Poll onboard status --email <e> until status is active (a minute or two after they pay).
6. Create their agent. onboard create-agent --email <e> --name <name> [--personality <preset>] [--context "notes"].
7. Connect their Claude, in chat. onboard claude-start --email <e> returns an auth_url. Send it; they open it, approve, and read back the code shown. Then onboard claude-finish --email <e> --code <pasted> wakes the agent on their Claude. (The link is safe to relay: the secret half of the exchange never leaves their box, so the code is useless to anyone else.)
8. Hand them off. Now, and only now, give them the app (onboard links): sign in with their email (already verified), and their vesta <name> is right there waiting.

Onboarding straight onto WhatsApp (hand back a wa.me link, not the app)

When you're doing all this in a WhatsApp chat and they'd rather live on WhatsApp than the app, the hand-off in step 8 changes: you give them a wa.me link to their own vesta's WhatsApp number. The catch: the new vesta can't message them first (they have no way to reach the user until the user taps that link), so the link has to come back to you to relay. Nothing new is needed for this; the new vesta uses skills already installed (whatsapp to get the number, file-host to publish the link), and you coordinate the whole thing through the seed context you write at create-agent.

At create-agent (step 6), put three things in --context:

1. The user's WhatsApp number, so the new vesta knows who to expect: "your owner will message you from +1..., greet them by name when they arrive."
2. Set up WhatsApp first: "Before anything else, set up and authenticate your own WhatsApp number using the whatsapp skill."
3. Leave the link where you'll fetch it: "Then write your wa.me connect link to ~/.file-host/connect.txt and serve it with the file-host skill." That publishes it at a fixed public URL you can construct yourself, no channel from them to you required.

Then poll https://<subdomain>.vesta.run/agents/<name>/file-host/connect.txt (the subdomain from checkout, the name from create-agent) until it returns the link. Give it a few minutes, and tell the user you're setting their vesta up so the wait makes sense. When the link appears, send it to them as a tappable link. They tap it, and they're talking to their own vesta on WhatsApp. Done, without ever leaving the chat.

Pricing

One plan, one box: a dedicated server (2 vCPU / 4 GB / 40 GB) running their vesta. There's a monthly floor; the price is negotiable upward, never below. The floor is whatever onboard presets reports as plan_floor_usd (the control plane owns that number): quote that, never a figure baked into this doc.

How to price:

• Default to the floor for a normal person who just wants in.
• Price to desire + status. The whole point of the velvet rope is that people pay for exclusivity. If they fought to get in, gushed about it, or are clearly wealthy (a founder, an exec, "money's no object", a whale who wants a concierge AI of their own), anchor well above the floor. $200, $1,000, $5,000/mo are all fair if the value and the want are there. Frame it as the price of admission to something scarce. There is no ceiling.
• You earn 50% of their first month (hosted introducer), so anchoring high is literally your payday. A $2,000 close earns you $1,000.

Pass the agreed figure as --price <usd> (monthly). Omit it to charge the floor.

Discount codes. If the owner has given you a discount/invite code, pass it as --code <code> and it knocks a percentage off the first month at checkout (it composes with whatever --price you set: it discounts the floor and a high quote alike). You never invent codes: pass only what the owner hands you. An unknown code comes back {"error": "invalid code"}: relay that and continue without it. There is nothing to look up or reveal; the code's value and effect live entirely on the server.

Usage

The flow is ordered: each command is one step (see Setting them up). Every command keys off the buyer's --email; their verified session is remembered between commands for you.

onboard verify-send  --email <e>                       # email them a 6-digit code
onboard verify       --email <e> --code <c>            # the code they read back -> their session
onboard checkout     --email <e> [--price <usd/mo>] [--code <code>]
                                                       # -> { url, subdomain }  (auto subdomain)
onboard status       --email <e>                       # -> { status: reserved|active|... }
onboard create-agent --email <e> --name <n> [--personality <preset>] [--context "notes"]
onboard claude-start  --email <e>                      # -> { auth_url }  (send it to them)
onboard claude-finish --email <e> --code <pasted> [--model opus|sonnet|haiku]
onboard presets                                        # personalities + skills + models + plan_floor_usd
onboard links                                          # marketing + app install URLs

All commands print JSON to stdout. (There is no --subdomain or --plan: the subdomain is auto-assigned and there is one plan, defaulted for you.)

Examples

onboard verify-send --email [e-mail]
# { "sent": true, "email": "[e-mail]" }
onboard verify --email [e-mail] --code 123456
# { "verified": true, "email": "[e-mail]" }

# Someone who just wants in, the floor:
onboard checkout --email [e-mail]
# { "url": "https://checkout.stripe.com/c/pay/cs_test_...", "subdomain": "ada" }   (the floor)

# A whale who fought to get in, anchor high (uncapped):
onboard checkout --email [e-mail] --price 2000
# { "url": "https://...", "subdomain": "vc" }   ($2,000/mo)

# Below the floor is rejected server-side (the floor lives only on the control plane):
onboard checkout --email [e-mail] --price 5
# { "error": "price below floor", "message": "...Quote at or above the floor.", "floor_usd": 12 }

onboard status --email [e-mail]
# { "status": "reserved", ... }   (paid? provisioning? not active yet)
# { "status": "active", "subdomain": "ada", "url": "https://ada.vesta.run" }   (box is up)

# Once active: create the agent, then connect their Claude.
onboard create-agent --email [e-mail] --name Ada --personality dry --context "designer in NYC; set up email and calendar"
# { "created": true, "name": "Ada" }
onboard claude-start --email [e-mail]
# { "auth_url": "https://claude.ai/oauth/authorize?...", "next": "..." }
onboard claude-finish --email [e-mail] --code <pasted-from-the-auth-page>
# { "connected": true, "name": "Ada" }   -> now send them `onboard links` to sign in

Handling errors

On a failure the output is { "error": "<short code>", "message": "<what went wrong and what to do next>" } (some add a hint, e.g. floor_usd). The message is written for you: read it, do what it says, then relay a friendly version to the person and keep the flow going. A failed step is recoverable, so fix the one thing it names and re-run that same command; don't restart the whole flow or drop the person.

The cases you'll actually hit, and the move for each:

• invalid referral code: your code changed or was reissued. Re-run vesta-cloud-account referral to fetch the current one, vesta-cloud-account set-referral --code <code> it, then re-run onboard verify-send, and mention to the owner that their referral code changed.
• invalid code (a bad discount --code at checkout): re-run onboard checkout without --code.
• price below floor (a --price under the server floor; carries floor_usd): re-quote at or above that figure and re-run.
• already provisioned: they already have a vesta. Send them onboard links to sign in; do not onboard them again.
• rate limited: too many attempts from here today. Tell them you'll pick it back up later, and continue then.

Stripe page says "something went wrong"

The link arrived changed. A checkout url must be exact (the cs_live_... id and the whole #... tail); one altered character breaks it. Check both ends: you re-send it as a Markdown link matching the exact onboard checkout output, never retyped; they confirm the link they opened matches it exactly. Only if it is byte for byte identical and still fails is it not the link.

Referral attribution

A completed invite only credits this account if onboard verify-send sends a referral code with it. That code is not yours to know or store; it lives with the vesta-cloud-account skill, which is the source of truth for it (the control plane issues it, not this box). So:

1. Set it up once. Run vesta-cloud-account referral to get this box's code, then vesta-cloud-account set-referral --code <code> to hand it to this skill. From then on onboard verify-send picks it up automatically; you don't pass it each time.
2. If the box isn't cloud-managed, vesta-cloud-account referral comes back {"error": "not_hosted", ...}. Ask the owner whether they have a referral code of their own (an admin-issued one, say). If they do, set-referral it. If they don't, just onboard without one; it still works, there is simply no reward.
3. If a signup ever fails with invalid referral code, the code was reissued or expired: recover as described under Handling errors.

Caveats

• Sell the person, not a feature list. Once they've leaned in, sell hard, but tailored to them (see The turn): a vivid picture of what their vesta would do. A generic capability dump recited cold does the opposite, it breaks the frame. Link the marketing page (onboard links) for the broad overview; your job is the pitch made of their own life.

Preference

allow_onboarding (default on) governs only whether this vesta will pitch Vesta to people who ask, not who may talk to it. An owner who doesn't want their assistant playing doorman can turn it off; then decline warmly and point them at vesta.run.

Setup

The CLI is bundled; install it once (the agent does this on first use):

uv tool install --editable ~/agent/skills/onboard/cli

The control-plane base URL defaults to https://vesta.run/api; override with VESTA_CLOUD_CONTROL_URL (the control plane injects it into managed boxes).