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

# Agent guardrails

> Decide which Xano SDK commands a coding agent may run on its own and which wait for your approval, give it checks that fail loudly with export --strict and preflight, and have it read --json documents and exit codes instead of terminal text.

A coding agent writes your backend and runs most of the loop itself. The line to draw is between
what touches only a backend nobody else uses and what changes something real. The Xano SDK makes
that line visible: every command that reaches your workspace or a tenant names it on the command
line, and a bare `deploy` never reaches either.

## What an agent runs unattended

These write only to the Xano Engine on your machine or to this project's own ephemeral, or write
nothing at all:

| Command | What it touches |
| - | - |
| `npm run xano:deploy` | The Xano Engine on your machine. |
| `npx xanosdk deploy ./xano/index.ts --ephemeral --test` | This project's ephemeral, then its tests. |
| `npx xanosdk test run-all` | Runs the tests on the backend this project last deployed to. |
| `npm run xano:check` | Nothing. Typecheck and `export --check --strict`. |
| `npx xanosdk export ./xano/index.ts --strict` | Writes the bundle and the lock locally. |
| `npx xanosdk workspace diff ./xano/index.ts` | Nothing. Reads the workspace and compares. |
| `npx xanosdk release list`, `tenant list`, `workspace branch list` | Nothing. Reads. |
| `npx xanosdk preflight ./xano/index.ts` | A throwaway environment it creates for the run. |

## What waits for your approval

These change your workspace, a tenant, or the stored releases your team ships from. Have the
agent propose the command and stop:

| Command | Why it waits |
| - | - |
| `release create` | Stores a release that `promote` and `tenant deploy` can land. A name is used once. |
| `promote` | Lands on your workspace. A table change reaches live as it lands. |
| `workspace branch set-live`, `promote --set-live` | Changes what your users are served. |
| `tenant deploy` | Replaces what a tenant serves, and drops tables the release does not carry. |
| `deploy --to workspace`, `deploy --to tenant:<name>` | Merges into a real backend, and can prune or replace. |
| `publish --to workspace`, `publish --to tenant:<name>` | Replaces the frontend your users load. |
| `env set`, `env unset` with `--to workspace` or `--to tenant:<name>` | Changes a value a running backend reads. |
| `pull` | Rewrites the files in `xano/`. |

The scaffolded `AGENTS.md` already tells the agent to leave `pull`, `promote`,
`deploy --to workspace`, `tenant deploy` and `local update` to you unless you ask. Add the rest
of this table to your own notes in that file, outside the managed block, so every agent that
opens the project reads the same rules. [Coding agents](/ai/coding-agents)
covers the file.

The strongest guardrail is credentials. An agent session signed in only for ephemerals still
reaches your workspace, because an ephemeral lives under it. Keep the release commands in
[CI](/govern/ci-cd), behind a GitHub environment with required reviewers, and the approval is a
button rather than a promise.

## Checks that fail loudly

An agent reads a failure far more reliably than a warning, so give it checks that fail:

* **`export --strict`** turns every export warning into a failure: a data-losing shape, a filter
  that cannot resolve, an `env()` outside the declared set. `npm run xano:check` already passes it.
* **`preflight`** imports the backend into a throwaway environment on a live instance and diffs
  each object back, so a shape that compiles but does not round-trip fails before any release.
  It signs in separately, with `XANO_VALIDATE_INSTANCE` and `XANO_VALIDATE_TOKEN`
  (see [Environment variables](/reference/environment-variables)).
* **`deploy --ephemeral --test`** exits `5` when a test fails and `6` when the tests cannot be
  reached. The deploy stays in place either way, so the agent checks the code before it reports
  success.

## Read JSON and exit codes, not text

Every command prints a JSON document when stdout is not a terminal, and `--json` forces it.
A failure carries `ok: false` and an `error` with a stable `code`, such as
`SDK_SHARED_SCHEMA_CHANGE`. Tell the agent to branch on the exit code and on `error.code`, never
on the wording of a message.

| Exit | Tells the agent |
| - | - |
| `0` | Done. |
| `1` | An ordinary failure: fix the cause and try again. |
| `2` | A refusal or a disagreement. Running it again changes nothing; report it. |
| `5`, `6` | Tests failed, or could not be reached. |
| `8` | The backend is gone, stopped or unreachable. |
| `9` | The outcome is unknown. Run `resolveWith`; never retry blind. |

`--yes` waives a confirmation, never a refusal. An agent that adds `--yes` to get past an exit
`2` gets the same exit `2`. [Exit codes and outcomes](/help/exit-codes-and-outcomes) lists every
code.

## Next

[Coding agents](/ai/coding-agents): install the agent skill and keep `AGENTS.md` current.


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