Skip to main content
An Ankra Workspace is your own long-lived pod on the organisation’s CI pool, one per repository (and per kind, such as node or e2e). ankra exec runs a command for your current checkout in it: your uncommitted changes go with it, the output streams back live, and the exit code is the remote command’s own. ankra dev install puts small shims in front of go, golangci-lint, pnpm and friends so that the heavy commands you, your editor, git hooks and coding agents already run go to the workspace without anyone typing anything different. The point is your laptop’s CPU and memory: five coding agents each running go test ./... or a full typecheck stop fighting over one machine.

​
Prerequisites

  • The Ankra CLI, logged in to the organisation that owns the repository:
  • The workspaces.use permission. Organisation admins have it; ask an admin to grant it otherwise. A workspace you cannot reach answers “not found”, like one that does not exist.
  • A git checkout whose origin remote is a repository connected to Ankra Pipelines in that organisation. If it is not connected yet, see Connect a repository for Workspaces.

​
Run your first command

From anywhere inside the checkout:
The first command in a repository brings its workspace up, which takes a few minutes while the pod is scheduled, the image is pulled and the profile’s tools are installed. ankra exec says what it is waiting for (still provisioning: Pulling image ...). Later commands reuse the warm pod and start in a second or two. The command runs in the same relative directory as your shell, against your worktree exactly as it is: tracked files plus untracked files that git does not ignore. Your branch, index and working tree are never touched, and only what the workspace does not already hold is uploaded.

​
Route commands automatically

ankra dev install writes the shims to ~/.ankra/dev/shims and links them into ~/.local/bin, so every new shell, editor, git hook and coding agent session picks them up. If ~/.local/bin is not on your PATH, or a real tool comes before it, the command prints the exact PATH line to add to your shell profile; it never edits a profile for you. Each shim decides per invocation: A routed command behaves exactly like ankra exec: same output, same exit code. When a checkout cannot use a workspace - its repository is not connected, you are not logged in, you are offline - or the workspace could not run the command, the real tool runs on your machine instead, so nothing ever blocks on the platform.

​
Commands that write files or produce results

  • --apply brings the files the command changed in the workspace back as a patch applied to your worktree. A patch that no longer applies (you edited the same lines meanwhile) is kept under .git/ankra-exec-unapplied-<run>.patch.
  • --fetch DIR copies a directory back after the run, replacing your local one, whatever the exit code.
Only an allowlisted environment is forwarded (GOFLAGS, NODE_OPTIONS, TZ and similar). Add your own variable names, never secrets, with ANKRA_EXEC_FORWARD_ENV=MY_FLAG,OTHER_FLAG.

​
Manage your workspaces

A workspace that has not been used for 24 hours is torn down for you. Changing the repository’s workspace profile replaces the workspace at the new size the next time it is brought up.

​
Connect a repository for Workspaces

A repository has to be connected to Ankra Pipelines in your organisation before anyone can use a workspace for it. If the repository’s pipeline runs somewhere else - in another organisation or another CI - connect it for Workspaces only, so Ankra never reads its pipeline file, starts a run or posts a check on its pull requests:
Connecting needs the pipelines.manage permission.

​
Give a repository a workspace profile

Without a profile, the workspace uses the image of the repository’s pipeline. A workspace profile says exactly what the pod needs: its image, CPU and memory, disk, service containers (a database the tests reach by name), pinned tools to install and setup commands to run once. A repository can have several kinds, such as default, node and e2e; ankra dev uses the go kind for Go tools, node for pnpm, npm and npx, and e2e (or playwright) for Playwright runs when the profile has them, and default otherwise.
  • tools are downloaded once, checked against their sha256 and put first on the PATH of every command. A .tar.gz or .tgz URL is unpacked; anything else is the executable itself.
  • setup runs once per workspace, before the first command, in the checkout.
  • Services and commands run as uid 65534. An image that writes where only its own user may, such as postgres, needs pointing at a writable directory (PGDATA above).
  • resources.memory is the limit for every command in the workspace together. Heavy commands queue for a share of it, so several agents can run at once without the kernel killing the pod. If a command still runs it out of memory, ankra exec says so and names the limit to raise.
  • The image must match one of the organisation’s allowed CI image prefixes.
Store the profile with the API, which needs workspaces.manage:
Find the repository id with ankra pipeline repositories list.

​
Troubleshooting

Every run appends one line to ~/.claude/logs/ankra-exec.log (or ANKRA_EXEC_LOG) with the repository, exit code, duration and command, which is the first place to look when a routed command behaved unexpectedly. See also the CLI reference for ankra exec, ankra workspace and ankra dev.