Documentation menu
Get started with remote caching
Choose your build tool, connect Cachely, and verify a remote cache hit.
Choose your build tool
Set up with AI
Copy this prompt into your coding agent to configure Cachely for your repository and verify a real remote cache hit.
Setup checks that your normal build command works in a fresh terminal. For a new workspace, a trusted build must upload first; a read-only laptop token cannot populate the cache. Your agent should ask before changing CI configuration or secrets.
MCP can create the token for you, which makes the credential available to your coding agent. You can choose manual entry instead: create the token in the dashboard and enter it directly into your ignored local config or CI secret store. See credential handling.
View setup prompt
Set up Cachely remote caching for this repository. Read and follow the public skill at: https://cachely.dev/.well-known/agent-skills/cachely-remote-cache/SKILL.md Read the MCP connection guide at https://cachely.dev/docs/mcp. Detect the existing build tool, version, cacheable tasks, and CI workflow. Preserve the workflow and use the current tool-specific Cachely docs. Use Cachely MCP when available; help me connect it and sign in if needed. Reuse an appropriate workspace, or create one named after the repository. If MCP is unavailable, guide me through the dashboard steps instead. Explain that MCP token creation exposes the credential to my coding agent. If I choose manual credential entry, use placeholders and let me enter the token directly; do not create a token through MCP or read my secret file. Use read-write tokens only for trusted CI and read-only tokens for developer machines and untrusted builds. Keep raw tokens in gitignored local files or CI secrets; never commit them or repeat them in chat. Explain each change. Do not send repository content, paths, or findings to Cachely. Make local setup persistent using the repository's existing configuration loading. Verify the normal build command in a fresh terminal without relying on exports from this session. Ask before changing CI configuration or secrets. For an empty workspace, identify the trusted build that will populate it; a read-only developer token cannot seed the cache. If no trusted writer is available, explain the required CI change and wait for my approval. Verify a real remote cache hit: populate the cache from a trusted build, exclude local cache reuse, remove only confirmed generated task outputs, and rerun with unchanged inputs and remote caching enabled. Show tool-specific evidence that outputs were restored from the remote cache without executing the task. A warm local cache, UP-TO-DATE result, or faster build is not proof. Report changes, verification evidence, and any steps I still need to complete. If verification is blocked, say setup is unverified and explain why.
Quickstart
- Create an account and a workspace. Sign in with Google or GitHub and create a workspace. Your cache is stored on fully managed Cloudflare R2 - zero configuration, nothing to provision, secure, or patch.
- Generate an API token. Open the workspace and create a token with a descriptive name (e.g.
github-actions-prodoralice-laptop). Copy the raw value immediately - it is shown once and never again. See tokens and access control. - Point your build tool at the cache. One workspace token works for every protocol. For Nx and Lerna that is two environment variables. The native integration requires Nx 20.8 or later; use the same pinned Nx version locally and in CI:
export NX_SELF_HOSTED_REMOTE_CACHE_SERVER=https://remote.cachely.dev export NX_SELF_HOSTED_REMOTE_CACHE_ACCESS_TOKEN=<your-token> - Verify a remote hit. Populate the remote cache with a cacheable build and a read-write token, clear the local cache and declared outputs, then rerun with unchanged inputs. Confirm a remote hit and restored outputs. The Nx verification steps show the commands; repeating a build with a warm local cache only verifies local reuse.
CI, access, and troubleshooting
Connect your CI provider, choose token access, or diagnose a failed restore.
- CI setupChoose a CI provider, connect your build tool, and verify remote cache hits.
- GitHub ActionsAll five build tools, one token for trusted workflows, and optional read-only access.
- CircleCINx, Lerna, Turborepo, Gradle, and Bazel recipes with simple token setup and optional read-only access.
- JenkinsNx, Lerna, Turborepo, Gradle, and Bazel recipes with simple token setup and optional read-only access.
- Tokens and accessScopes, rotation, revocation, and the read-only token that stops cache poisoning.
- AI agents (MCP)The MCP endpoint, OAuth sign-in, and what an agent can create, configure, and read.
- TroubleshootingA symptom-first index: 401, 403, 404, silent misses, and an empty dashboard.
- Nx invalid cache directoryDiagnose a machine ID mismatch in the Nx legacy local cache.
- Turbo signature key too shortFix the Turborepo remote cache signing key length error.
- Turbo hit with missing outputsDiagnose a cache hit that replays logs without restoring the build files.
- Gradle remote cache disabledFind the failed cache operation behind the warning and verify recovery.
- Bazel missing digestDiagnose a cached result whose referenced output blob is unavailable.
Looking for another build tool? Request an integration. We are researching demand; these requests are not a support or delivery commitment.
Storage
Managed (R2). Cachely stores cache objects in Cloudflare R2 on your behalf. Zero configuration, included in the subscription. Nx, Turborepo, Gradle, and Bazel CAS artifacts are write-once; Bazel action-cache entries can be replaced by an authorized writer. Cachely does not clone your repository, but configured outputs can include source-derived files or secrets. Review what your build uploads and read the security model before connecting CI.
Artifact upload limits
The managed endpoint currently has a 100 MB ceiling per compressed artifact upload, across all Cachely plans. The size includes archive metadata. Larger requests can return 413 Payload Too Large; a rejected upload does not store an artifact for a later restore.
Nx, Lerna through Nx, Turborepo, and Gradle send one task archive per upload. Bazel HTTP caching sends individual CAS blobs and action-cache entries: the ceiling applies to each request, not the combined size of a build. This upload ceiling does not apply to downloads.
Review your task's declared outputs to avoid caching unnecessary files. Increasing a timeout or upgrading your Cachely subscription does not raise the upload ceiling. Check upload warnings and verify a remote restore with the local cache disabled. See 413 troubleshooting for diagnosis.
Background reading
These pages explain the concepts rather than the Cachely setup: what a remote cache is, how the Nx remote cache works, how to improve a low hit rate, and monorepo build performance.
Community and support
Join the Cachely Discord to ask setup questions, compare cache configurations with other teams, and hear about protocol support as it lands. For anything account-specific - billing, quotas, a workspace you cannot reach - email hello@cachely.dev instead, so it stays off a public channel.
Ready to speed up your builds?
Create a workspace, connect your build tool, and verify your first remote cache hit. Free tier - no credit card.