Applications

Applications take you from source code to a deployable workload. Connect an application’s Git repository and Ankra analyzes it, generates the packaging it’s missing, and opens a pull request in your repository. Once merged, CI builds and publishes a container image that you can deploy to a cluster.

Applications connect to GitHub repositories and use a GitHub credential. By default the generated CI/CD pipeline pushes the container image to your organisation’s private Ankra registry; if you already run your own registry, declare it and Ankra publishes to and reads from it instead.

No repository yet? A Claude Design export can be imported straight into an application: Ankra converts the artboards into a static site, creates the GitHub repository, commits it with a Dockerfile and registers it, and the same setup pull request, build and deploy lane follows. See From Claude Design to a live application.

Watch a repository go from source to a live URL with one command.

How it works

Connect a repository

Provide a name and a GitHub credential, then pick the repository and a branch from the repository’s own branch list - the default branch is preselected, and Enter a different branch lets you type one that does not exist yet.

Analyze and generate

Ankra inspects the repository, detects the language and framework, and generates the artifacts it needs: a Dockerfile, Kubernetes manifests, and a CI/CD workflow.

Merge the pull request

Review and merge the PR. Merging activates the CI/CD pipeline in your repository.

Build and publish

CI builds and pushes the container image to the organisation’s private Ankra registry. Ankra surfaces the image URL and scans the published image.

Deploy

Deploy the application onto a cluster. Ankra verifies that the image was published and tracks the rollout.

Building on Ankra’s builders

The flow above puts the first image behind a merged pull request: until the generated workflow is on your default branch, your CI has nothing to run, and nothing to publish. Ankra can also build the image itself, on its own builders, with no workflow in the repository at all. Ankra clones the commit, resolves a recipe for it, builds it, and pushes the image to the same registry the application publishes to. The recipe is the first of these that fits:

The repository’s own Dockerfile — used as-is.
A generated Dockerfile — the one Ankra wrote for this application.
Buildpacks — when there is no Dockerfile to use.

No Actions minutes are spent, no runners need operating, and no registry credentials go anywhere near the repository.

# Queue a build and follow it to a result
ankra application build start <application-id> --commit <full-sha> --ref main --wait

# Read what the builders did
ankra application build list <application-id>
ankra application build get <application-id> <build-id>

Reach for this when the repository’s own CI cannot do the job — a private repository on a plan whose Actions never leave the queue, a first image needed before anyone merges the setup PR, or an unattended caller with no browser to click through.

--commit takes a full 40- or 64-character commit sha. The queue deduplicates on the string it is given, so an abbreviation would be a second key for the same commit and would build it twice. Asking twice for one commit joins a single build rather than racing two, and the answer’s already_requested says when that happened.

Following a build

A request is not yet a build. start answers with a request id immediately; the build itself is created when a builder claims the request. So there are two things to read:

# The queued ask - pending until claimed, then it names its build
ankra application build request <application-id> <request-id>

# The build itself
ankra application build get <application-id> <build-id>

ankra application build start --wait walks both steps for you and exits non-zero if the build failed, which makes it usable as a pipeline gate. Watching the build list instead is a trap: a previous failed build of the same commit is still the newest one for that commit, so it would report an old failure as your build’s result.

Waiting for a builder

Ankra’s builders are one pool that every organisation shares. Your organisation runs at most three builds on it at a time, so a burst of builds from one organisation - onboarding a repository with many components, say - cannot hold every builder while others wait. Requests beyond three stay pending, in the order they were made, and the next one starts as soon as one of your running builds finishes. A pending request is waiting its turn, not failing: it keeps its request id, and --wait keeps following it.

What a failure means

A failed build carries an error_class that says whose failure it was:

`error_class`	Whose	What to do
`build_failed`	Yours	The recipe did not build. Read `error_message`.
`clone_auth`	Yours	Ankra could not clone the repository — check the application’s Git credential.
`recipe_missing`	Yours	No Dockerfile and no buildpack matched the repository.
`push_failed`	Ankra’s	The image built but could not be pushed.
`timeout`	Ankra’s	The build exceeded its budget.
`capacity`	Ankra’s	No builder was running to take the build.

The last three are platform-side and are already visible to Ankra without anyone reporting them.

This replaces the image build, not the whole generated pipeline. That workflow also runs a Semgrep scan, and packages a Helm chart for applications that publish one. If you plan to retire the workflow entirely, decide where those two go first.

The application workspace

An application opens as a workspace: a context sidebar beside the main one, in the order the work happens, with one page per section at /organisation/applications/<application-id>/<section>. A link to an older ?tab= address redirects to its section.

Section	What it shows
Overview	Where the application is right now: the setup journey, the environments it is live in, and the latest run.
Pipelines	Run history as one lane per run, with skipped and cancelled runs grouped on their own. Stages fold into phases decided by each stage’s kind, so a long pipeline reads as a handful of things you can name; a kind the grouping does not know yet sits under Other steps. A run opens as its own sheet - logs, the failed step and its exit code, the artifact and the commit - with the suggested fix separate from the rerun.
Deployments	One installation per row: the cluster and its environment label, the owning add-on or stack, the version it serves, health and the reported address. A version that differs between installations is shown as a difference, not called drift. A field the read does not carry reads unknown, never zero, and the installation sheet links to the owning add-on for namespace, pods, events and logs rather than pretending to show them.
Previews	What the CLI and API call demos. One card per preview with its branch or commit, component, image, expiry, access (browser URL, in-cluster only, URL not live, or not reachable yet) and the staging cluster, plus the launch dialog and the environment template. See Preview demos.
Security	Eight views over the application’s scan reports, ranked by exploitability. See Security scanning.
Environment	The secret keys the application reads, each with three independent states: stored (Set, No value, Value missing), consumed (Manifests or Not referenced) and its deployment state. Only a stored key the manifests reference inherits the application-wide apply answer; a key nothing references reads Stored only, a key with no value Nothing to apply, a lost value Cannot apply. Values are never displayed - the API has no route that returns one. Ordinary, non-secret variables are not available for applications yet.
Source & config	The files Ankra wrote: the file tree, the editor, pending changes per file and in total, and the commit message with Push to PR. The editor says whether it is showing the setup branch or the generated set, and why the branch is not showing when it is not.
Settings	The repository, branch and component paths setup ran against (read-only), delivery per environment, the image registry, publishing the application as an add-on, running setup again, and delete last.

The sidebar carries two badges: Security shows the CISA-listed finding count once the KEV catalog has synced, and never before; Environment shows the declared keys still without a value. The Applications list has two ways in: All applications, or Needs attention - a failed setup, an unmerged setup pull request, a failed deploy or a degraded one. Setup in progress, deploying, parked, resting, and a runtime Ankra could not read are not attention.

What Ankra tracks

For each application you see:

State and analysis status - where the application is in the connect/analyze/generate/build lifecycle, with an error message if something needs attention.
Repository - owner, name, branch, and URL.
Components - the repository’s deployable apps. An ordinary repository has one; a monorepo has one per app.
Artifacts - the private container image URL and the latest published build, per component.
Pull request - a link to the generated PR.
Jobs - the underlying platform jobs for the application, so you can follow analysis and generation as it runs.

Monorepos

A repository that builds more than one deployable app is onboarded as a monorepo: Ankra records one component per app, and each component gets its own packaging and its own image.

Per component	Where it lives
Dockerfile	`<component-directory>/Dockerfile`
Kubernetes manifests	`.ankra/manifests/<component>-*.yaml`
Build workflow	`.github/workflows/<component>-build-and-publish.yml`, with a `paths:` filter scoped to the component’s directory so touching one app does not rebuild the others
Container image	`<your-registry-project>/<repository>/<component>`

Ankra decides the components from, in order: the per-component workflows the repository already carries (so re-running analysis never renames a component and orphans the images it has published), the apps the analysis proposed, then the repository’s structure - two or more Dockerfiles in subdirectories and no Dockerfile at the root, or a workspace marker (nx.json, turbo.json, lerna.json, pnpm-workspace.yaml, go.work) plus two or more subdirectories with their own dependency manifest. A Dockerfile at the repository root always means a single app, whatever else the repository contains. Build state, published images, deploys, demos, and container scanning are all reported per component, so an application whose API component built and whose frontend did not says exactly that.

Using your own registry

An application publishes to your organisation’s private Ankra registry unless you say otherwise. If you already operate a registry - the same Harbor whose OCI charts Ankra indexes, for instance - declare it on the application and Ankra publishes there, reads the published tags back from there, and pulls from there. Declare it on an existing application from Settings → Image registry, from the CLI, or with image_registry when you create the application. The settings panel also reports the host and project the declaration resolved to and the image repository each component is expected to publish to, so you can compare them against where your builds actually push.

# Show the effective registry and the expected repositories
ankra application registry get <application-id>

# Declare a registry you operate
ankra application registry set <application-id> \
  --url oci://artifact.example.com/commerce-images \
  --credential example-harbor-pull

# Go back to your organisation's own Ankra registry
ankra application registry clear <application-id>

The same declaration at create time:

{
  "name": "commerce",
  "app_repo_credential_name": "github",
  "app_repo_owner": "smartoptics-dwdm",
  "app_repo_name": "commerce",
  "image_registry": {
    "url": "oci://artifact.example.com/commerce-images",
    "credential_name": "example-harbor-pull",
    "pull_secret_name": "harbor-registry",
    "username_secret_name": "HARBOR_USERNAME",
    "password_secret_name": "HARBOR_PASSWORD"
  }
}

Field	Meaning
`url`	The registry project images publish to, as `oci://<host>/<project>`. A deeper path becomes a prefix every component’s repository nests under.
`credential_name`	An existing registry credential of the organisation - the same credential resource your chart registries authenticate with. Ankra reads published tags and builds the cluster pull secret from it.
`api_url`	Optional. The registry’s management API base; defaults to `https://<host>`, which is where a Harbor serves its own API.
`pull_secret_name`	Optional. The `kubernetes.io/dockerconfigjson` Secret the generated manifests reference through `imagePullSecrets`. Defaults to `ankra-registry-pull`.
`username_secret_name` / `password_secret_name`	Optional. The repository Actions secrets the build workflow logs in with. Default to `ANKRA_REGISTRY_USERNAME` / `ANKRA_REGISTRY_PASSWORD`.
`admin_credential_name`	Optional. A registry credential with project administrator rights on the project (or a robot granted the robot-account permissions). Setting it hands robot management on your registry to Ankra: it mints, rotates and revokes a push robot for the application with it. See Robot accounts.
`manage_actions_secrets`	Optional, default `false`. See below.
`component_repositories`	Optional. The repository inside the project for a component, keyed by component name - `{"backend": "commerce-backend"}` publishes the backend at `<project>/commerce-backend` - for a registry whose layout follows neither Ankra’s nesting nor the flat component name. Unnamed components keep the derived path. CLI: `--component-repository backend=commerce-backend` (repeatable); portal: one field per component under Settings → Image registry.
`flat_repositories`	Optional, default `false`. Publish a monorepo’s components straight under the project - `<project>/<component>` - instead of Ankra’s `<project>/<app>/<component>`. Turn it on when the registry already holds the images that way, so publish readiness, the deploy gate and the generated workflows all address the repositories your pipeline already pushes to. Single-component applications are unaffected.

Ankra does not mint robots for a registry you operate unless you hand it the keys. With a declared registry and no admin_credential_name, setup names the two Actions secrets the workflow reads and leaves them to you, rather than writing a credential Ankra happens to hold over a push robot you administer. Publish readiness reports whether those secrets exist and names them. Name an admin_credential_name to have Ankra mint a push robot for the application there (Robot accounts), or set manage_actions_secrets: true to have it write the declared credential into them instead.

credential_name is what makes a declaration usable rather than merely descriptive. Without one Ankra records where the images live but cannot read their tags or pull them, so publish readiness, the demo build check and the deploy gate all keep reporting the application as never built - while it publishes healthily to a registry Ankra simply cannot see.

An application is bound to the GitHub credential it was created with; its App installation must reach the repository for builds, deploys and Actions secrets. Move an application onto another credential of the organisation with ankra application credential set <application-id> --credential <name> (GET/PUT /api/v1/org/applications/{application_id}/repository-credential); the answer reports whether the new binding resolves to an installation.

On a monorepo, a component may declare its own image_registry to publish into a different project of the same registry - useful when each app has its own robot accounts and retention rules. A component’s declaration wins over the application’s; the application’s applies to every component that declares none.

Publish readiness, the deploy gate, image tag listings, container scanning, and preview demos all resolve the declared registry, so an application whose images live outside Ankra reports what is actually published rather than staying blocked on an artifact that was never going to appear in Ankra’s own project. Running Harbor yourself? Harbor as your application registry covers the operator’s side: which credential does what, why the project-administrator credential must be a Harbor user rather than a project robot, how to check the minted robot from Harbor’s own API, and how the pull secret reaches every cluster and namespace the application deploys to.

Robot accounts

Every application gets a registry robot account of its own: a push+pull robot named robot$<project>+app-<application-id> on the project it publishes to, stored as the platform-managed registry credential ankra-harbor-app-<application-id> and written into the repository’s Actions secrets as the login the build workflow uses. Nothing else shares that login, so a leaked repository secret is rotated or revoked for that one application, and a deleted application takes its robot with it.

On your organisation’s Ankra registry the robot is minted automatically when the application is set up, and again whenever the application is reconciled. Applications onboarded before robots existed get one the first time Fix automatically runs in the Pipelines section, or when you create it from Settings → Image registry.
On a registry you operate, Ankra mints one only with a credential that may: set admin_credential_name to a registry credential with project administrator rights on the declared project (in Harbor, a project admin user, or a robot granted the robot-account permissions). Without it Ankra never touches your robots; publish readiness names the field.

The robot is shown - name, registry, when it was created and last rotated - under Settings → Image registry, where you can create, rotate or revoke it. Rotating refreshes the secret and rewrites the repository’s Actions secrets; the previous secret stops working the moment the registry answers. Revoking deletes the robot from the registry and drops its credential, leaving the repository’s secrets holding a login that no longer works.

# Show the application's robot
ankra application registry robot get <application-id>

# Mint one (or confirm the existing one) and write its login into the repository
ankra application registry robot ensure <application-id>

# Rotate its secret after a leak
ankra application registry robot rotate <application-id>

# Revoke it
ankra application registry robot revoke <application-id> --yes

# Let Ankra manage robots on a registry you operate
ankra application registry set <application-id> \
  --url oci://artifact.example.com/commerce-images \
  --credential example-harbor-pull \
  --admin-credential example-harbor-admin

The same is available on the API at /api/v1/org/applications/{application_id}/registry-robot (GET, POST with {"rotate": true|false}, DELETE). The robot’s credential appears in your organisation’s registry credentials as managed by Ankra; it cannot be edited or deleted there, only through the application.

Security scanning

Applications include code and container security insights, so vulnerabilities surface alongside the build rather than in a separate tool. The Security section reads the way the Security Center reads a fleet finding - risk first, ranked by exploitability - in eight views:

View	What it shows
Overview	Risk score, vulnerabilities, known exploited, last scan and scanners reporting, then First to review: the CISA-listed finding when the catalog is synced, the highest-severity one otherwise. An unscanned image reads Not assessed on every tile, never `0 / 10`; a pipeline configured but not yet built reads Waiting; a report older than two hours is marked stale.
CVEs & findings	Every finding, ranked by exploitability: CISA KEV listing first, then EPSS, then severity, then CVSS, with highest severity as the alternative order. A Known exploited filter narrows to CISA-listed findings, and a banner leads the table when any finding is listed.
KEV	One card per CISA-listed finding: date added, due date (overdue marked), ransomware use, EPSS, the fix, CISA’s required action, and where it runs.
SBOM	The package inventory of the selected image version - package and PURL, version, type, licence and tier, the CVEs on that version and the workloads it runs in - and the versions list with one row per pushed tag, its bill of materials, its findings and the CycloneDX and CSV downloads. Only versions with a bill of materials are selectable; nothing borrows another image’s inventory.
Compliance	Not available for applications yet; points at the organisation Security Center.
Coverage	Which scanner reported - Trivy, Semgrep, Checkov, bill of materials - and how fresh: fresh, stale after two hours, pending (configured, no build since), not configured, or unknown when the read failed.
Code and Infrastructure	The Semgrep and Checkov findings; a row opens with the file, lines, rule, category and the rule reference. Waiting for a first scan and zero findings are distinct states.

Every finding row opens a sheet with severity, CVSS, EPSS (as EPSS 94% · top 1%), the CISA KEV entry - date added, due date, ransomware use and required action - the fix, and a link to the platform’s own advisory page for the CVE. Exploitability reads Unknown until the KEV catalog has synced; absent is never read as not exploited. On a monorepo, the image tags and the scanned image reference follow the component you select; code and IaC findings cover the whole repository, because that is where those scanners run. Pair this with AI Insights for proactive analysis.

Preview demos

Before you merge, you can spin up a throwaway demo of a pull request or branch build to see it running. In the portal these live in the application’s Previews section, which calls each one a preview; the CLI and API keep the demo name. Each demo is deployed into its own isolated namespace (ankra-demo-pr-<n> or ankra-demo-br-<branch>) on the organisation’s staging cluster, PodSecurity-hardened and quota-bounded, and is automatically torn down when its TTL expires - so it can never affect existing workloads.

Configure a staging cluster

An admin sets the organisation’s staging cluster under AI → Settings → Workspaces. Optionally set a demo base domain (with an ingress class and TLS secret) there too - this is what gives demos a public URL.

Deploy a demo

Deploy a branch or PR demo from the application’s Previews section, from the CLI, or by asking the AI assistant. The demo pulls the image tag the PR/branch build pushed.

Open the preview

When a public host is available, Ankra returns a preview URL you can open directly. Otherwise the demo stays reachable in-cluster (service DNS + a kubectl port-forward command).

Two guides cover the two ways a demo starts: branch demos walks the launch dialog field by field, and PR preview environments covers the automatic per-pull-request flow.

The preview URL

Ankra resolves the demo’s public hostname automatically, and every surface (portal, CLI, MCP, and automatic PR previews) uses the same rule:

An organisation demo base domain, if configured, wins outright - the host is <namespace>.<demo-base-domain>, served with your configured ingress class and TLS secret.
Otherwise, the staging cluster’s own delegated DNS zone, but only when that zone is active - giving <namespace>.<cluster-id>.<org-id>.<ankra-domain>, a hostname the external-dns running on that cluster can resolve. When the cluster also carries the Ankra networking stack, the demo’s ingress requests a Let’s Encrypt certificate from its letsencrypt-prod issuer automatically, so the preview URL is served over https.
Otherwise the demo stays in-cluster-only - no ingress is created, and you reach it with the returned service DNS name and kubectl port-forward.

A demo only gets a resolvable public URL when the organisation has a demo base domain configured or the staging cluster has an active Ankra DNS zone. Without either, the demo still deploys - it just stays in-cluster-only.

The Ankra domain in rule 2 is ankra.cc by default. An organisation can register its own custom domain - dedicated to that organisation alone - in the Custom Ankra domain field under AI → Settings → Workspaces, or from the CLI with ankra org domain set <domain>. The domain must be a bare domain the organisation owns, its NS records must already point at Ankra’s nameservers (the ones serving ankra.cc), and no other organisation may hold it. With a custom domain registered, the external-dns Ankra runs on each of the organisation’s clusters is scoped to the whole domain, not just that cluster’s delegated <cluster-id>.<org-id>.<domain> zone. An Ingress on any hostname under the domain - a top-level name like app.example.com included - is published automatically by the cluster serving it. On the shared ankra.cc root the scope stays the cluster’s own delegated zone: names directly under ankra.cc are allocated by the platform, and one organisation’s cluster must never be able to write another’s. Zones already provisioned keep the domain they were minted under, so the switch is refused while any cluster DNS zone or DNS record still lives under the old domain. The refusal names exactly what is blocking it - the portal lists the cluster domains and records beside the field, and ankra org domain set prints the same list - so the migration is a checklist rather than a guess:

Inventory what is under the current root

ankra org dns zones lists every cluster domain in the organisation with its state; ankra org dns list lists the DNS records. Both are reads. In the portal the same two lists live under Organisation → Settings → DNS records.

Destroy any playground environment

A playground publishes a wildcard DNS record in the organisation’s zone, and that record is reconciled - the platform writes it again on its next pass over a ready environment, so deleting it in the next step will not clear it. Destroy the environment instead: ankra cluster playground destroy <cluster_id>. The refusal names any playground that is still holding a record.

Remove each cluster domain

ankra cluster domain <cluster> --remove (or DELETE /api/v1/clusters/{cluster_id}/dns-zone, or Remove on the cluster domain row in the portal) hands the zone to Ankra for teardown.The removal is held: nothing re-creates the zone until you ask for it back in the last step - not the external-dns Ankra runs on that cluster, and not the discovery that mints zones for clusters that have none. ankra cluster domain <cluster> reports Opted out: yes for as long as the hold stands, so a domain that is gone is distinguishable from one that is between reconciler passes.

Delete the DNS records

ankra org dns delete <record>, or delete them from the DNS records table. These are the records you created; anything the platform publishes is listed separately in the refusal, with what to remove instead.

ankra org domain set example.com, or save the Custom Ankra domain field. Ankra tears the organisation zone down and re-creates it under the new domain automatically.

Re-enable the cluster domains

ankra cluster domain <cluster> --enable withdraws the hold and re-creates each cluster’s zone under the new root, and the cluster’s external-dns picks up the new zone on its next cloud-provider stack pass. Every cluster you removed in step 3 needs this, the staging cluster included.

ankra cluster domain <cluster> on its own is a read: it reports the cluster’s domain, or state none when it has none, and never creates a zone. Creating one is the explicit --enable. (Before CLI v0.13.0 the bare command created a zone, which meant checking a cluster’s domain could add a blocker to this very migration.)

What a root-domain switch does and does not touch

Two questions decide whether the switch is safe to attempt on a domain that is already in use. Both have short answers. Ankra touches only the records it creates in the domain you register. Registering example.com adopts it as the organisation’s zone apex, with each cluster’s own <cluster-id>.example.com subzone under it, and the external-dns Ankra installs on every cluster is scoped to the whole domain so it can publish top-level names like app.example.com. Each controller runs with its own record ownership (--txt-owner-id), so it creates, updates and deletes only the records that exist because of an Ingress on its cluster: records you already publish at the apex or under any other name in example.com are never read, written or deleted - not by the switch, and not by anything Ankra runs afterwards. A switch never re-labels a zone. Zone labels are derived from the organisation and cluster ids, so they are the same under any root: a cluster that was axmndle4sl.<org>.ankra.cc becomes axmndle4sl.<org>.example.com. The label is also what Ankra passes as external-dns’s --txt-owner-id, and what any GitOps path built from a cluster domain embeds - so the TXT ownership registry stays matched to its records across the switch, and the paths do not move. --enable re-creating a zone preserves the label for the same reason.

external-dns on each cluster runs with --policy=sync against its own subzone. That is safe here precisely because the label and the owner id survive the switch together: an owner id that changed under a --policy=sync controller would be the configuration that deletes records the controller no longer recognises as its own. Ankra does not change it, and nothing in the switch asks you to.

Serving a zone in your own DNS account from every cluster

A custom Ankra domain has to be hosted in Ankra’s own DNS account, because Ankra mints the per-cluster credentials for it. A zone you keep in your own DNS provider account is different: Ankra cannot mint anything there, so the external-dns it installs drops Ingress hostnames on that zone silently (the sync logs All records are already up to date, because from its point of view there is nothing in scope), and cert-manager’s HTTP-01 challenge for such a hostname waits forever for a name that never resolves. Declare the zone with a credential of your own instead, once, for the whole organisation:

ankra org dns credentials create --name my-dns \
  --webhook-provider-url https://dns.example/api/external-dns/<token>   # stored in the platform's secret store; never echoed back
ankra org custom-dns-zones add --zone example.dev --credential my-dns
ankra org custom-dns-zones list

Every cluster in the organisation - the ones running now and every one created afterwards - then gets its own external-dns for example.dev, rendered and reconciled by Ankra in a dedicated custom-dns stack, within about two minutes of the declaration or of the cluster coming up. An Ingress on chat.example.dev publishes from whichever cluster serves it, and the certificate follows once the name resolves. Each cluster’s controller is pinned to exactly that zone (--domain-filter) with its own record ownership, so it can never fight the controller Ankra runs for the cluster’s Ankra domain, another cluster’s controller, or records you publish in the zone yourself.

The credential is the external-dns webhook provider URL including its token, for any provider that speaks the external-dns webhook protocol. It is written to the platform’s secret store on create and no read surface returns it; re-creating it under the same name re-points every cluster at once, which is how a rotated token rolls out. Its name is what list shows.
ankra cluster custom-dns-zones add <cluster> --zone <zone> --credential <name> declares the same thing for one cluster. A cluster’s own declaration of a zone takes precedence over the organisation’s on that cluster - the way to serve a zone with a different credential on one cluster - and ankra cluster custom-dns-zones list <cluster> shows where each zone a cluster serves was declared (SOURCE = cluster or organisation).
A zone that overlaps the domain Ankra already serves for the organisation (its <org-id>.<ankra-domain> zone, or the whole custom Ankra domain when one is registered) is refused: Ankra’s own controllers publish there already and cannot be told to stay off those names. A zone above the Ankra domain is accepted, and each cluster’s controller is told to leave the Ankra-served part alone.
A domain in Avura needs no credential of your own: once the Avura workspace is connected to the organisation and the domain is shared with Ankra, declare it with --credential avura. See use Avura domains with Ankra.
ankra org custom-dns-zones remove --zone example.dev withdraws the declaration. Ankra tears down the controllers it rendered on every cluster that inherited the zone; clusters that declared it themselves keep theirs, and the zone’s records are yours and are left untouched.

The same declarations are available on the API: GET/POST /api/v1/org/custom-dns-zones, DELETE /api/v1/org/custom-dns-zones/{zone}, and the per-cluster /api/v1/clusters/{cluster_id}/custom-dns-zones twins.

Deploying a demo

A demo deploys every component of the application by default. A single-app application runs its one image; a monorepo runs one pod per component — the frontend and the API of a two-app repository both come up, wired together, instead of half an application answering where the other half belonged. You can still deselect components or demo a single one.

Portal
CLI
AI / MCP

Open the application’s Previews section, choose Launch preview, pick a branch or enter a pull request number, and deploy. The dialog groups what to preview, its lifetime and environment, and the staging cluster, and lists the branch, image, lifetime, template, resources, cleanup and access in a summary before the launch button; a missing image or an offline staging agent is an explicit blocker. The section shows one card per active preview with its branch or commit, component, image, expiry, access and cluster. Each preview links to its own detail page - live provisioning progress read from the staging cluster, the namespace’s bill of materials with manifests (grouped per component), Kubernetes events, and pod logs, plus the preview URL or port-forward command to reach it. On a monorepo the launch dialog lists every component with its own build status and tag, lets you include or exclude each, and marks the web entry — the component that owns the demo URL.

# Deploy a branch demo
ankra application demo deploy <application-id> --branch feature/login

# Deploy a PR demo with an explicit TTL
ankra application demo deploy <application-id> --pr-number 42 --ttl-hours 8

# List active demos, then stop one
ankra application demo list <application-id>
ankra application demo stop <application-id> <workspace-id>

# Inspect a demo: record + provisioning steps, and a bounded log tail
ankra application demo detail <application-id> <workspace-id>
ankra application demo logs <application-id> <workspace-id> --tail 200

# Read or edit the saved demo defaults
ankra application demo config get <application-id>
ankra application demo config set <application-id> \
  --database=true --env 'DATABASE_URL=${{ ankra.demo_database.url }}' \
  --migrate-command 'pnpm run db:migrate' --database-extension vector

# Dispatch the AI pre-setup mission for a failed demo
ankra application demo fix <application-id> <workspace-id>

The deploy response includes preview_url when a public host was resolved. config set fetches the saved configuration first and applies only the flags you pass, so it never drops entries or dependency designations you did not name.

Ask the AI assistant to demo a pull request, or call the deploy_pr_demo tool directly (it is allowed in Ask mode - the demo is isolated and self-expiring). The result carries the same preview_url, names the entry_component, and lists every deployed workload under components[] with its image, container port and ingress path - so a multi-component launch reports what it actually provisioned rather than only the component that owns the URL. Pass entry_component to choose which component serves /. Tear down early with demo_stop.

Opening a pull request on a connected application also deploys a preview automatically and posts the URL back as a PR status comment that updates in place - see the PR preview environments guide for the comment lifecycle, requirements, and troubleshooting.

Monorepo demos: every component, one URL

A monorepo demo deploys each component as its own Deployment and Service inside the demo namespace, and the demo only reports ready once every component accepts connections:

The web entry owns the demo URL. Ankra picks the frontend-shaped component (a name or directory like frontend, web, ui, portal) as the entry serving / on the demo host; you can move the entry in the launch dialog or with entry_component on the API.
API components share the host under a path. The single API-shaped component (api, backend, server) is published under /api on the same demo host, routed straight to its Service — so a browser calling /api/... reaches the API even when the frontend’s own proxy target was baked for another environment. Override per component with ingress_path.
Save the routing when the guess is wrong. The entry and the /api path above are heuristics, and the lanes with no human in the loop — the automatic PR previews and the MCP demo tools — have no launch dialog to correct them in. Declare the routing once in the demo configuration and every lane follows it:
{ "routing": { "entry_component": "commerce-frontend", "components": [{ "name": "commerce-backend", "ingress_path": "/api/v1" }] } }
A declaration is authoritative: the /api guess stops running, so a component you leave out of components stays reachable in-cluster only rather than picking up a path it never asked for. Per-launch ingress_path overrides still win over the declaration. Clear it with "routing": null to return every lane to the heuristics.
Components reach each other by name. Every component’s Service is named after it, so in-namespace URLs like http://crm-api:8090 resolve. Env values can also use placeholders that resolve at deploy time:

Placeholder	Resolves to
`${{ ankra.demo_component.<name>.url }}`	`http://<component>:<port>` inside the namespace
`${{ ankra.demo_component.<name>.host }}`	The component’s Service name
`${{ ankra.demo_component.<name>.port }}`	The component’s container port

The saved migration command runs once per deploy, inside the image of the component that owns the schema (the primary component - usually the backend). Demo environment defaults and the throwaway database are shared by every component of the demo.

Existing demos and single-app applications are unaffected: a demo recorded before multi-component support (or of an application with one component) keeps exactly the previous single-pod shape.

Environment variables and a throwaway database

Most real applications need configuration to boot — a database name, an API key, an SMTP host. Demos support both per-application defaults and per-launch overrides, so any codebase can run as a demo without changes:

Defaults are the application’s environment template, under Previews (Preview settings), which separates the disposable dependencies each preview gets from the shared services it points at and labels every generated value with the dependency it comes from. Every demo of the application inherits them — manual launches, CLI/MCP deploys, and the automatic PR previews.
Overrides are set per launch in the Environment & database section of the launch dialog (or via the env argument of deploy_pr_demo). Overrides win by name.

Values marked secret are stored as Ankra secret slots, held in the platform secret store — the plaintext never persists and is mounted into the demo as a Kubernetes Secret at deploy time. Need a database? Toggle Attach a throwaway Postgres and an ephemeral Postgres is provisioned inside the demo namespace with a random per-demo password, destroyed together with the demo. Because every codebase names its configuration differently, nothing is injected automatically — reference these placeholders in your env values and they resolve when the demo starts:

Placeholder	Resolves to
`${{ ankra.demo_database.url }}`	Full `postgres://` connection string
`${{ ankra.demo_database.host }}`	In-namespace service host
`${{ ankra.demo_database.port }}`	`5432`
`${{ ankra.demo_database.name }}`	Database name
`${{ ankra.demo_database.user }}`	Database user
`${{ ankra.demo_database.password }}`	The per-demo random password

The throwaway database is ephemeral by design: it starts empty on every deploy and is wiped with the namespace. The database runs a pgvector-capable Postgres, so migrations using CREATE EXTENSION vector work. .url and .password references are always delivered through a Kubernetes Secret, never as plain env text.

Migrations. If your image does not run its own migrations on boot, set a migration command in the demo configuration (migrate_command) — for example pnpm run db:migrate or alembic upgrade head. It runs inside your application image (sh -c) as an init container, after the database accepts connections and with the same environment the app sees, so a fresh demo database provisions its schema before the first request. Because every deploy starts the database empty, the command re-runs on every deploy — write migrations to be idempotent (every standard migration tool is).

The command runs with your image’s WORKDIR as the working directory and on PYTHONPATH. Python puts the script’s directory on sys.path, not the working directory, so a migration entrypoint that is a script rather than a console script — python scripts/bootstrap_database.py — could not import the application package sitting beside it and died at import with ModuleNotFoundError. Setting PYTHONPATH yourself in the command still wins.

Extensions. If your schema needs Postgres extensions beyond what migrations create themselves, list them in database_extensions (for example ["vector"]) and the demo database creates them at initdb, before your migrations run. Ankra detects both automatically when it analyses a repository: a Postgres client dependency, an ORM configuration, or a composed database marks the application as database-needing, its referenced connection variables are wired to the ${{ ankra.demo_database.* }} placeholders, and a recognised migration script becomes the migration command — so the first demo of a database-backed application works without any manual configuration. Detection only ever seeds an application that has no demo configuration yet; it never overwrites what you or the pre-setup agent saved.

The demo container port

The demo’s readiness probe, Service, and preview route all target one container port, resolved in this order: the component’s recorded port, the generated runtime Dockerfile’s EXPOSE, the generated Deployment manifest’s containerPort, the analysed target_port parameter, and only then the platform default. The launch dialog shows the resolved port and where it came from; a port you did not edit is left to the platform to resolve. When the resolved port is still wrong — stale analysis, a hand-edited Dockerfile — the platform corrects itself at runtime: a demo whose container runs cleanly but never accepts connections has its logs read for the port the server actually announces (Accepting connections at…, Listening on…, and the other common startup banners). If the evidence is unambiguous, the demo is repointed at the announced port on the fly, the correction is recorded on the application so the next launch resolves it statically, and the demo detail page shows the correction. Ambiguous evidence never auto-corrects; it flows into the failure message (“Nothing accepted connections on port 3000. The container’s logs say it listens on port 8001.”) and dispatches the pre-setup agent instead.

Automatic pre-setup when a demo crashes

An image that validates its environment on boot — refusing to start without a database URL, an auth secret, an API key — crash-loops when demoed with no configuration. Ankra now detects this and fixes it with an agent:

When a demo fails with a startup crash (CrashLoopBackOff or a container configuration error), a failed migration command, or a port-evidence timeout (the container announced a different port than the demo probed), Ankra dispatches a one-shot pre-setup agent for it automatically. The run appears on the AI agents page like any other mission.
The agent reads the crashed container’s logs, works out which environment variables the application demands, and generates a pre-setup: missing database URLs become ${{ ankra.demo_database.* }} references with the throwaway Postgres enabled, secrets get fresh random values, and mode flags get the value that avoids external side effects.
It saves the pre-setup as the application’s demo defaults — so every future demo inherits it — and redeploys the failed demo to prove it boots.

The agent can also set the migration command and database extensions when the logs show schema or CREATE EXTENSION failures. It never weakens the application’s own validation, never reuses values found in logs, and merges with existing demo settings rather than replacing what you configured. Dispatch is bounded to one run per demo per day; image-pull failures and provisioning timeouts never dispatch (no environment can fix those). You can also trigger it on demand with POST /org/applications/{application_id}/demos/{workspace_id}/fix, or just ask the AI assistant to fix the failed demo — the chat has the same get_demo_diagnostics, update_application_demo_config, and redeploy_demo tools the mission uses.

Managing applications

Action	What it does
Retry	Re-run analysis and generation after fixing an issue (for example, adding the right credential or repository permissions)
Reconcile	Re-evaluate the application against its repository and refresh its state
Delete	Disconnect the application from Ankra

Which Ankra AI lanes run on the application’s repository - the pull request review, the organisation skills review, the automatic preview URL - is set per application under Settings → Ankra AI. See Application AI settings.

Built the app with Claude? Watch it shipped to Kubernetes on Ankra.

Prerequisites

Connect GitHub

Add a GitHub credential with access to the application’s repository. The Ankra GitHub App needs permission to open pull requests, commit workflow files, and manage Actions secrets. Ankra installs the Ankra registry credentials on the repository automatically; for your own registry you set the login secrets yourself.

Have a target cluster

Make sure you have a cluster with the agent connected to deploy onto.

API

Applications are available over the API for CLI and scripted use, under /api/v1/org/applications (bearer-token authenticated) - create, list, inspect, retry, reconcile, and delete. See the API Reference for endpoints and schemas. The same lifecycle is available through Ankra’s AI and MCP clients - connect, deploy, retry, reconcile, and delete applications, and follow their CI workflow runs - see the MCP Tool Reference. See the CI/CD Pipeline guide for how the generated pipeline fits into GitOps.

Get Started

Concepts

Create and Run Clusters

Ship Your App

Stacks and Add-ons

Observe and Troubleshoot

Ankra AI

Connect Tools

Source Control

Security and Access

Cost and Backups

Organisation and Account

Reference

How it works

Building on Ankra’s builders

Following a build

Waiting for a builder

What a failure means

The application workspace

What Ankra tracks

Monorepos

Using your own registry

Robot accounts

Security scanning

Preview demos

The preview URL

What a root-domain switch does and does not touch

Serving a zone in your own DNS account from every cluster

Deploying a demo

Monorepo demos: every component, one URL

Environment variables and a throwaway database

The demo container port

Automatic pre-setup when a demo crashes

Managing applications

Prerequisites

API

​How it works

​Building on Ankra’s builders

​Following a build

​Waiting for a builder

​What a failure means

​The application workspace

​What Ankra tracks

​Monorepos

​Using your own registry

​Robot accounts

​Security scanning

​Preview demos

​The preview URL

​What a root-domain switch does and does not touch

​Serving a zone in your own DNS account from every cluster

​Deploying a demo

​Monorepo demos: every component, one URL

​Environment variables and a throwaway database

​The demo container port

​Automatic pre-setup when a demo crashes

​Managing applications

​Prerequisites

​API

How it works

Building on Ankra’s builders

Following a build

Waiting for a builder

What a failure means

The application workspace

What Ankra tracks

Monorepos

Using your own registry

Robot accounts

Security scanning

Preview demos

The preview URL

What a root-domain switch does and does not touch

Serving a zone in your own DNS account from every cluster

Deploying a demo

Monorepo demos: every component, one URL

Environment variables and a throwaway database

The demo container port

Automatic pre-setup when a demo crashes

Managing applications

Prerequisites

API