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

# Ephemeral Tenants

> Create short-lived, auto-expiring tenants for previews, CI, and parallel testing

export const BrowserFrame = props => {
  const {url = "xano.run", maxWidth = 820, className = "", lightSrc, darkSrc, alt = "", children} = props || ({});
  const style = typeof maxWidth === "number" ? {
    maxWidth: `${maxWidth}px`,
    margin: "16px 0"
  } : {
    maxWidth,
    margin: "16px 0"
  };
  const hasSwapImages = Boolean(lightSrc && darkSrc);
  return <div className={`browser-frame ${className}`.trim()} style={style}>
      <div className="browser-frame__top">
        <div className="browser-frame__controls" aria-hidden="true">
          <span className="browser-frame__dot browser-frame__dot--red" />
          <span className="browser-frame__dot browser-frame__dot--yellow" />
          <span className="browser-frame__dot browser-frame__dot--green" />
        </div>
        <div className="browser-frame__address">{url}</div>
      </div>

      <div className="browser-frame__body">
        {hasSwapImages ? <>
            <img className="browser-frame__img--light" src={lightSrc} alt={alt} />
            <img className="browser-frame__img--dark" src={darkSrc} alt={alt} />
          </> : children}
      </div>
    </div>;
};

An ephemeral tenant is a short-lived, auto-expiring [tenant](/xano-cli/tenants) scoped to a workspace. Each one is a real, database-isolated environment with its own database, environment variables, and configuration — but it deletes itself when its timer runs out. Spin one up for a pull-request preview, a CI run, or a throwaway experiment, and let it clean itself up.

<Note>
  **Building only inside the Xano product today?** Ephemeral tenants are created from the CLI, so you'll need it set up first. See [Build from your Local Agent](/getting-started-ai) to get started with agentic development — installing the CLI, connecting the Developer MCP, and pulling your workspace — then come back here.
</Note>

<Info>
  **Ephemeral tenant vs. [sandbox](/xano-cli/sandbox)**

  Both give you a database-isolated place to push and test changes, but they solve different problems:

  |          | Ephemeral tenant                       | Sandbox                                    |
  | -------- | -------------------------------------- | ------------------------------------------ |
  | Scope    | Belongs to a workspace (requires `-w`) | One per user, workspace-agnostic           |
  | Count    | Many in parallel                       | Exactly one                                |
  | Lifetime | Auto-expires (1–24h)                   | Persists until you `reset` or `delete` it  |
  | Best for | PR previews, CI, parallel runs         | Personal iteration and review-then-promote |

  Use a sandbox for personal, review-driven iteration; use ephemeral tenants when you need several disposable environments at once or an environment that tears itself down.
</Info>

## Use Cases

<CardGroup cols={3}>
  <Card title="Agentic development" icon="robot" href="/getting-started-ai">
    Give an AI coding agent somewhere to push, run, and verify its work — several agents at once, each in its own tenant, none of them touching your live workspace.
  </Card>

  <Card title="CI/CD and PR previews" icon="code-branch" href="/ci-cd">
    Create a fresh environment per pipeline run or pull request, test against real records and environment variables, then share a read-only preview link. It expires on its own, so there is no cleanup step.
  </Card>

  <Card title="Experiments and PoCs" icon="flask" href="/xano-cli/guide-from-scratch">
    Build a proof of concept locally, then push it to a real running environment to see whether the idea holds. The timer deletes it when you're done — nothing to tear down, nothing left behind in your workspace.
  </Card>
</CardGroup>

## Create

Create an ephemeral tenant with a display name. The workspace is required — pass `-w` or set one in your profile.

<BrowserFrame url="Terminal">
  ```bash theme={null}
  xano ephemeral create "PR preview"
  xano ephemeral create "Demo" --expires-hours 24 -w 5
  xano ephemeral create "Load test" -d "overnight soak" --expires-hours 24
  ```
</BrowserFrame>

| Argument / Flag     | Description                                                  |
| ------------------- | ------------------------------------------------------------ |
| `display`           | Display name (required, positional)                          |
| `--expires-hours`   | Hours until the tenant auto-expires, `1`–`24` (default: `1`) |
| `-d, --description` | Tenant description                                           |
| `-w, --workspace`   | Workspace ID (uses profile workspace if not set)             |
| `-o, --output`      | Output format: `summary` or `json`                           |

The command prints the new tenant's name and expiry. Use `-o json` for the full response.

<Note>
  `--expires-hours` is capped at **24**. There is no non-expiring ephemeral tenant — for a long-lived environment, use a regular [tenant](/xano-cli/tenants) or [workspace](/xano-cli/workspaces-and-branches) instead.
</Note>

***

## List

List the ephemeral tenants in the current workspace, or across every workspace you can access with `--global`.

<BrowserFrame url="Terminal">
  ```bash theme={null}
  xano ephemeral list
  xano ephemeral list -w 5
  xano ephemeral list --global
  ```
</BrowserFrame>

| Flag              | Description                                                       |
| ----------------- | ----------------------------------------------------------------- |
| `--global`        | List ephemeral tenants across the whole instance (all workspaces) |
| `-w, --workspace` | Workspace ID (uses profile workspace if not set)                  |
| `-o, --output`    | Output format: `summary` or `json`                                |

***

## Get & Edit

Retrieve one tenant's details, or update its display name and description.

<BrowserFrame url="Terminal">
  ```bash theme={null}
  xano ephemeral get TENANT_NAME
  xano ephemeral edit TENANT_NAME --display "New Name" -d "New description"
  ```
</BrowserFrame>

`edit` changes only the display name (`--display`) and description (`-d`); it does not extend the expiry. Both commands accept `-w` and `-o`.

***

## Pull & Push

Pull an ephemeral tenant's content down as local XanoScript files, or push local files up to it. This works the same way as [workspace pull & push](/xano-cli/push-pull), using the [multidoc](/xanoscript/multidoc) format — but targets the ephemeral tenant. Unlike a regular tenant, an ephemeral tenant **does** accept a direct push.

### Pull

<BrowserFrame url="Terminal">
  ```bash theme={null}
  xano ephemeral pull TENANT_NAME -d ./my-ephemeral
  ```
</BrowserFrame>

| Flag              | Description                                                        |
| ----------------- | ------------------------------------------------------------------ |
| `-d, --directory` | Output directory for pulled documents (default: current directory) |
| `--env`           | Include environment variables                                      |
| `--records`       | Include database records                                           |
| `--draft`         | Include draft versions of resources                                |
| `-w, --workspace` | Workspace ID                                                       |

### Push

By default, only changed files are pushed (partial mode). Push shows a preview and prompts for confirmation before applying anything — always run `--dry-run` first to inspect the change.

<BrowserFrame url="Terminal">
  ```bash theme={null}
  xano ephemeral push TENANT_NAME -d ./my-ephemeral --dry-run   # preview first
  xano ephemeral push TENANT_NAME -d ./my-ephemeral
  xano ephemeral push TENANT_NAME -d ./my-ephemeral --records --env
  ```
</BrowserFrame>

| Flag               | Description                                                                 |
| ------------------ | --------------------------------------------------------------------------- |
| `-d, --directory`  | Directory containing documents to push (default: current directory)         |
| `--dry-run`        | Show the push preview, then exit without applying                           |
| `--sync`           | Full push — send all files, not just changed ones (required for `--delete`) |
| `--delete`         | Delete remote objects not present locally (requires `--sync`)               |
| `--records`        | Include database records in import                                          |
| `--env`            | Include environment variables in import                                     |
| `--force`          | Skip the preview and confirmation prompt (for CI/CD)                        |
| `--wait`           | After pushing, wait for auto-deployed microservices to become ready         |
| `--wait-timeout`   | Seconds to wait when `--wait` is set (default: `300`)                       |
| `--truncate`       | Truncate all table records before importing                                 |
| `--no-guids`       | Skip writing server-assigned GUIDs back to local files                      |
| `--no-transaction` | Skip wrapping the import in a database transaction                          |
| `-w, --workspace`  | Workspace ID                                                                |

<Tip>
  In CI, combine `--force` (skip the interactive prompt) with `--wait`. With `--wait`, the command blocks until every auto-deployed microservice is ready and **exits non-zero** if any fails to deploy or the wait times out — so a failed deploy fails the pipeline step instead of passing silently. `--wait` is ignored with `--dry-run`.
</Tip>

<Warning>
  `--truncate` empties tables before importing, and `--no-transaction` disables the rollback safety net. Use them deliberately, and preview with `--dry-run` first.
</Warning>

***

## Impersonate

Open the ephemeral tenant's dashboard in your browser, or print the URL for scripting.

<BrowserFrame url="Terminal">
  ```bash theme={null}
  xano ephemeral impersonate TENANT_NAME
  xano ephemeral impersonate TENANT_NAME --url-only
  xano ephemeral impersonate TENANT_NAME --guest --url-only
  ```
</BrowserFrame>

| Flag              | Description                                                                      |
| ----------------- | -------------------------------------------------------------------------------- |
| `-g, --guest`     | Mint a read-only guest session (browse only; no schema, data, or config changes) |
| `-u, --url-only`  | Print the URL without opening the browser                                        |
| `-w, --workspace` | Workspace ID                                                                     |
| `-o, --output`    | Output format: `summary` or `json`                                               |

<Tip>
  `--guest --url-only` is the pairing for a **per-PR preview link**: it returns a read-only URL you can post as a comment so reviewers can browse the environment without being able to change it.
</Tip>

***

## Static Hosting

An ephemeral tenant can host static sites, scoped to that tenant. These commands mirror [`xano static_host`](/xano-cli/static-hosting) but take the tenant name as the first argument.

<BrowserFrame url="Terminal">
  ```bash theme={null}
  # List / create / inspect a tenant's static hosts
  xano ephemeral static_host list TENANT_NAME
  xano ephemeral static_host create TENANT_NAME --name marketing --description "Marketing site"

  # Builds: push a directory, list, deploy to an env
  xano ephemeral static_host build push TENANT_NAME -H default -d ./site
  xano ephemeral static_host build list TENANT_NAME -H default
  xano ephemeral static_host deploy TENANT_NAME -H default --build_id 52 --env prod
  ```
</BrowserFrame>

<Note>
  Static hosting is currently available for **local** tenants. Remote (tier2/tier3) tenants are not yet supported and will return an error.
</Note>

***

## Delete

Delete an ephemeral tenant immediately, rather than waiting for it to expire.

<BrowserFrame url="Terminal">
  ```bash theme={null}
  xano ephemeral delete TENANT_NAME
  ```
</BrowserFrame>

Add `-f` to skip the confirmation prompt (for CI/CD).

<Warning>
  Deleting an ephemeral tenant destroys all associated infrastructure and data. This cannot be undone. (An ephemeral tenant is also destroyed automatically when its `--expires-hours` window elapses.)
</Warning>

***

## Typical Workflow

A common pattern for standing up a disposable environment, verifying it, and sharing a preview:

<Steps>
  <Step title="Create the environment">
    <BrowserFrame url="Terminal">
      ```bash theme={null}
      xano ephemeral create "PR #482 preview" --expires-hours 4 -w 5
      ```
    </BrowserFrame>

    Note the tenant name it returns — you'll use it below.
  </Step>

  <Step title="Push your code and wait for deploy">
    <BrowserFrame url="Terminal">
      ```bash theme={null}
      xano ephemeral push TENANT_NAME -d ./my-workspace --dry-run   # preview
      xano ephemeral push TENANT_NAME -d ./my-workspace --records --env --force --wait
      ```
    </BrowserFrame>
  </Step>

  <Step title="Test against the live environment">
    The tenant is now serving real API requests. Point your test suite or API checks at its endpoints, exactly as you would any deployed environment.
  </Step>

  <Step title="Share a read-only preview">
    <BrowserFrame url="Terminal">
      ```bash theme={null}
      xano ephemeral impersonate TENANT_NAME --guest --url-only
      ```
    </BrowserFrame>

    Post the returned URL for reviewers. The tenant tears itself down when its timer expires — no cleanup step required.
  </Step>
</Steps>

<Tip>
  An ephemeral tenant is for **verifying** a change, not shipping it — nothing is copied from a tenant to production. Once an experiment proves out, promote it through your normal release process: push the same local files back to a workspace, or deploy them to a tenant, depending on how your team ships. See [CI/CD](/ci-cd) for the end-to-end release flow.
</Tip>


## Related topics

- [Tenants](/xano-cli/tenants.md)
- [Build from your Local Agent](/getting-started-ai.md)
- [Sandbox Testing](/testing-debugging/sandbox.md)