Deploy a folder
Send a Next.js app's folder to production with npx extraorbital deploy, follow the build, read its errors, roll back and read production's logs.
Production runs on ExtraOrbital Deploy, on Vercel: one Vercel project per ExtraOrbital project, a version history and rollback, and a host of its own, <slug>.extraorbital-apps.com. The CLI deploys production only. Previews (a live copy you edit with an agent) are made from the MCP server.
Deploy
From the app's folder:
npx extraorbital deploy→ Deploying . to shop · 132 files, 2.4 MB · 18 left out by the ignore rules
3 to upload (120 KB), 129 already on ExtraOrbital
v12: building on Vercel…
│ Running "npm run build"
│ ✓ Compiled successfully
✓ Production: https://shop.extraorbital-apps.com (v12)
Primary domain https://shop.comAnother folder: npx extraorbital deploy ./web. A message for the version: -m "New pricing page".
| Step | What happens |
|---|---|
| 1. The files | The folder is read with its ignore rules, checked against the limits, and summed up. |
| 2. The project | The one .extraorbital.json names. An unlinked folder is linked first, as link does: chosen at a terminal, or named after the git remote or the folder. |
| 3. The upload | Deploy answers which files it does not have (by SHA-1); only those are sent. Unchanged files cost nothing. |
| 4. The version | Production's resources and variables are set, then Vercel builds. The build log streams while it runs. |
| 5. The answer | The production URL, the ExtraOrbital host and the primary domain. Or the errors, and exit code 1. |
What is uploaded
| Rule | |
|---|---|
.gitignore | The folder's, the ones under it, and the ones above it up to the repository's root, as git reads them. |
.vercelignore | At the folder's root, after them. |
| Never | node_modules, .next, .git, .vercel, .turbo, .env* files, .extraorbital*. Symbolic links are skipped. |
| Limits | 4 MB per file, 100 MB and 10,000 files per folder. A larger folder is refused before anything is sent, naming the heaviest parts. Serve large files from storage. |
--dry-run lists the files and their sizes, and sends nothing.
Production's variables
A local .env is never uploaded. Production has its own:
- Resources. A permanent resource with the slug
prodfor each service the project uses: the onesextraorbital addmade for it. A service is never guessed from a variable's name. - A sign-in secret. An app that uses better-auth gets a
BETTER_AUTH_SECRETof its own, minted once and kept. - Logs. Its server and browser logs reach ExtraOrbital (
extraorbital logs --prod).
The variables the app reads, from .env.example and from process.env.X in its code, that production has no value for are listed after the deploy, with the service that provides each one:
! Production has no value for 1 variable the app reads:
OPENAI_API_KEY (lib/ai.ts) · extraorbital add openai, then deploy againnpx extraorbital deploy --check lists them before deploying, deploys nothing, and exits 1 if there are any.
Frameworks
Next.js only, for now: the folder needs a package.json with a next dependency. Production is a Next.js project on Vercel, and the log client added to every deployment is Next.js code. Anything else is refused with a message, before anything is uploaded.
When the build fails
✗ v13 failed: 2 errors
First error app/page.tsx:3:7 Type 'string' is not assignable to type 'number'.
Type errors (1)
app/page.tsx:3:7 Type 'string' is not assignable to type 'number'.
Lint (1)
app/lib/x.ts:12:5 'x' is assigned a value but never used. (@typescript-eslint/no-unused-vars)
Full build log: npx extraorbital logs --prod --source build v13
Production still serves the version before it.The errors are grouped by step: install, build, type errors, lint, then the deployment itself. The command exits 1, and production keeps serving the version before.
For agents and scripts
npx extraorbital deploy --json
npx extraorbital deploy --json --no-wait--json prints one object on stdout, progress on stderr:
{
"ok": true,
"project": "shop",
"version": 12,
"status": "ready",
"url": "https://shop.extraorbital-apps.com",
"host": "https://shop.extraorbital-apps.com",
"primaryDomain": null,
"files": 132,
"bytes": 2516582,
"uploaded": { "files": 3, "bytes": 122880 },
"errors": [],
"env": { "services": ["mongo"], "missing": [] }
}On a failure, ok is false, errors holds {kind, file, line, column, message, rule} items, and the exit code is 1. --no-wait returns once the deployment is created; follow it with extraorbital deployments.
A machine still in its sandbox can't deploy: run npx extraorbital login once.
Versions, rollback, logs
npx extraorbital deployments # every version; ● is production
npx extraorbital rollback # the version before the current one
npx extraorbital rollback v3 # a given version (or forward to a newer one)
npx extraorbital logs --prod # server and browser logs of production
npx extraorbital logs --prod --source build # the newest build's output
npx extraorbital logs --prod --level error --since 1h -fA rollback is instant: the version is already built. See the CLI reference for every flag.