Origin CloneKit: Faster Clones in CI

git clone clones from scratch. origin repo clone-fast {owner}/{repo} [DIR] starts from a clone kit instead, a packed snapshot of the repository that Cursor builds ahead of time, and then catches up on whatever changed since. The numbered sequence below is what one run does.

1. 1Fetch the kit manifest from Origin using the token in CURSOR_AUTH_TOKEN. The manifest lists the kit's artifacts and the commit at its tip.
2. 2Download the pack artifacts from gitcdn.origin.cursor.com and check their sizes. With --verify, the hashes are checked while the download runs.
3. 3Install the artifacts into the destination directory, which must be empty.
4. 4Top up the clone: fetch the objects added since the kit was built and check out the current tip of the default branch.

The top-up is what makes the result a current clone instead of a stale one. A kit is a snapshot, so on its own it would sit at whatever commit it was built from. The fetch brings in the newer objects and the checkout moves to the default branch tip. Two flags change that last part: --no-top-up leaves the checkout at the kit's tip, and --bare creates a bare repository with no working tree.

When the kit path succeeds the command prints mode: clone-kit on stdout. If any step fails, the default --fallback auto runs a plain git clone and prints mode: git-clone, while --fallback never exits with status 1 instead. A pipeline can therefore stay green without once using the kit, which is why the last section of this page turns the fallback off for the first run.

One more behavior is worth knowing before you wire it in. The clone ends on the default branch tip, so a job that builds a specific commit has to fetch and check it out afterwards, with git fetch origin SHA and git checkout SHA. Origin serves any reachable commit by SHA.

CloneKit is available on Enterprise plans and is turned on per repository. There is no self-serve toggle, so the first step is a conversation with your Cursor account team about each repository you clone. origin repo clone-fast --help lists the command's options.

The runner needs the Origin CLI, installed with curl -fsSL https://downloads.cursor.com/origin/install.sh | sh, which puts the binary at $HOME/.local/bin/origin. Linux runners need glibc on x64 or arm64, and macOS runners are supported. Alpine and other musl images are not supported. The runner also needs bash, git, jq, curl 7.55 or later and openssl 1.1.1 or later, since clone-fast uses curl for its downloads.

The runner needs network egress to four hosts, and each one covers a different phase of the job.

Every CI system ends up in the same place, with a short-lived token exported as CURSOR_AUTH_TOKEN in the shell that runs origin. They differ only in who mints it. Buildkite does it for you through its Agent API, while GitHub Actions, GitLab CI, Jenkins, CircleCI and self-hosted fleets mint their own through an Origin App.

The one rule that applies everywhere is the expiry. Tokens last at most 15 minutes and cannot be refreshed, so you mint one immediately before the clone. A later job, or a git operation more than 15 minutes after the mint, needs a fresh token from the same request.

On Buildkite, you replace the agent's default checkout with a checkout hook. It requests a token from the Buildkite Agent API scoped to the pipeline's repository, exports it, runs origin repo clone-fast with --verify, registers the credential helper with origin auth setup-git, and checks out $BUILDKITE_COMMIT. The hook cannot live in the repository itself, because the repository is not checked out yet when the hook runs. Connecting Origin takes a Buildkite organization administrator and an Origin administrator to install the Buildkite app.

Three details decide whether that hook works. The repo_url you send must match the URL registered on the pipeline exactly, .git included, or the Agent API returns HTTP 400, so send $BUILDKITE_REPO unchanged. If the Agent API answers HTTP 503, wait for its Retry-After header and retry. And if the agent keeps its build directory between builds, empty $BUILDKITE_BUILD_CHECKOUT_PATH before the hook runs, since clone-fast falls back to git clone when it finds files there.

Everywhere else, you create an Origin App once, install it on the repositories you clone, and hand each job the private key as ORIGIN_APP_PRIVATE_KEY plus two plain variables, ORIGIN_APP_ID and ORIGIN_INSTALLATION_ID. The job signs an app JWT and exchanges it for an installation token that asks for repository:contents:read, which covers clone, fetch and pull. Push needs repository:contents:write, and the installation must have granted it.

The App JWT reference suggests about five minutes, but an installation token never outlives the JWT that minted it. The recipe therefore signs a 15-minute JWT so the token gets its full 15 minutes. The recipe also feeds the private key to openssl through a file descriptor and the bearer header to curl through stdin, so neither shows up on a command line where other processes on the runner could read it.

origin_app_token
origin repo clone-fast acme/widgets . --verify
origin auth setup-git
git fetch origin "$COMMIT_SHA"
git checkout -q "$COMMIT_SHA"

GitHub Actions uses the Origin App path, with one extra step caused by where the code lives. The repository is on GitHub and Origin holds it as a mirror, so the workflow first asks Origin to pull the build's commit and only then clones. It never calls GitHub, which means it needs no GITHUB_TOKEN permissions and does not use actions/checkout.

1. 1On the app's page in Origin app settings, select Sync mirrors from upstream (repository:mirror:sync) under Permissions. If the app is already installed, open the installation's page and select Review & Update.
2. 2In your repository, go to Settings > Secrets and variables > Actions and add the secret ORIGIN_APP_PRIVATE_KEY with the full private key PEM.
3. 3On the same page, add the repository variables ORIGIN_APP_ID and ORIGIN_INSTALLATION_ID.
4. 4Save the workflow as .github/workflows/ci.yml, set ORIGIN_REPO to the mirror's {owner}/{repo} on Origin, and add your build steps after the clone step.

The workflow installs the CLI, mints a token, calls Sync Mirror with "wait":true, then clones and checks out the build's commit. github.sha on a pull_request event is a merge commit that exists only on GitHub, so the workflow builds the pull request's head commit and branch instead. Pull requests from forks are not mirrored at all, because their head branch is not in your repository, so those builds have to run from GitHub.

Sync Mirror is documented as its own API call. It accepts the installation token, needs repository:mirror:sync, and returns 200 with "synced": true or 202 with "synced": false once its wait budget of about two minutes runs out. The workflow treats anything but synced as a failure and exits 1. If Origin is the source of truth and GitHub is the mirror, delete the sync request, because the commit is already on Origin and Origin rejects sync requests for repositories that do not pull from an upstream source.

Secret handling carries over from the generic recipe. The workflow masks both the app JWT and the installation token with ::add-mask::, and a later step that needs Origin git access mints again instead of reading the token from $GITHUB_ENV or $GITHUB_OUTPUT, which are files on disk.

Run the first job with --fallback never. A missing kit then fails the job with exit status 1 instead of quietly running a slow git clone, and you keep the flag on until the kit path succeeds. A good run prints clone-kit: manifest=..., one download line per artifact, a clone-kit timings: block and clone-kit: ready DIR (head SHA) on stderr, then mode: clone-kit on stdout, and exits 0.

The timings block splits the run into manifest, download, verify and checkout phases. To measure the gain, compare its total with a plain git clone of the same repository on the same runner. The docs publish no figure for the gain.

When the kit path does not finish, stderr carries one machine-readable line, clone-kit-result: status=fallback phase=PHASE or clone-kit-result: status=failed phase=PHASE, followed by the reason. That line is also the one your Cursor account team asks for if you escalate. The table maps the common messages to their causes.

The trap in this list is origin auth status. It derives Token: valid or Token: expired from the expiry claim inside CURSOR_AUTH_TOKEN and never asks Origin whether the token is accepted, so valid means only that the token has not expired. The CLI also treats a token as expired five minutes before its expiry claim and refuses to make requests with it, which is how clone-fast ends up logging phase=auth with an expired-session message. If the kit path still fails after all of this, send your account team the job log with the clone-kit-result line, the repository and the output of origin --version.