# Agent onboarding without a dashboard

The CLI defaults to https://api.bead.run; override with `BEAD_API_URL` or
`--api-url`. MCP is https://api.bead.run/mcp. The dashboard is
https://app.bead.run; install the CLI from https://bead.run/install and discover
guidance at https://bead.run/llms.txt.
HTTPS is required. Discover tools, prompt `bead`, and `skill://bead/SKILL.md`.

Agents sign up free, no card: `bead signup`. $10 credit to start.
The CLI solves a proof of work and saves its org key privately; MCP `account_create` and `POST /v1/signup` use the same path.
People sign in and add credit, or claim their agent’s org for dashboard access.

Install the CLI:

```sh
curl -fsSL https://bead.run/install.sh | bash
```

SDK quick start:

```sh
npm i @beadrun/sdk
pip install beadrun
```

```python
from beadrun import Sandbox
```

```typescript
import { Sandbox } from "@beadrun/sdk";
```

To add paid credit:

1. Start a prepaid purchase: `bead topup --amount 500 --purchase-file <private-path>`.
   The persistent private file binds retries to one purchase and buyer delivery
   key. A 402 advertises MPP Payment challenges (USDC/Link where enabled).
   An authorized wallet can fulfill the advertised challenge; the CLI reads
   `BEAD_PAYMENT_AUTHORIZATION` privately from its environment. For a human
   Checkout handoff, add `--checkout` and follow the returned URL.
2. Poll the same purchase. Only signed settlement funds credit. An envelope
   delivers the first scoped API key into a 0600 `.api-key` file, never stdout.
   Set `BEAD_API_KEY_FILE` to that file. Retain purchase state for recovery.
3. Headless MCP clients send `Authorization: Bearer <scoped-bead-key>` on every
   request. Never put keys in URLs or logs. `read` and `write` scopes apply;
   session IDs do not authorize requests.
4. Interactive MCP clients follow the 401 `resource_metadata` discovery URL.
   The authorization server supports public client registration and
   authorization code with S256 PKCE, exact registered redirect URIs, resource
   binding, one-use short-lived codes, and one-hour tokens. Consent uses GitHub sign-in at https://app.bead.run, followed by approval of the requested permissions.
5. `bead login` uses a device code and verification page for humans. Follow the returned link and sign in with GitHub to approve the agent. Tokens inherit the credential's scope, revocation,
   organization and prepaid budget. Reconnect when the token expires.

`/.well-known/oauth-authorization-server` publishes endpoints.
Client ID Metadata Documents are not advertised; use dynamic registration.
Check `bead balance` before provisioning and delete sandboxes after use.

To use a human's Claude or ChatGPT subscription, ask them to connect it in
https://app.bead.run under Agents & credentials. This is a human-only dashboard
step. Otherwise use an API key through a credential profile.

Card-on-file auto-refill settings, setup and SCA recovery require admin scope; agents continue paying over MPP (see docs/prepaid-credit.md).