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.
# macOS and Linux
$ curl -fsSL https://cacheport.cc/install.sh | sh
# or with Homebrew
$ brew install cacheport/tap/cacheport
$ cacheport login03
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.
$ cacheport workspace create acme --region fra1
Workspace acme created
URL: https://acme.cacheport.cc04
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.
$ cacheport token create ci --scope read
$ cacheport token create build-cache-writer --scope build-cache:write
$ cacheport oidc allow github --org acme-corp05
Configure clients
Each package manager needs one setting. Follow the guide for yours:
| Ecosystem | Setting | Endpoint path |
|---|---|---|
| npm | .npmrc | /npm/ |
| Yarn | .yarnrc.yml | /npm/ |
| pnpm | .npmrc | /npm/ |
| pip | PIP_INDEX_URL | /pypi/simple/ |
| Poetry | pyproject.toml | /pypi/simple/ |
| uv | pyproject.toml / uv.toml | /pypi/simple/ |
| Conda | .condarc | /conda/ |
| Maven | settings.xml | /maven/ |
| Gradle | settings.gradle.kts | /maven/ |
| Go modules | GOPROXY | /go/ |
| Cargo | .cargo/config.toml | /cargo/ |
| RubyGems | bundle config | /gems/ |
| Composer | composer.json | /composer/ |
| NuGet | nuget.config | /nuget/v3/index.json |
| Docker Hub | image references | /hub/ |
| Helm | helm repo add | /helm/ |
| apt | sources | /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.
$ curl -sI -H "Authorization: Bearer $CACHEPORT_TOKEN" \
https://acme.cacheport.cc/npm/react | grep -i cache-status
cache-status: cacheport; hit; ttl=24307
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.
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.
$ cacheport upstream add npm github-packages \
--url https://npm.pkg.github.com \
--scope @acme-corp \
--token-env GITHUB_PACKAGES_TOKEN09
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.
$ cacheport purge npm left-pad@1.3.0
$ cacheport purge hub library/node:22-alpine --tag-only10
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