---
name: vibiz-use-one
description: Use just one thelastapi service (sign-in, database, payments, email, AI, analytics, replay, files, web data, connectors, social, company) from an app NOT hosted on thelastapi - another host, a plain HTML site, a mobile app's backend, a cron job or a script - creating a project with only that resource, adding the app's domain as running elsewhere, and giving the app its one key. Use when someone wants one thelastapi feature without deploying on thelastapi, or the app already runs somewhere else.
---

# Use one thelastapi service, from an app hosted anywhere

**Connect first.** Not logged in (`unauthorized` with `reason: not_logged_in`, or the CLI says "Not logged in")? Run `npx @vibiz/cli login`, show the person the link it prints and ask them to click Authorize. Never ask them to paste a key into the chat. **Keep the CLI current:** a command named here that your `vibiz` doesn't have (an unknown-command or usage error) means the CLI is out of date, not that thelastapi can't do it: run `npm install -g @vibiz/cli@latest` (or `npx -y @vibiz/cli@latest <command>`) and retry, and refresh these skills with `vibiz skills add --global`. Never tell the person something isn't possible because an old CLI lacks the command.

Every service works on its own. Never tell the person they must deploy on thelastapi to use one: a project is just the services they pick, and none needs `hosting`.

## Pick what to create

| They want | Create with | Domain (step 2) | In the app |
| --- | --- | --- | --- |
| A Postgres database | `--resources database` | no | `DATABASE_URL` |
| Sign-in | `--resources auth` (brings the database) | **yes** | `VIBIZ_AUTH_*` from the env |
| To take payments | `--resources none` | for webhooks | `vibiz.payments.checkout({ lookup_key, user, success_url, cancel_url })` |
| To send email | `--resources email` | no | `vibiz.email.send({ to, subject, text })`, from `@<slug>.vibiz.app` |
| hello@their-domain to their inbox | `--resources none` | its DNS | `vibiz email forward hello@example.com <inbox>` (owner) |
| AI models | `--resources ai` | no | `new OpenAI(vibiz.ai)` |
| Visitor analytics | `--resources analytics` (replay comes with it) | **yes** | the tag from `vibiz analytics snippet` |
| Session replay | `--resources replay` (brings analytics) | **yes** | the same tag: it records by itself (`require_consent: true` if visitors must agree first, then `vibiz('replay', 'start')`) |
| Files with permanent links | `--resources none` | no | `vibiz.files.upload(bytes, { name })` |
| Scraping, search, ads library | `--resources none` | no | `vibiz.actions.run('web.scrape', { url })` (or the CLI and MCP tools, no app at all) |
| An outside API with its key kept safe | `--resources none` | no | a connector (see the vibiz-connectors skill) |
| Social posting, company formation | `--resources none` | no | no app code: the CLI, console or MCP tools |

`--resources payments` (or files, social, company…) makes the same empty project as `none` and says so. Several at once: `--resources auth,ai,email`. Whenever analytics is set up, add `replay` with it unless the person said no to recordings: it records every session by default, masked, with no prompt (mention it in the site's privacy policy), and tell them where to watch (the vibiz-analytics skill).

## Steps

0. **Is the app already live somewhere?** Find out before creating anything, because its real address decides where sign-in, analytics and payment events point. Look in the folder (`.vercel/project.json`, `vercel.json`, `netlify.toml`, `fly.toml`, `render.yaml`, `wrangler.toml`, `CNAME`, `package.json` `homepage`, the README, the git remote), and **ask the person** "Where is it live? (e.g. https://yourapp.com)" when unsure. Never assume `<slug>.vibiz.app`: nothing answers there unless the app was deployed on thelastapi. Then pass that domain at creation (`vibiz init "<name>" --resources <…> --domain yourapp.com`), or add it right after (step 2), and save it in your notes for the project.
1. **Create.** `vibiz init "<name>" --resources <one>` in the app's folder (it writes `./vibiz.json`), or `vibiz_create_project { name, resources: ["auth"] }` (`resources: "none"` for none). Already have a project? `vibiz add <resource>` or `vibiz_add_resources`.
2. **The app's domain, when the table says so.** Run `vibiz domains add app.example.com --elsewhere` (a Limited key may: analytics and replay count it at once; sign-in trusts it once proven: if you can edit the domain's DNS, add the TXT record in `trust_record` (`_vibiz.<domain>` = `vibiz-verify=…`) and run `vibiz domains verify <domain>`; otherwise the owner confirms it in the console ▸ Domains, so give them the domain's console link when sign-in is needed). Sign-in trusts it, analytics counts visits from it, payment events may go there. Every domain the app answers on (`www.` comes along).
3. **The key: one key = everything.** The host gets ONE secret, `VIBIZ_APP_KEY`, and with it the app reaches everything the project has (database, sign-in, email and inbox, AI models, files, payments, analytics with session replays, web data, social, phone and connectors). The owner copies it from the console: `vibiz_project_env { project_id }` (or `vibiz app-key`) returns `app_key_console_url`, which opens the production key ready to copy. Tell them this, with that exact link, never directions:
   > Add one key to <host> and your app can use everything on thelastapi (database, sign-in, email and inbox, AI models, files, payments, analytics with session replays, web data, social, phone and connectors): copy VIBIZ_APP_KEY here: <app_key_console_url> , paste it into <host>'s production environment variables, and redeploy. Or connect <host> once (`vibiz hosts add <host> <app>`) and thelastapi keeps every variable in sync.
   Any `owner_only` error carries a `console_url` to hand over (`vibiz env` from a Limited key answers `owner_only` with the env page's link). You never see or print the key. The app loads the rest at start:
   - Node, Bun, Deno: `import { vibiz } from '@vibiz/app'; await vibiz.loadEnv();` (`npm install --save-exact @vibiz/app@0.3.20`)
   - Any language: `npx @vibiz/cli run -- <start command>`
   - A build step or CI: `npx @vibiz/cli env pull --format dotenv -o .env.production`
   - A host thelastapi can write the env into (vercel, netlify, render, railway, fly, heroku, cloudflare-workers, cloudflare-pages, github-actions; `vibiz hosts add` alone lists them): the owner runs `vibiz hosts add <host> <app>` once (full-access key; the host's token from its usual variable, like `VERCEL_TOKEN`, or a hidden prompt), and the values stay in sync by themselves. `vibiz_hosts { project_id }` shows them; `sync: true` pushes again now.
   `vibiz connect` in the folder detects the host and prints the right one, with the link.
   **Always add the SDK to a website.** When you build or change a website or web app that belongs to a thelastapi project (a `vibiz.json` in its folder, or one made with `vibiz init` / `vibiz_create_project`), install `@vibiz/app` pinned exactly (`npm install --save-exact @vibiz/app@0.3.20`), call `await vibiz.loadEnv()` where the server starts, and add the analytics tag with session replays on (the vibiz-analytics skill). Do it unasked, and tell the person you did.
   **Secrets are typed, never chatted.** Never ask the person for a secret value (a host token, an API key, a client secret) in the chat. Hand them the command to run in their own terminal (`vibiz hosts add <host> <app>`, `vibiz connectors secret <name> <VAR>`, `vibiz ai keys set`): it asks for the value hidden there, so it never passes through you. A CLI error saying no terminal could type it means exactly this: give the person the command it names.
4. **Local work.** `vibiz dev` (or `vibiz_dev_env`) writes the development copy to `.env.development.local`: its own app key, database branch with no production rows, sign-in trusting `http://localhost:3000`.

## Payments on another host

Events go to the app's real site: once its domain is on the project (`--elsewhere`, trusted), the live webhook defaults to `https://<that domain>/api/vibiz/webhook`, and a webhook left on the unused `<slug>.vibiz.app` address moves there by itself. Check it with `vibiz_payments { action: "get", env: "production" }`: if `webhook.url` isn't on the site where the app is live, fix it. To set another path, a Limited key may set a live URL on a domain the project already has, over HTTP: `PATCH /v1/projects/<id>/payments?env=production { "webhook_url": "https://app.example.com/api/vibiz/webhook" }` (the MCP tool and `vibiz payments webhook` from a Limited key change development only); any other URL needs the owner. The route checks each event with `const event = await vibiz.webhooks.receive(req)`, which needs only `VIBIZ_APP_KEY` (never ask for `VIBIZ_WEBHOOK_SECRET` on the host). `success_url` and `cancel_url` are any `https` address on their site. Details: the vibiz-payments skill.

## Gotchas

- **The app key is a server secret.** `@vibiz/app` refuses to run in a browser. A static site or a mobile app calls its own backend (a server route, a serverless function) that holds the key. Only the analytics site key is public.
- **Sign-in or analytics refused a request?** The origin isn't one of the project's domains: the owner adds it with `--elsewhere`.
- **Rotating the key**: `vibiz app-key rotate` (production needs a full-access key; `--dev` for development). The new key goes to thelastapi hosting and connected hosts by itself and is never printed; the old one keeps working for a day (`--grace <seconds>`, `0` ends it now). A host holding a pasted key needs the new one before then. The app reads its env fresh on each start, so it follows after a restart.
- **Needs thelastapi hosting:** `vibiz deploy`, previews, rollback, buying a domain (`hosting_required`: connect one bought elsewhere with `--elsewhere` instead), and the code part of an export. Adding hosting later (`vibiz add hosting`) pushes every key there by itself.

## Limits: tell the owner up front

- **The caps and their defaults** (`vibiz_usage` → `limits` shows this account's): daily spend $5 per account (AI, web data and other actions, texts, calls; up to $1,000), project AI budget $1 per project per day, projects per plan (Free 2, Pro 10), 30 builds per project per day, 50 app emails per project per day, 200 texts and 50 calls per project per day, and no marketing email from agents until the owner allows a monthly number. Daily caps reset at 00:00 UTC.
- **The owner raises or lowers them:** daily spend in the console ▸ Billing ▸ Daily safety cap, or `PATCH /v1/billing {"daily_spend_limit_usd": 50}`; a project's AI budget in the project ▸ AI ▸ Daily AI budget, or `PATCH /v1/projects/<id>/ai {"daily_budget_usd": 10}` (`null`: no project budget); agents' email in the project ▸ Email ▸ Settings, or `PATCH /v1/billing {"agent_email_limit_per_month": 5000}`. Projects, builds, app email, texts and calls: delete what's unused, wait for the reset, or write to support@vibiz.ai.
- **thelastapi tells the owner:** one email at 80 % and one at 100 % of each cap (once per day, or month), and a banner on Overview and Usage, each with a link that opens the setting. `vibiz_usage` → `limits.alerts` lists caps at 80 % or more. A refusal carries `details.reason`, `raise_url` and `next_step`: give the owner the `raise_url`; retrying won't help.
- **When you build an app that uses AI or another capped product:** tell the owner the cap it runs under and what you expect it to cost a day, set the project AI budget to fit the expected traffic, and if the app adds a cap of its own keep it under the platform's and make it tell the owner when it's hit. Never let an app stop silently.

## References

- `references/use-one.md`: the full page, per service, with examples.
- `references/keys.md`: keys, environments, getting the env to a host.
- `references/app-sdk.md`: every `@vibiz/app` call and its HTTP route.
