> ## Documentation Index
> Fetch the complete documentation index at: https://sdk.docs.xano.com/llms.txt
> Use this file to discover all available pages before exploring further.

# The Xano Engine

> Run your backend on the Xano Engine on your machine: the first deploy, the version pin in package.json, keeping rows between deploys, the local commands, overrides, disk use, and where the Engine differs today.

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](/run/ephemerals) in Xano's cloud.

## Deploy to the Engine

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

```bash theme={null}
npm run xano:deploy                          # scaffolded project
npx xanosdk deploy ./xano/index.ts --local   # any project; --local is the default, spelled out
```

<Note>
  **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](/start/connect-to-xano)). See
  [where the Engine differs today](/run/xano-engine#where-the-engine-differs-today).
</Note>

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](/run/engine-mcp).

### 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](/run/frontend-hosting).

## Commit the pin

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

```json theme={null}
{
  "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](#where-the-engine-differs-today)).

## 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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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](/reference/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.

```bash theme={null}
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:

1. **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:

   ```bash theme={null}
   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](/ship/releases).
2. **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.
3. **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.

## Next

* Connect your coding agent to the Engine: [Engine MCP server](/run/engine-mcp).
* Put the same backend in Xano's cloud: [Ephemerals](/run/ephemerals).
* Every flag on `deploy` and `local`: [CLI reference](/reference/cli/index).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.