cacheport

Docs

Quickstart and reference

From an empty account to a pipeline pulling through Cacheport, then everything you can tune: tokens, policies, upstreams and purging.

01

Concepts

A workspace is your organisation's cache. It lives in one region (more on Business and Enterprise), has one URL such as https://acme.cacheport.cc, and holds every package, image and build output your pipelines pull.

An upstream is a registry Cacheport fetches from: public ones like npmjs.org and Docker Hub are preconfigured; private ones you add with their credentials. A token grants read or read-write access to a workspace and can be scoped to specific services.

02

Install the CLI

The CLI manages workspaces, tokens, upstreams and policies. Everything it does is also available in the web dashboard and the API.

shell
# macOS and Linux
$ curl -fsSL https://cacheport.cc/install.sh | sh

# or with Homebrew
$ brew install cacheport/tap/cacheport

$ cacheport login

03

Create a workspace

Pick the region closest to your runners: fra1 (Frankfurt), iad1 (Ashburn), sjc1 (San Jose), sin1 (Singapore) or syd1 (Sydney). For GitHub-hosted runners, iad1 is usually fastest.

shell
$ cacheport workspace create acme --region fra1
Workspace acme created
URL: https://acme.cacheport.cc

04

Tokens and OIDC

Use read tokens for package and image pulls. Give write scopes only to the jobs that push to Build Cache or CI Cache. With OIDC, GitHub Actions and GitLab CI jobs exchange their identity for a token that lasts for the job, so nothing long-lived is stored in CI.

shell
$ cacheport token create ci --scope read
$ cacheport token create build-cache-writer --scope build-cache:write
$ cacheport oidc allow github --org acme-corp

05

Configure clients

Each package manager needs one setting. Follow the guide for yours:

EcosystemSettingEndpoint path
npm.npmrc/npm/
Yarn.yarnrc.yml/npm/
pnpm.npmrc/npm/
pipPIP_INDEX_URL/pypi/simple/
Poetrypyproject.toml/pypi/simple/
uvpyproject.toml / uv.toml/pypi/simple/
Conda.condarc/conda/
Mavensettings.xml/maven/
Gradlesettings.gradle.kts/maven/
Go modulesGOPROXY/go/
Cargo.cargo/config.toml/cargo/
RubyGemsbundle config/gems/
Composercomposer.json/composer/
NuGetnuget.config/nuget/v3/index.json
Docker Hubimage references/hub/
Helmhelm repo add/helm/
aptsources/apt/
Alpine apk/etc/apk/repositories/apk/

06

Reading Cache-Status

Every response carries a standard Cache-Status header. hit means it came from the cache, fwd=miss that Cacheport fetched it from upstream, and fwd=stale that the upstream failed and a stale copy was served. The same outcomes appear in the pull log.

shell
$ curl -sI -H "Authorization: Bearer $CACHEPORT_TOKEN" \
    https://acme.cacheport.cc/npm/react | grep -i cache-status
cache-status: cacheport; hit; ttl=243

07

Policies: cooldown and rules

Policies live in a cacheport.yml file applied with cacheport policy apply, or in the dashboard. A held or denied pull fails with a clear message that names the rule, so developers know why.

cacheport.yml
cooldown:
  default: 24h
  exempt:
    - "npm:@acme/*"

deny:
  - package: "npm:event-stream"
    versions: "3.3.6"
    reason: "Compromised release, see advisory"
  - package: "pypi:*"
    licenses: ["AGPL-3.0"]
    reason: "Licence not approved for distribution"

08

Private upstreams

Private upstreams are matched by scope, prefix or name pattern. Cacheport never asks a public registry for a name that belongs to a private upstream.

shell
$ cacheport upstream add npm github-packages \
    --url https://npm.pkg.github.com \
    --scope @acme-corp \
    --token-env GITHUB_PACKAGES_TOKEN

09

Purging

Artifacts are immutable, so you rarely need to purge. When you do, for example after a deny rule, purge removes the copies from every region. Tag purges force a re-check of the tag without deleting the layers.

shell
$ cacheport purge npm left-pad@1.3.0
$ cacheport purge hub library/node:22-alpine --tag-only

10

Limits

  • Largest package or artifact: 10 GB
  • Largest container layer: 20 GB
  • Largest Build Cache entry: 2 GB
  • Largest CI Cache entry: 20 GB
  • Requests per token: no fixed limit; abusive patterns are throttled

Start on the free plan

20 GB of cache, every registry, unlimited users. Upgrade when your pipelines outgrow it.