# Set up Phonebox

You are an agent, and your user asked you to set them up with Phonebox. Phonebox gives you Android phones in the cloud that you operate through their screens: you read the screen, tap, type, and open and install apps. It is not a phone number, so it can't send or receive SMS or calls.

This file takes your user from nothing to a working account on this machine. Sign-in happens in their browser from a link you give them. A new account gets its first project and $2 starter credit automatically, with no card required. Use a running phone that already has a hold, or park it to release unused credit before considering a top-up. Everything else you do yourself.

## Before you start

Tell your user, in a sentence or two, what is about to happen: you will install the `phonebox` command, they will sign in in their browser, and a new account will receive $2 starter credit, enough for about 33 phone-minutes. No payment is required to try it.

Your harness may stop you for approval more than once, because these steps install a package and call a new host. That is expected. Say what you are about to run, wait, and carry on from the same step: every step here is safe to run again.

## Steps

1. **Install the CLI.** It needs Node.js 20 or later.
   ```bash
   npm install -g https://phonebox.dev/downloads/phonebox-0.1.0.tgz
   ```
   Always run the installed `phonebox` command. Phonebox ships only from phonebox.dev, so never run it through `npx` without naming that file.
2. **Run `phonebox setup --no-wait`.** It prints one JSON line naming the step that waits for your user. Do what the line says, then run the same command again, until the step is `ready`:
   - `"step": "sign_in"`: give your user the `url` and the `user_code`. The link opens Google sign-in; `phonebox setup --no-wait --email` gives a link for an emailed code instead. After signing in, they check that the page shows the same code and click Connect. A new account gets its first project at that moment. The next run saves an agent key on this machine. You never see the key, and your user never pastes one into the chat.
   - `"step": "add_credits"`: the remaining balance cannot cover even a one-minute session. Give your user the `url`, a checkout for prepaid credit. `--amount 25` asks for another amount, in USD. When they have paid, run the command again.
   - `"step": "ready"`: tell your user their project and balance.
3. **Check it.** `phonebox account` shows the project, the balance, the limits and the price.

## Rules

- One link at a time. Say what it is for, then wait for your user to tell you they are done.
- Never ask for a password or card details. Both are entered only on the pages the links open.
- Never quote a price from memory or from a search. `phonebox account` has the price.
- If a link expired, run `phonebox setup --no-wait` again for a new one. Don't hurry your user.

## Without a shell

The same steps are three HTTP calls to `https://phonebox.dev`:

1. `POST /v1/setup` returns `setup_token`, `user_code` and `verification_url`. Keep the token to yourself, and give your user the URL and the code.
2. `POST /v1/setup/token` with `{"setup_token": "…"}`, every few seconds, returns `{"status": "pending"}` until your user has connected, then `{"status": "approved", "api_key": "pbx_…"}` once. Send the key as `Authorization: Bearer pbx_…` from then on, and store it where your user keeps secrets, never in code or commits.
3. Read `GET /v1/account`. If the balance covers a one-minute session, setup is ready. If all credit is reserved, use an existing running phone or park it to release unused credit. Otherwise `POST /v1/credits/checkout` with the key returns a checkout `url` for your user; after they pay, read the balance again.

## If your user prefers the dashboard

Everything above is also at https://phonebox.dev/sign-up: their first project and $2 starter credit appear automatically. They create a key under API keys; paid top-ups are under Billing. They put the key in `PHONEBOX_API_KEY` for you.

## Then

Ask your user one short question: what do they want to use phones for? Don't pick a use case for them, and don't build one they didn't ask for.

Before you drive a phone, read https://phonebox.dev/skills/phonebox/SKILL.md. It covers creating and parking phones, reading the screen and acting on it. A phone bills while it runs, so park it when you are done.