Skip to content
extraorbital
Documentation ExtraOrbital
Browse documentation

Start here

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:

sh
npx extraorbital deploy
Output
→ 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.com

Another folder: npx extraorbital deploy ./web. A message for the version: -m "New pricing page".

StepWhat happens
1. The filesThe folder is read with its ignore rules, checked against the limits, and summed up.
2. The projectThe 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 uploadDeploy answers which files it does not have (by SHA-1); only those are sent. Unchanged files cost nothing.
4. The versionProduction's resources and variables are set, then Vercel builds. The build log streams while it runs.
5. The answerThe production URL, the ExtraOrbital host and the primary domain. Or the errors, and exit code 1.

What is uploaded

Rule
.gitignoreThe folder's, the ones under it, and the ones above it up to the repository's root, as git reads them.
.vercelignoreAt the folder's root, after them.
Nevernode_modules, .next, .git, .vercel, .turbo, .env* files, .extraorbital*. Symbolic links are skipped.
Limits4 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 prod for each service the project uses: the ones extraorbital add made 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_SECRET of 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:

Output
! Production has no value for 1 variable the app reads:
  OPENAI_API_KEY (lib/ai.ts) · extraorbital add openai, then deploy again

npx 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

Output
✗ 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

sh
npx extraorbital deploy --json
npx extraorbital deploy --json --no-wait

--json prints one object on stdout, progress on stderr:

json
{
  "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

sh
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 -f

A rollback is instant: the version is already built. See the CLI reference for every flag.