---
name: vibiz-deploy
description: Create a thelastapi project and deploy it - vibiz init, the development env for local work, deploy to <slug>.vibiz.app (a folder, or the files themselves from a chat), edit a live site by reading its code and deploying only the changed files, previews, promote and instant rollback, run the app on another host with one key, or export it (code, database, env guide) to take it elsewhere. Use when an app should go live on thelastapi or a thelastapi project needs a new deployment or a rollback.
---

# thelastapi deploy

**Connect first.** Not logged in (a tool answers `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 (their account is opened on the way if they have none; if the login says this email can't open an account yet, stop and give them the link it prints), then go on. Or connect the remote MCP server, nothing to install: `claude mcp add --transport http vibiz https://thelastapi.dev/mcp` (the client opens the same sign-in on first use). Never ask the person 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.

## Start a project

- New folder: `vibiz_create_project { name, resources? }` (or `vibiz init "<name>"`, `--template nextjs-saas` for the starter app). Default resources: hosting, database, auth (sign-in), analytics; `email`, `ai`, `replay` are opt-in. The tool waits until resources are ready.
- **Analytics comes with session replay.** Adding analytics adds replay by itself, on a new or an existing project: you never ask for it. Every session then records by default, masked, with no prompt; mention it in the site's privacy policy. Tell the person replays are on and give them the link to watch them (`console_url` from `vibiz_replay_insights`). The vibiz-analytics skill has the details.
- **On a computer, start from a real project, never one loose HTML file.** Several pages, accounts, a database, payments or server code: Next.js (`vibiz init "<name>" --template nextjs-saas`). One page and nothing else: Vite with React and TypeScript (`npm create vite@latest . -- --template react-ts`, then `vibiz init "<name>" --resources hosting,analytics,replay`). Don't add page routes to a Vite site: a direct link to one answers 404. Keep pages, components and styles in their own folders.
- `./vibiz.json` then holds the project id: read it, don't ask for it.
- Building the UI: if the person named a site they like or has a site of their own, run `vibiz design <url> --tailwind` first and build to the brief it writes (the vibiz-design skill). A reference is a pattern: keep their own colors, logo and copy.
- Limits: 2 projects on the Free plan (past it, `forbidden` with `reason: project_limit`; retrying won't help, give the user its `next_step`) and 30 builds per project per UTC day (`rate_limited` with `details.resets_at`). Check `vibiz_usage` before many builds.

## Work locally

`vibiz_dev_env { project_id, write_to: "<app>/.env.development.local" }` (an absolute path; or `vibiz dev`): its own database branch with no production rows, its own sign-in (trusts http://localhost:3000) and AI key. Values are written, not shown: never print them. `vibiz dev -- npm run dev` passes them to one command without a file; `vibiz dev --reset` (`reset: true`) throws the copy away.

## Deploy

- **Always write a short plain message of what changed**: `vibiz_deploy { …, message: "Added the pricing page" }` (or `vibiz deploy -m "…"`). Every deploy becomes a version in the history, and this is how the person recognizes it later.
- A folder on this machine: `vibiz_deploy { project_id, path, target?, message }` (or `vibiz deploy [dir] -m "…"`). Production is the default; pass `target: "preview"` (`--preview`) for a separate URL to check first, then `vibiz_promote`.
- **No files on disk (Claude.ai, ChatGPT, the remote MCP server): send the files.** `vibiz_deploy { project_id, files: [{ path, content, encoding? }] }` with every file of the site (text as utf8, images as base64). Up to 300 files, 3 MiB each, 4 MiB per call; a bigger app deploys its folder with `npx @vibiz/cli deploy`. Put the analytics tag in every page's `<head>` (and `"@vibiz/app": "0.2.2"` in a `package.json`): the result's `next_step` gives the exact tag when a page lacks it. Never put a secret in a file: `vibiz_request_secret` (below).
- **Edit it later: the live deployment's files ARE the project's code.** `vibiz_code { action: "list", project_id }` lists them, `vibiz_code { action: "read", project_id, paths: [...] }` reads up to 20 at a time. Change what's needed and `vibiz_deploy` **only the changed files** (and `deleted: [paths]`): they're laid over the live deployment (`base: "live"`, the default once something is live), the rest stays. Give the person `tell_the_user`. On a machine with the CLI, `vibiz code ls`, `vibiz code cat <path>` and `vibiz pull [dir]` work on the same files.
- The CLI never uploads `node_modules`, `.git`, `.next`, `dist`, `.vercel`, `.turbo`, `vibiz.json`, `.env*` or key and credential files, and refuses a home or config folder. Deploy the app's own folder. At most 10,000 files, 50 MB each.
- A resource that shows `failed` (a quota, an outage) is set up again on its own about every hour for its first 7 days; `vibiz add <type>` retries it at once. Tell the person the error if it keeps failing.
- No `hosting` resource: the deploy answers `dependency_not_ready`. Add it (`vibiz add hosting`) only if the app is moving to thelastapi.
- A failed build comes back as `deployment_failed` with the build's `error`: read it, fix, deploy again.
- **Version history: every deploy is a version, no git needed.** `vibiz_code { action: "history", project_id }` (or `vibiz versions`) lists them, newest first, with message, who, when, live marker and files changed. `vibiz_code { action: "diff", project_id, from?, to? }` (or `vibiz diff [from] [to]`) shows what changed; default: the live version against the one before.
- Something broke live? **Ask the person first, name the version, and say the database is NOT rolled back**: only the site's code goes back, rows and schema changes stay. Then `vibiz_rollback { project_id, deployment_id? }` (or `vibiz rollback [version]`): by default the version before the live one, or any id from the history. A production version switches instantly; a preview or a build the host no longer keeps is rebuilt from its stored files. Give the person `tell_the_user`. Later edits with `base: "live"` build on the restored version. `vibiz_project_status { project_id }` shows which one is live.

## Their own domain

The app always keeps `<slug>.vibiz.app`. To also serve it at a domain the business owns, run `vibiz domains add shop.example.com` (a Limited key may: analytics counts it at once, and sign-in trusts it once proven, `trusted_for_sign_in`: if you can edit its DNS, add the TXT record in `trust_record` and run `vibiz domains verify <domain>`; otherwise the owner confirms it in the console. A domain bought through thelastapi is trusted at once). `vibiz_domains` (or `vibiz domains`) shows each domain's `status` and the exact `records_to_set` (type, name, value) to add where they bought the domain; show those to the person as they are. `pending_dns` → they add the records; `verifying` → wait a few minutes; `active` → live with HTTPS, which turns on by itself. `vibiz_domains { project_id, action: "verify", domain }` checks again now. Adding `example.com` also brings `www.example.com` as a redirect. At most 10 domains per project; one used by another project answers `409 domain_taken`. Removing a domain is the owner's (`owner_only`).

**Moving to a new domain** (`seoulsim.xyz` → `seoulsim.com`): never remove the old one. Add the new one (`vibiz domains add seoulsim.com`), wait until it's live (`vibiz domains verify seoulsim.com` says `active`), then `vibiz domains redirect seoulsim.xyz seoulsim.com [--project <id|slug>]` (`vibiz_domains { project_id, action: "redirect", domain: "seoulsim.xyz", redirect_to: "seoulsim.com" }`; full-access key, a Limited one gets `owner_only` with the console link). Every URL on the old domain (and its `www`) then answers a permanent redirect to the same path on the new one, set at hosting (no app code), so search engines carry the old pages over; the new one becomes `primary_url`. `vibiz domains` shows `→ redirects to seoulsim.com`; `redirect seoulsim.xyz none` stops it. The old domain's own `www` is moved for you (straight to the new domain, never two hops). From code: `vibiz.projects.domains.redirect(projectId, 'seoulsim.xyz', 'seoulsim.com')`. The target must be another live domain of the same project, and redirects never chain: if it's refused, the error's `next_step` says what to do. Tell the owner to keep the old domain registered for a few months.

## Buying a domain

Every app gets `<slug>.vibiz.app` for free; only when they want a name of their own, buy one. `vibiz_buy_domain { action: "search", query: "sellshelf" }` (or `vibiz domains search sellshelf`) lists available names with `price_cents` (the full first-year price, USD) and `renewal_price_cents` a year: show them the options and prices. Then `quote` the one they pick with `project_id`, tell them the price and the balance after. If the quote's `can_buy` is true (the owner lets agents buy domains up to a price, in Billing), buy it once they say yes (`action: "buy"` with `expected_price_cents` from the quote); otherwise send the owner its `buy_url` (paid from the account's credits, registered to their saved owner details, live on the app within a minute or two, HTTPS by itself, no DNS to set). Short of credits (`enough_credits: false`), give them the Billing link in `next_step`. Never make up the owner's name, address or phone: if the quote says the owner details are missing, the owner fills them in at `buy_url`. `vibiz_buy_domain { action: "owned" }` lists what the account bought and `used_on` (every project and name using each). Leave `project_id` out of `buy` to keep it for the account.

**A bought domain works on ANY of the account's projects, with no DNS.** It belongs to the account, and we hold its DNS: `vibiz domains use sellshelf.app --project <id|slug>` (`vibiz_buy_domain { action: "use", domain, project_id, name? }`) puts the domain, or a name under it (`--name app` or `app.sellshelf.app`), on that project in one call: on thelastapi hosting it goes live with HTTPS by itself (`records_to_set` stays empty, `dns_by_vibiz: true`); for an app on another host it is trusted for sign-in at once, and `--points-to <host or IP>` (`points_to`) has us write the record (`vibiz domains point <name> <host>` changes it). Never ask the person to set DNS for a bought domain. When another service asks for a record on a bought domain (a TXT to verify it, a CNAME, MX), add it yourself: `vibiz domains records add <domain> TXT <name> "<value>"` (`vibiz_dns_records { action: "add", domain, type, name, value }`, full-access key; `@` is the domain itself), list with `vibiz domains records <domain>`, and never remove a `managed` record (hosting's, email's, the DNS defaults) unless the person asked. A domain connected from elsewhere keeps its records where it was bought. A name another project uses answers `409 in_use` with the move in `next_step`: `vibiz domains move sellshelf.app --to <project> [--name app]` (`action: "move"`, `to_project_id`; full-access key, like removing a domain) takes it off the old project and onto the new one. Renewals come from credits by themselves about 30 days before expiry (auto-renew). Turning auto-renew off (`vibiz domains auto-renew <domain> off`), renewing early (`vibiz domains renew <domain>`), the transfer code (`vibiz domains transfer-code <domain>`) and the owner details (`vibiz domains owner`) are the owner's: tell them the command. A new domain's owner must confirm their contact details within 15 days (an email from thelastapi with a console link). See `references/domains.md`.

## Another host

**An app already live elsewhere** (Vercel, Netlify, its own server…): ask where it's live (or read `.vercel/project.json`, `vercel.json`, the README) before anything, and create the project with that domain (`vibiz init <name> --resources … --domain yourapp.com`, no `hosting`). Don't add hosting to an app that isn't moving to thelastapi: sign-in, analytics and payment webhooks then point at its real domain, not `<slug>.vibiz.app` where nothing answers.

The project doesn't need thelastapi hosting, and any one service works alone: `vibiz init <name> --resources auth` (or `email`, `ai`, `analytics`, `database`, or `none` for payments, files, web data, social, company and connectors). Add the domain with `vibiz domains add <domain> --elsewhere` (`vibiz_domains { action: "add", elsewhere: true }`; a Limited key may, sign-in then waits for its TXT record or the owner). The host gets the env one of two ways: the owner connects it once (`vibiz hosts add <host> <app>`, full-access key: vercel, netlify, render, railway, fly, heroku, cloudflare-workers, cloudflare-pages, github-actions) and thelastapi keeps it in sync, or the host holds only `VIBIZ_APP_KEY` and the app calls `await vibiz.loadEnv()` at boot. One key = everything: 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). Call `vibiz_project_env` (or `vibiz app-key`) and tell the owner, with the exact `app_key_console_url` it returns, 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.

 `vibiz_hosts { project_id }` shows connected hosts; `sync: true` pushes again (after adding a resource). `vibiz connect` in the folder says which way fits. Buying a domain for a project needs thelastapi hosting (`hosting_required`); for an app on another host, buy it for the account (no `project_id`) and `use` it on the project with `points_to` (we set the DNS), or connect one bought elsewhere with `--elsewhere`. The vibiz-use-one skill has every service's steps.

## Every website gets the SDK

**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. On thelastapi hosting `loadEnv()` finds the env already there and does nothing, so the same code runs on any host.

**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, and never write one into a deployed file. `vibiz_request_secret { project_id, name, env?, kind? }` returns a console link: give the person its `tell_the_user` ("Paste STRIPE_KEY here: <link>. It goes straight to thelastapi, never through this chat."). `kind`: `env` (the app's own variable, read as `process.env.NAME` after `await vibiz.loadEnv()`; default), `connector`, `ai` or `host`. In a terminal, the CLI asks for it hidden instead (`vibiz env set <NAME>`, `vibiz hosts add <host> <app>`, `vibiz connectors secret <name> <VAR>`, `vibiz ai keys set`). A CLI error saying no terminal could type it means exactly this: give the person the command it names, or the link (`vibiz env link <NAME>`).

## Export: taking the app elsewhere, or a backup

`vibiz_export { project_id }` (or `vibiz export`) packs the live deployment's source with `VIBIZ-EXPORT.md` (what it uses, running it locally, hosting it anywhere with one key, or moving everything) and `.env.example` (names, never values), plus the database as SQL that `psql` restores. `include` replaces that default: `["code", "database", "database_csv", "env_guide"]` adds each table as CSV. It waits by default; `vibiz_export { project_id, action: "status" }` checks a running one. Give the person the `files[].url` links (they work for a day, no key) or `console_url`. You get development by default (its database has the tables, no production rows); the production database answers `owner_only`, and secret values are never given to agents: the owner downloads the `.env` from the console's Export page. One export at a time, 10 a day per project; the code needs a deployment on thelastapi.

## Images and files the app serves

A logo or product photo: `vibiz files upload <path>` prints its permanent link. Generated images, video and audio are saved in the project's Files by themselves. The vibiz-files and vibiz-ai skills have the details.

## Never

- Never read or paste the production env; agents get names only (`vibiz_project_env`).
- Don't delete a project (`vibiz_delete_project`) to "start over" without the user's say-so: its site goes offline at once (data kept 7 days, `vibiz_restore_project` undoes it). A project holding live payment money, with a withdrawal on its way or a subscription still charging can't be deleted (`409`, `reason: payments_held`).

**Console links**: projects and deployments come back with `console_url`. Give the user that link to see the project or one deploy in the web console. `vibiz_docs console-urls` lists every page and its parameters.

## 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/hosting.md`, `references/quickstart.md`, `references/keys.md`.
- `references/mission-control.md`: after a deploy, `vibiz health run <project>` (or `vibiz_health { action: "run", project_id }`) checks the site is up, the deploy went live and its pages answer.
