Skip to main content
A branch demo runs a branch’s already-built container images in their own isolated namespace on your organisation’s staging cluster, and stops itself when the timer runs out. Use it to show work in progress, reproduce a bug against a specific build, or hand a reviewer a live URL instead of a screenshot.
Pull requests get previews automatically. This guide covers the manual path: the Launch a branch demo dialog on an application’s Demos tab, and its CLI and MCP equivalents.

​
Prerequisites

1

Connect the repository as an application

The branch must belong to a connected application. Application setup adds the canonical build-and-publish workflow, which is what pushes the image a demo deploys.
2

Set the organisation's staging cluster

An admin sets it under AI → Settings → Workspaces. Every demo lands there. Without it, there is nowhere to launch.
3

Build the branch at least once

A demo deploys an image, it does not build one. Push the branch so the workflow publishes a tag for it. If nothing was ever published, the dialog offers Fix the build.
4

Optional: a demo base domain for HTTPS

Without one, demos are served over the staging cluster’s own Ankra zone (*.ankra.cc by default, or the Ankra domain your organisation selected) on plain HTTP, or stay in-cluster-only.

​
Launch a demo

Open the application, go to the Demos tab, and choose Launch demo.

​
Staging cluster capacity

The panel at the top of the dialog reports the staging cluster’s live headroom - nodes ready, CPU and memory in use, pod count, and how many demos are already running - and highlights a figure in amber once it passes 90% of capacity. It is informational: a busy cluster does not block the launch, but it tells you whether your pods will actually get scheduled. Each demo namespace carries its own hard ResourceQuota, so one demo can never exhaust the cluster:

​
Branch

Pick the branch to demo. The list marks the application’s configured build branch and the repository default branch. As soon as you pick one, Ankra checks the registry for a matching image and reports the verdict inline:

​
Components (monorepos only)

A single-app repository has nothing to choose. A monorepo shows every deployable component with its own build status and tag, and all of them deploy by default - each as its own pod in the one namespace, so a frontend and its API come up wired together instead of half an application answering where the other half belonged.
  • Untick a component to leave it out of this launch. At least one must stay ticked.
  • The web entry owns the demo’s URL root. Ankra marks the component its heuristic picked; set as entry moves the badge to another one.
  • Path badges on the remaining components show where they are published under the same host, so in-cluster callers and the browser reach the same demo.
The container port prefill follows the web entry, and the launch is blocked until every ticked component has an image (or you supply an image tag override, which applies to all of them).

​
Stop automatically after (hours)

The teardown timer. It is pre-filled with the organisation’s default demo TTL and capped by your role’s limit, which admins set per role (admin, operator, member) under AI → Settings → Workspaces. The field states your own ceiling. When the timer expires the namespace is deleted; nothing survives it.

​
Environment and database

Expand Environment & database to set variables for this launch only. Add variable adds a row - a name, a value, and a Secret checkbox. Values marked secret are stored as Vault-backed Ankra secret slots and mounted as a Kubernetes Secret at deploy time; the plaintext never persists in the application’s configuration. Toggle Attach a throwaway Postgres and an ephemeral pgvector-capable Postgres is provisioned inside the demo namespace with a per-demo random password, then destroyed with it. Nothing is injected automatically, because every codebase names its configuration differently - reference the placeholders in your own variable values instead: With the toggle on, the editor offers quick-add buttons for the common names (DATABASE_URL and friends) already wired to the right placeholder.
Everything in this section applies to this launch only. To give every demo of the application the same configuration - manual launches, CLI and MCP deploys, and the automatic PR previews - set it once as the application’s demo defaults behind the gear button on the Demos tab. Per-launch values win by name. Full reference: environment variables and a throwaway database.

​
Advanced options

​
Full-stack demos

When the application designates a stack profile for demos, the dialog says so before you launch. That launch also instantiates the profile as a demo-scoped Stack in the same namespace - dependencies, add-ons, and manifests included - and tears the whole thing down with the demo. The per-demo quota rises to the full-stack row in the table above. Configure the designation in the Demos tab settings. The Demos tab also names that profile and lists the profile’s own live demos, each one linking straight to its details. A profile can be demoed on its own - the same stack, without an application in front of it - which is usually a cheaper way to look at it than launching a whole application demo. See Stack Profile Demos.

​
Reach the running demo

Launching drops you back on the Demos tab, which lists every active demo with its status, preview URL, and remaining TTL. Each demo has a detail page carrying live provisioning progress read from the staging cluster, the namespace’s bill of materials, Kubernetes events, and pod logs. How you reach it depends on DNS:
  1. An organisation demo base domain, if configured, wins outright: <namespace>.<demo-base-domain>, with your ingress class and TLS secret.
  2. Otherwise the staging cluster’s delegated Ankra DNS zone, when active: <namespace>.<cluster-id>.<org-id>.<ankra-domain> over HTTP (ankra.cc by default, or the Ankra domain your organisation selected).
  3. Otherwise in-cluster only - the demo still runs, and the detail page gives you the service DNS name and a ready-made kubectl port-forward command.
The full resolution order is documented under the preview URL.

​
From the CLI and the AI Assistant

The deploy response includes preview_url when a public host was resolved.

​
No built image for this branch

When the registry holds nothing for the branch, the dialog does not dead-end. It offers, in order of effort:
  • Recent image tags from the same repository as one-click chips - handy for demoing the last good build while a new one is still running.
  • Fix the build, which diagnoses why no image exists and applies the safe fixes it can: restarting a failed application setup, repairing publish readiness, or re-running the latest workflow so it can push to the registry. When the deterministic fixes cannot unblock it, Ankra dispatches an agent mission and links you to its run so you can watch the work.
  • Open CI/CD, which jumps straight to the application’s pipeline runs.

​
Stopping a demo

A demo stops itself when its TTL expires - namespace deleted, quota released, database gone. Stop one early from the Demos tab, with ankra application demo stop, or with the demo_stop tool. There is nothing to clean up afterwards.
Demo namespaces are ephemeral by design. The throwaway database starts empty on every deploy and is wiped with the namespace - run your migrations on boot and never point a demo at data you care about.

​
Troubleshooting