Workspaces vs. tokens: choosing a remote cache setup for your org

The first decision every team makes with a remote cache is not which build tool to wire up - it is how to structure it. One workspace and one token for the whole company? A workspace per repository? A token per developer? The answer changes your security posture, your billing, and how much you can actually see about where build time goes. This is the map we give teams to choose.

Two axes, and they do different jobs

Almost every setup question comes down to two primitives that are easy to conflate. Keeping them straight makes the rest of the decision obvious.

Workspace: the cache boundary

A workspace is the unit of shared cache. Every token that belongs to the same workspace reads and writes the same artifacts, so a task executed on one machine can be restored on any other machine pointed at that workspace. The corollary matters just as much: different workspaces never share a cache. Split two repositories into two workspaces and they each keep their own isolated store - which is usually what you want, because their build graphs and inputs have nothing in common anyway.

Token: identity, not access to a different cache

A token authenticates a caller into a workspace and carries a permission scope (read or write). Crucially, splitting one workspace into several tokens does not split the cache - every token still hits the same artifacts. What extra tokens buy you is accountability and safety: every cache event is stamped with the token that produced it, so tokens are how you tell CI from local, one CI system from another, or one developer from the next. Revoking a leaked token is a one-line action that never disturbs the shared cache.

So: workspaces decide what shares a cache; tokens decide who did what and what they are allowed to do. Hold those two sentences and the spectrum below reads itself.

The spectrum of setups

There is no single correct answer - it is a trade of simplicity against security and insight. Here are the four points on the line, from the bluntest to the most granular.

1. One workspace, one token, whole company

The extreme case: a single workspace and a single token pasted everywhere - every repo, every CI job, every laptop. It works, and it is the fastest thing to stand up. But it is the option we recommend least. One token in every environment means one leak revokes access for everyone, a compromised fork build can poison artifacts the whole company then restores, and your insights collapse into a single undifferentiated blob - you cannot tell CI from local, or one repo from another, because it is all one identity in one store. Entirely the customer's call, but go in with eyes open.

2. One workspace per repository (our baseline)

The setup we recommend as the floor for almost everyone: give each git repository its own workspace. Repositories have independent build graphs, so isolating their caches costs you nothing in hit rate and buys real isolation - a problem in one repo's cache cannot touch another, storage and usage are attributed per repo, and you can hand each team ownership of its own workspace. From here you vary the token strategy per repo; the workspace boundary stays put.

3. Tokens per area, inside a workspace

Now start dividing the single repo workspace into tokens by where the build runs, while everyone keeps sharing the same cache. A common first step is one token for local development and one for CI. If a repo builds in more than one CI system - say Jenkins and GitHub Actions - you can give each its own token and then compare their execution characteristics side by side, or share a single CI token if you do not care to. Same workspace, same cache; different tokens, different lenses.

This is the sweet spot for most teams: cheap to manage, meaningfully more accountable than a single token, and enough separation that a rotated CI token never interrupts developers.

4. A token per endpoint or per developer

The most granular end: a distinct token for every place a build runs - each CI pipeline, and each developer's machine. This is the most secure posture (one revocation is surgical, and least-privilege is per-caller) and the most insightful: because every event is stamped with its token, you can see how much local development is actually served from the cache, which developers or pipelines drive the most reuse, and where cold builds cluster. The cost is administrative - more tokens to issue and rotate - which is exactly what the MCP flow below is for.

Read-only tokens for CI, PRs, and forks

Orthogonal to the spectrum, and the single most important safety control: not every caller needs to write. A remote cache is a shared dependency, so an untrusted build that can write to it is a supply-chain surface. Pull-request and fork builds - where the code under test is not yet reviewed - should use a read-only token. They still get the speedup of restoring existing artifacts, but they cannot publish poisoned outputs that a later trusted build would trust. Grant write only to the pipelines running on your protected branches. We walk through the exact attack this closes in Cache poisoning and CVE-2025-36852.

At a glance

Read-only scoping is not a row here because it applies to any of these: whatever your token layout, make the untrusted callers (PRs, forks) read only.

A quick decision guide

• Pick one workspace + one token if you are trialing Cachely today and will restructure later, or you are a single small repo that accepts the lower isolation.
• Pick a workspace per repository as your default - always. Then choose a token strategy per repo.
• Add a token per area (local vs CI) as soon as more than one environment writes to the cache, or you run more than one CI system and want to compare them. This is the right answer for most teams.
• Go token-per-endpoint or per-developer when least-privilege is a requirement, or when you want to measure local cache reuse and per-pipeline behavior precisely.
• In every case, make PR and fork builds use a read-only token, and reserve write for protected-branch pipelines.

Set it up through MCP

The administrative cost of the more granular setups - creating workspaces and issuing scoped tokens - is exactly what Cachely's MCP server removes. Point an agent (Claude, Copilot, or any MCP client) at Cachely and it can create a workspace, mint tokens with the scope you ask for, and hand back the tool-specific configuration to drop into your build. So "a workspace per repo with a read-only CI token and a write token for main" is a request you can make in plain language rather than a dashboard chore.

The write tools (create_workspace, create_token) return the raw token exactly once and prompt for your approval before running; the read-only setup_instructions tool returns the exact Nx, Turborepo, Gradle, or Bazel config with a placeholder where the real token goes, plus the CI-secret name and the paths to gitignore. Connect it once and the granular setups stop being a spreadsheet exercise.

# The kind of request the MCP flow turns into real workspaces + scoped tokens:
"Create a Cachely workspace for the payments repo.
 Give me a write token for the main-branch CI, a read-only
 token for PR and fork builds, and one token per developer.
 Then show me the Nx setup for each."

Whatever point on the spectrum you land on, you can start blunt and get more granular later - the workspace boundary and the tokens are independent, so tightening one never forces you to rebuild the other. New to the fundamentals? The remote cache guide covers trust boundaries and rollout in more depth.