The Xano Engine

The Xano Engine is the Xano backend running on your machine. A bare xanosdk deploy deploys to it, with no Xano account and no network round-trip once the Engine is cached. It runs the same imports, statements and tests as an ephemeral in Xano’s cloud.

Deploy to the Engine

In a scaffolded project, deploy to the Engine with the xano:deploy script:

npm run xano:deploy                          # scaffolded project
npx xanosdk deploy ./xano/index.ts --local   # any project; --local is the default, spelled out

On Windows or an Intel Mac? There is no Xano Engine build for your machine yet. Wherever this page says npm run xano:deploy, run npm run xano:deploy:ephemeral instead: it deploys the same code to an ephemeral in Xano’s cloud. That needs a Xano account, so sign in first (Connect to Xano). See where the Engine differs today.

The script typechecks, then runs xanosdk deploy ./xano/index.ts --keep-data. On a fresh machine the first deploy downloads the newest Engine for your platform, checks it against the sha256 its release recorded, starts it, and imports your backend. Each Engine version downloads once per machine and is shared by every project on it.

→ Deploying xano/index.ts → Xano Engine
i Pinned Xano Engine v0.1.26 in my-app/package.json — commit it so everyone on this project runs the same engine.
  on Xano Engine · 127.0.0.1:53358 · workspace 1
i Nothing to keep yet — this environment is new, so it is replaced and seeded. Later deploys with `--keep-data` keep its rows.
✓ Xano Engine xanosdk-4f2a91c03b7e deployed (4.4s)
i New Xano Engine URL:
  http://127.0.0.1:53358
  Open the builder: http://127.0.0.1:53358/_engine/sign-in?key=…
  Meta API bearer (the local XANO_META_TOKEN): `npx xanosdk local token`
  MCP server for coding agents: http://127.0.0.1:53358/_engine/mcp — connect one with `npx xanosdk local mcp`
  Stop it with `npx xanosdk local stop xanosdk-4f2a91c03b7e`
  No static site was published. Run your frontend locally against the URL above, or pass `--static <dir>` to have the engine serve a built one.
  Pointed .env.local at this deploy (VITE_XANO_HOST) — restart your dev server to pick it up. `--no-dev-env` skips this.

The deploy prints:

The backend URL. Your APIs answer there, on loopback only.
A sign-in link to the Xano editor on the Engine. Browse your tables and see what your code compiled to. The link carries a session, so treat it as a credential. xanosdk impersonate opens the same session later (--url-only prints it, --guest makes it read-only).
The MCP server a coding agent connects to. See Engine MCP server.

Your frontend follows the deploy

In a scaffolded project, a deploy that publishes no static site writes the Engine’s URL into .env.local as VITE_XANO_HOST, inside a marked block that leaves your own values alone. Restart npm run dev to pick it up. --no-dev-env turns the write off. A .env.local that your repo does not gitignore is reported, never written. To have the Engine serve a built frontend instead, see Frontend hosting.

Commit the pin

The first deploy pins the Engine version in package.json, creating the file if the project has none:

{
  "xanosdk": {
    "@xano/sdk": { "engine": "v0.1.15" }
  }
}

Commit it. Every checkout of the project then runs the same Engine, and a cached pin deploys with no network access. Nothing moves the pin without you:

A newer Engine is offered, never applied. Each deploy checks at most once an hour. In a terminal it asks, defaulting to no. In CI, piped output or --json it prints one line and keeps the pin. XANOSDK_NO_UPDATE_CHECK=1 turns the check off.
xanosdk local update moves the pin on purpose to the latest Engine, or to --version v0.1.14 (downgrades included). It downloads that version and restarts this project’s Engine on it. Commit package.json afterwards.
A teammate’s pin change reaches you on your next deploy. When the running Engine is on a different version from the pin, the deploy stops it, starts the pinned one, and says so.

Keep your rows between deploys

The scaffolded npm run xano:deploy passes --keep-data, so rows you enter through your app survive each code change:

The first deploy seeds. The Engine starts empty, and your tables get their seed rows.
Every later deploy merges. Code and schema changes land, objects you removed are deleted, and existing rows stay. Seed rows are not written again.
--reset starts over. npm run xano:deploy -- --reset replaces the Engine’s backend and seeds it fresh.

Before a merge writes, it prints what it will cost (dropped tables and columns, retyped columns, new tables whose seeds it skips) without prompting. A restarted Engine starts empty, so the next --keep-data deploy seeds it instead of merging (see below).

Work against it

After a deploy to the Engine, it is the backend this project tracks. These commands reach it with no flag and no Xano account:

npx xanosdk status           # which backend this project is tracking
npx xanosdk test run-all     # the Engine's tests (exits 5 on a failure)
npx xanosdk tables           # its tables: id, guid, name
npx xanosdk env pull         # its env values, into xano/.env

To reach the Engine from a project that last deployed elsewhere, name it: local, or local:<name> for another Engine from xanosdk local list (for example xanosdk test run-all --on local). A script that calls the meta API needs the Engine’s own bearer. xanosdk local token prints it on stdout, so it works in a subshell:

export XANO_META_TOKEN=$(npx xanosdk local token)

--json adds the Engine’s URL and workspace id. A restart mints a new bearer, so read it again after one. The bearer is never written to disk or printed in a deploy summary.

Manage engines

An Engine has no expiry, and nothing on a server reclaims it. These commands see and stop them. Each Engine is named after its project’s path (xanosdk- plus 12 hex characters), and token, mcp and update default to this project’s Engine.

Command	What it does
`xanosdk local list`	Every Engine running on this machine, marking the ones `xanosdk` started.
`xanosdk local token [name]`	Prints an Engine’s meta API bearer. `--json` adds its URL and workspace id.
`xanosdk local mcp [name]`	Prints how a coding agent connects to the Engine’s MCP server.
`xanosdk local stop [name]`	Stops one Engine. `--all` stops every Engine `xanosdk` started, across projects.
`xanosdk local update`	Moves this project’s pin to the latest Engine (`--version <v>` for one) and restarts it.
`xanosdk local cache list`	Each cached Engine version, its size on disk, and the Engines running on it.
`xanosdk local cache clear`	Removes every cached version (`--version <v>` for one). Engines on a removed version are stopped first.

Run a different Engine without moving the pin

To try an experimental build, or a published version the project has not moved to, override the pin for your own runs:

npx xanosdk deploy ./xano/index.ts --local=v0.1.16    # one deploy
export XANOSDK_ENGINE_OVERRIDE=~/Downloads/engine-experimental.tar.gz
npm run xano:deploy                                   # every deploy in this shell
unset XANOSDK_ENGINE_OVERRIDE                         # back to the pinned version

An override takes a version, an https URL to an Engine archive, or a path to one. The flag beats the variable, and the variable beats the pin. An override never reads or writes the pin and never checks for updates. Plain http:// is refused unless the host is this machine. Two more variables apply to overrides and release lookups:

XANOSDK_ENGINE_TOKEN is sent only to an override URL’s host, for a private archive.
XANOSDK_ENGINE_RELEASES_URL points version lookups at a different Engine release service. Its Engines download fresh on every deploy, and xanosdk local update refuses while it is set.

All of these are in Environment variables.

Disk use

Engine binaries and the runtime data a running Engine keeps (unpacked runtime files, logs, records of running Engines) live in ~/.xanosdk/local-engine. Set XANOSDK_ENGINE_HOME to move it. Expect roughly 600 MB after the first deploy, and a similar amount for each Engine version you run.

npx xanosdk local cache list     # each version and its size
npx xanosdk local stop --all     # stop every Engine xanosdk started
npx xanosdk local cache clear    # remove every cached version; the next deploy fetches again

Where the Engine differs today

The Engine is the same backend as an ephemeral. Three gaps change a command you run today:

You cannot cut a release from the Engine. xanosdk release create refuses it by name, because a release is cut on your Xano instance. Deploy to an ephemeral first, then cut the release from there:
npx xanosdk deploy ./xano/index.ts --ephemeral --test # deploy to an ephemeral, then run its tests npx xanosdk release create v1.4.0 # cut from that ephemeral
You can also stage on a Xano branch of your workspace and cut from it with xanosdk release create v1.4.0 --from workspace --branch <label>. See Releases.
There is no Engine build for Windows or Intel Macs. The Engine runs on macOS (Apple silicon) and Linux (x64, arm64). On any other platform a deploy to the Engine is refused before anything compiles. Use npm run xano:deploy:ephemeral to deploy to an ephemeral instead.
An Engine update or restart starts it empty. Rows do not survive xanosdk local update, a version change, or a restart. The next --keep-data deploy seeds the Engine instead of merging. Treat rows on the Engine as scratch data.

Connect your coding agent to the Engine: Engine MCP server.
Put the same backend in Xano’s cloud: Ephemerals.
Every flag on deploy and local: CLI reference.

Get started

Build

Run locally

Deploy to Xano

Govern

Use with AI tools

Help

Deploy to the Engine

Your frontend follows the deploy

Commit the pin

Keep your rows between deploys

Work against it

Manage engines

Run a different Engine without moving the pin

Disk use

Where the Engine differs today

Next

​Deploy to the Engine

​Your frontend follows the deploy

​Commit the pin

​Keep your rows between deploys

​Work against it

​Manage engines

​Run a different Engine without moving the pin

​Disk use

​Where the Engine differs today

​Next

Deploy to the Engine

Your frontend follows the deploy

Commit the pin

Keep your rows between deploys

Work against it

Manage engines

Run a different Engine without moving the pin

Disk use

Where the Engine differs today

Next