Skip to main content
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, unless it finds nothing there it can build and keep running. 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 GitHub repository go from its repo page to a running app on its own address.

How it works

1

Connect a repository

Applications → Add an application opens What are you shipping?. Choose a Repository connection (or Connect GitHub first), find and pick the Repository, then give the Application name and pick the Branch from the repository’s own branch list.
2

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

Merge the pull request

The pull request runs its own checks first: it builds the image, scans it and runs the security gate. It stays a draft, which GitHub will not merge, until they pass, and then Ankra marks it ready for review; if you run the AI review, it skips the draft until then unless Review drafts is on. Review and merge it. Merging activates the CI/CD pipeline in your repository. When they fail, Ankra fixes the pull request itself, and the PR shepherd keeps it moving until you merge it - or merges it for you, if you opt in. Beside CI that Ankra adopted, with no CI at all, or on a private repository whose GitHub plan has no drafts, it opens ready for review.
4

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

Deploy

Deploy the application onto a cluster. Ankra verifies that the image was published and tracks the rollout.
When setup stops before the pull request. In two cases Ankra opens no setup pull request and deploys nothing. The setup ends as failed, and the application’s error message says why:
  • Nothing in the repository keeps running. When the analysis finds only a program that runs once and exits, or nothing that runs at all, the message starts “Ankra did not set this repository up as an always-on application” and ends “Add a program that keeps running and listens on a port, then run setup again.”
  • Nothing can be built. When there is no Dockerfile in the repository, on an open setup branch or among the files Ankra generated, the failed setup_stopped task says what Ankra found and what it could not write. Add a Dockerfile and run setup again.
Both messages carry the same sentence: “No setup pull request was opened and nothing was deployed.” A repository that commits its own manifests under .ankra/manifests/, or whose own CI already publishes an image, still gets its setup pull request, with no build for anything that has no Dockerfile. So does a monorepo in which at least one component can be built.

When your repository already has CI

If your repository already runs CI, Ankra reads it during analysis and works with it instead of adding a pipeline of its own. It reads GitHub Actions workflows, .gitlab-ci.yml, bitbucket-pipelines.yml and .circleci/config.yml, and notes for each one whether it runs tests, builds an image, pushes it (to which registry, tagged how), deploys, what triggers it and which runners it asks for. The analysis says which of these it chose and why, and the setup pull request carries the same reasoning under Your existing CI. When the image your CI pushes lives in a private registry, add a registry credential for it and name it with ankra application registry set --credential so the cluster can pull the image. Ankra also checks whether your CI actually starts. If the newest run of a workflow has waited in the queue for more than 20 minutes, the analysis reports it, names the runner labels the jobs ask for (for example a depot- or self-hosted label nothing is serving), and suggests switching runs-on to ubuntu-latest, connecting a runner for that label, or letting Ankra Pipelines run the build. Ankra never edits your workflow. To build with Ankra Pipelines anyway, convert the application with ankra application pipeline convert. A repository that already commits .ankra/pipeline.yaml keeps building with it.

When the setup pull request does not pass its checks

A repository can already carry problems Ankra did not put there - most often dependencies with known security issues, which the security gate refuses to publish. The setup pull request then fails its own checks, and you do not have to fix it yourself:
  • Ankra AI fixes it on the same pull request. An agent reads the run, commits a fix to the setup branch (for vulnerable dependencies: newer releases, overrides, a regenerated lockfile) and watches the checks until they pass. It never opens a second pull request and never touches your default branch.
  • The pull request says what is happening. Ankra’s status comment explains in plain words what stopped the run and that Ankra AI is fixing it, and the application’s Go live page shows the same. Merge once the checks are green.
  • You can turn it off. Automatic build fixing is on for every application by default. Turn it off for one application, or pause Ankra’s autonomous actions, and the pull request only gets the explanation and a Fix with Ankra link.
When you create the application from the portal yourself and hold pipeline management access, Ankra also approves the pipeline it generated in your name, so the first runs are not held for an approval. An application added with the CLI, an API token or the AI Assistant leaves that approval to an administrator.

When a build on your branch fails

A failed build on the application’s tracked branch dispatches the same agent. What it may do depends on the repository’s CI/CD lane on the application’s AI tab:

When a pull request fails its checks

On Ankra Pipelines, a failed build, image gate or run step (your tests, for example) on any pull request from a branch of your repository, not only the setup pull request, is fixed on that pull request:
  • The fix lands on the pull request’s own branch. An agent commits it to the head branch and watches the run that commit starts. It opens no second pull request and changes only what the failure needs. For an image gate the agent is handed each vulnerable package with the releases that fix it, and moves it to at least the highest.
  • A conflict with the base branch is resolved the same way. The status comment opens “This pull request conflicts with” and names the base. The agent merges the base into the head with a merge commit, resolving every file both sides changed, and the run of that merge commit is its check. Nothing is ever merged into your default branch.
  • When the AI allowance is used up, on Ankra’s own models with no key of your own, the status comment says the fix is queued and starts by itself when the allowance resets on the 1st of the month, or as soon as an organisation owner adds the organisation’s own model key under Organisation settings, AI provider; if billing has paused AI, it names that instead.
  • Without AI, vulnerable Python packages are still upgraded. When the image gate blocked the run and the fix has to wait, Ankra moves each package a lock file pins to a release that fixes it, checked against the packages’ own requirements, commits that to the pull request on GitHub, and leaves the rest for the allowance.
  • The same switches hold it: automatic build fixing turned off for the application, Ankra’s autonomous actions paused, or an environment of the application set to You run it.
A pull request from a fork is never committed to: it gets the explanation and a Fix with Ankra link on the run page.

The PR shepherd

Ankra watches the pull requests it opens in your repository - the setup pull request, and any portability pull request a Launch Plan opens - and drives each one to a state you can merge. You see it as an Ankra PR shepherd check on the pull request’s latest commit. Its summary says where the pull request stands - waiting, ready, needs a person, or merged - and why, and it is updated as things change. What the shepherd does on its own:
  • Your CI never starts. When no CI check has started on the pull request after about 20 minutes - no runner picks the job up, or the Ankra agent on your CI cluster cannot run pipeline steps - Ankra starts a full Ankra pipeline run on the pull request’s head, builds it on Ankra’s builders and runs a proof of the application, so the pull request still gets an answer.
  • The pull request falls behind its base branch. Ankra merges the base branch into its own branch with a merge commit - never a force-push or a rebase. It waits until the head has sat for about 6 hours, or does it straight away when merging is opted in (below).
  • The pull request conflicts with its base branch. Ankra resolves the conflict only when every file in the pull request is one Ankra owns: the Dockerfile, .dockerignore, the .ankra/ directory and the generated build workflow. Your own files are kept exactly as the base branch has them, and a conflict that touches them is left for you.
  • A check fails. When the pull request only changes Ankra’s own files, Ankra AI fixes it on the same branch, up to 3 times, then reports it for a person. A failure in a pull request that changes your files is reported, never “fixed”.
  • The proof of the head never gives an answer. Where your organisation has a staging cluster, a proof still queued 20 minutes after Ankra queued it, or one that ended not proven, is a dead end: once nothing else is pending, the check reads Needs a person, names the proof and its reason, and Ankra does not merge. The shepherd keeps looking every 15 minutes, so a proof that passes later turns it Ready to merge.
These are the shepherd’s own actions. On Ankra Pipelines, a pull request from a branch of your repository is also fixed as When a pull request fails its checks describes, whichever files it changes.

Merging

Ankra merges a pull request only when all of these hold:
  • merging is opted in for the application (below);
  • every check on the head has finished green, and the proof of the application passed;
  • GitHub reports the pull request mergeable. Branch protection is always honoured, never worked around.
Otherwise the check reports the pull request as ready for a person to merge. Ankra never merges a pull request whose own CI never ran - Ankra’s pipeline run and proof make it ready for you, not merged - and it never merges a portability pull request, because that changes your code. After a merge, the application deploys as usual. When your CI could not build the pull request, Ankra builds the merge commit on its own builders so the deploy has an image.

Opting in to merging

Merging is off by default. Two settings decide it:
  • The organisation’s setting, auto_merge_setup_pull_requests on PUT /org/applications/settings (or ankra_application_settings in Terraform). Only organisation admins can change it.
  • The application’s own setting, which overrides the organisation’s: on for this application, off for this application, or follow the organisation (the default). Read it with GET /org/applications/{application_id}/auto-merge-setup-pull-requests and change it with PUT and a body of {"enabled": true}, {"enabled": false}, or {"enabled": null} to follow the organisation again. Only organisation admins can change it. The answer carries the application’s own value, the organisation’s, and the effective one Ankra acts on.
An application set to on is merged even when the organisation’s setting is off, and one set to off never is. If a setting cannot be read, Ankra does not merge.

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:
  1. The repository’s own Dockerfile - used as-is.
  2. A generated Dockerfile - the one Ankra wrote for this application.
  3. 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.
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:
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: 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 at /next/applications/<application-id>: the application’s own menu takes the sidebar’s place, in the order the work happens. Each section is a view of that page, named in the address with ?view=, and a view’s own tabs with &section=. A link that uses a view’s older name still opens the view it meant. The table describes the sections this page refers to; The application page lists every row of the menu in order. The last column gives each section’s address, after /next/applications/<application-id>; Portal URLs lists them in full. The menu carries one mark: Environments reads as needing attention while the environment in view has failed or is degraded, or its rollout is stuck, and while the Deploy group is closed, its heading carries the mark. The Applications list groups applications under Needs you, Ankra is on it, Live, Parked, Not deployed yet and Couldn’t check, with a count of each under the title. You can search by name or repository, and filter by status, environment and language.

Remove a deployment from one cluster

Removing takes the application off one cluster and leaves the application, and everywhere else it runs, in place. Ankra uninstalls its workloads, services and configuration in that namespace, and deletes the installation record once the uninstall has been handed to the cluster; the place reads as removing in the deployments read until the cluster has taken it down. A deployment that holds data (a CloudNativePG database, a persistent volume claim or a StatefulSet’s volume claims in the application’s manifests) is removed only when a complete restore point of its stack, taken in the last 24 hours, covers that data. An add-on among what it would remove, such as a wizard stack’s database add-on, is never covered, because Ankra cannot see its volumes from its definition, and neither is a manifest Ankra cannot read. Otherwise nothing is removed, and the removal fails with a reason naming the data and the two ways forward: take a restore point and remove again within a day, or remove those members from the stack yourself on the cluster’s Stacks page. The application itself, with its settings, secrets, published images and release history, its other deployments, the add-ons on that cluster other workloads may use, and the cluster itself all stay, so you can deploy there again from Environments → Deploy a version. To stop a deployment for a while without losing anything, park it instead; to take the application out of Ankra everywhere, delete it. Its home is Settings → Park or remove (?view=settings&section=runtime). The environment in view lists where the application runs, each place with Park (or Wake) and Remove; below it are the places that run the application outside every environment, a stack the deploy wizard made or an add-on carrying its chart in a stack the application did not create, which cannot be parked, only removed. Where it runs offers Uninstall on an environment’s place too, behind the same review, and links everything else to Park or remove. Removing an installation or a wizard stack needs permission to deploy the application (applications.deploy); an add-on’s removal needs stacks.delete on that cluster instead, as below. The review names what goes and what stays before anything happens and, opened from Park or remove on an environment’s place that is not parked, offers Park instead. Removing an installation takes one deliberate press, except when the deployment serves a production environment, is the only place the application runs, or Ankra could not read where else it runs or which environment it serves: then the cluster’s name has to be typed. The platform answers as soon as it has accepted the teardown, not when it is done: the installation reads removing until the teardown job has handed the uninstall to the cluster and deletes it, or failed with its reason, which is also what ankra application installations shows. Park or remove lists it under Being removed, reading every few seconds for the first two minutes and every half minute after that, and says what became of a removal asked for there once it settles: removed, naming any stacks left in place because other workloads may use them, or that it did not finish, with the platform’s reason when it gave one, in which case the deployment is listed again and can be removed again once the cause is fixed. A deployment that holds data with no fresh restore point fails this way, with the reason above. A second removal of the same deployment is refused as Already being removed (409), a deployment no longer on that cluster as Nothing to remove, and while a removal runs a deploy to the same cluster and namespace is refused with 409. An application deployed with the deploy wizard has no installation: it runs as a stack, named by cluster and stack name. Ankra removes only a stack it can show runs this application, from push to deploy’s record or from the image it runs; one it cannot attribute is left in place as This stack stays, because it may be a shared operator, and goes from the cluster’s Stacks page if it is no longer needed. The other stacks the same deploy created stay and are named in the answer, and the removal is followed through its undeploy_application job, which ankra application jobs lists. An add-on that carries the application’s chart in a stack the application did not create is removed from that stack through the cluster’s add-on uninstall. The review says whose stack it is, that Ankra commits the change to the cluster’s Git repository and that the rest of the stack stays; the cluster’s name is always asked for, and it needs permission to delete stacks on that cluster (stacks.delete). An add-on that belongs to a deployment of this application is refused as Remove it as a deployment: remove that deployment instead, so its record goes with it. A cluster Ankra cannot reach that is not stopped either cannot take the removal (That cluster isn’t reachable), and a change its Git repository did not take reads The change wasn’t committed. On a stopped cluster an add-on’s removal is recorded now: Ankra takes the add-on out of the stack and commits the change now, or at the cluster’s next sync when its repository has changes Ankra has not taken in yet, and uninstalls it when the cluster next starts, so you do not need to start the cluster for it. Park or remove lists it under Waiting for the cluster to start, with Keep add-on (permission to change stacks on that cluster, stacks.write) to take the removal back while it waits; a removal the cluster cannot hold until it starts is refused as This removal can’t wait for the cluster. Only an add-on’s removal is held for the start: an installation or a stack removed from a stopped cluster reads Being removed, and Where it runs gives no time for it. A place whose removal is recorded is no longer where the application runs, whatever its cluster still carries. The deployments read answers it in removal_deployments, apart from deployments, without a health or sync verdict, and the cluster and health counters are summed over deployments alone. Where it runs lists these places under Being removed, with when the removal finishes as its status, and no version: for a cluster named staging, Removed when staging starts for a removal waiting for the stopped cluster, Finishes when staging is back online for one on an unreachable cluster, and Being removed otherwise. A place listed under Being removed is never Needs attention, and an application whose only places are being removed no longer reads Nothing is running anywhere yet. Over the API, POST /api/v1/org/applications/{application_id}/deployments/remove takes cluster_id with namespace for an installation or stack_name for a wizard stack, not both, and answers 202 with the cluster_id, the namespace (empty for a stack) and a stack’s stack_name, an installation’s installation_id, any retained_stacks, the teardown’s operation_id and status removing. ankra application remove <application> --cluster <cluster> does the same and asks first (--yes skips the prompt): --namespace only when the application runs in more than one namespace on that cluster, --stack for a deploy-wizard deployment, -o json or -o yaml for the answer. Ankra’s AI and MCP clients have remove_application_deployment, which Ankra’s chat runs only after you confirm it (an MCP client with mcp:write runs it directly), with list_application_installations to find the cluster and namespace and park_application_deployment as the reversible stop; see the MCP Tool Reference.

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. Ankra decides the components from, in order: the components block of the repository’s .ankra/ankra.yaml, when it declares one; 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. Without a declaration, a Dockerfile at the repository root always means a single app, whatever else the repository contains. The AI proposal and structural detection can add components to a monorepo but never leave it with fewer than it records: a run whose inference finds fewer keeps the recorded ones. Only a declaration, or two or more of Ankra’s per-component build workflows for fewer components than the record, can shrink it, and a run that drops or renames a recorded component records the new set and reports the change as the failed task record_components. A repository whose layout inference misreads, such as an API built from deploy/docker/Dockerfile at the root beside a web app in web/, declares its components in .ankra/ankra.yaml, and the declaration is also how you remove one. 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 → 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.
The same declaration at create time:
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, which Harbor releases let a robot administer robots and when the credential must be a Harbor user, 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 when the application is next reconciled, or from Settings → Registry with Set up publishing login.
  • 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 → Registry, where Set up publishing login, Rotate publishing login and Revoke publishing login 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.
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: 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.
1

Configure a staging cluster

An admin sets the organisation’s Staging cluster under Ankra AI → AI workspaces. Optionally set a Preview domain (with an Ingress class and TLS secret) there too - this is what gives demos a public URL.
2

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

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:
  1. 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.
  2. 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.
  3. 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 Ankra AI → AI 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:
1

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 are on Infrastructure → Domains: the cluster domains under Cluster names, and the records on the organisation’s Ankra domain.
2

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

Remove each cluster domain

ankra cluster domain <cluster> --remove (or DELETE /api/v1/clusters/{cluster_id}/dns-zone, or Take the name away on the cluster’s row under Cluster names 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.
4

Delete the DNS records

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

Register the new domain

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

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:
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. On a cluster with the Gateway API option, an HTTPRoute hostname on the zone publishes the same way, once the Gateway API CRDs are on the cluster. 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 zone at Cloudflare needs no webhook: connect a scoped Cloudflare API token once with ankra org cloudflare connect <name> and declare the zone with --cloudflare-credential <name>. Ankra checks with Cloudflare that the token reaches the zone and is not denied DNS edit there before the declaration is stored, and that controller runs upsert-only: it never changes or deletes a record someone else made. See Serve a Cloudflare zone from every cluster.
  • 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.
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.
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:
    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:
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:
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:
  1. 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.
  2. 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.
  3. 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

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 → Who runs it, in the On your pull requests card. See Application AI settings.

Prerequisites

1

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

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.