Shared compiler cache for ccache and sccache

This page covers Depsilo v0.11.0. ccache and sccache can use Depsilo to share compiled artifacts across developer machines and CI, where several build nodes repeatedly compile the same inputs. Complete startup and initial setup first, then enable compiler caching separately.

Client	Version and protocol	HTTPS requirements
ccache	Recommended: 4.7+, HTTP remote storage	4.13+ with a storage helper installed
sccache	Recommended: v0.15.0+, native WebDAV backend	Native support; no ccache helper needed

Both clients share namespace, credential, and capacity management. Their entries occupy separate protocol spaces and cannot produce cross-client hits. Package caching and compiler caching also have separate capacity accounting.

1. Enable the server

Add this configuration to your existing config.toml. The path uses the persistent /root/.depsilo directory from the recommended Docker deployment. For a binary deployment, replace it with a persistent absolute path that the service can write to, separate from package-cache storage.

[compile_cache]
enabled = true
public_url = "http://127.0.0.1:23333"
allow_insecure_http = false
max_size_gb = 20
max_entries = 500000
max_entry_size_mb = 512
namespace_max_size_gb = 20
namespace_max_entries = 250000

[compile_cache.storage]
type = "local"
path = "/root/.depsilo/data/compile-cache"

The address above is for testing on the same machine. To share with other machines, set public_url to a reachable HTTPS origin such as https://depsilo.example.com and configure a TLS reverse proxy. This field validates and generates client configuration; it does not enable HTTPS automatically. Restrict the backend port to the proxy, loopback, or a trusted network.

Only use remote HTTP with allow_insecure_http = true on an explicitly trusted LAN/VPN. Restart the service, then open /admin/compile-cache on your instance as an administrator or Operator.

2. Create machine credentials

In Admin → Compiler cache, create a credential with a namespace such as linux-ci, a permission level, and an expiry. Save the token and generated client configuration when the credential is created: the full token is shown only once.

Permission	Intended recipient	Behavior
readwrite	Trusted CI / build nodes	Read entries and upload compiled artifacts after a miss
readonly	Developer machines consuming team caches	Read existing entries without uploading after a miss

Each credential is bound to one namespace. It is separate from Admin API tokens and the bootstrap token used during setup. Store the real token in a CI secret or secret manager, and keep it out of committed project configuration.

3. Connect a client

These are variable templates. Replace every REPLACE_WITH_… value with the corresponding value returned by Admin when creating a credential. Set them in the build shell or CI job, then use your project’s existing compiler-wrapper integration to run compilation through the chosen client.

ccache

Set the complete generated ccache_remote_storage value, including its token attributes and any read-only option:

export CCACHE_REMOTE_STORAGE='REPLACE_WITH_ADMIN_GENERATED_VALUE'

ccache checks its local cache before Depsilo by default. Ephemeral CI nodes can also set CCACHE_REMOTE_ONLY=true to use only remote storage. Generated values for readonly credentials already include read-only=true. Use the default subdirs layout or flat; do not set layout=bazel.

ccache uses different settings for HTTPS

Its built-in HTTP backend handles only http://. HTTPS requires ccache 4.13+ and ccache-storage-https, installed using the official helper instructions. Admin generates an @bearer-token attribute for HTTPS; do not replace it with the HTTP backend’s bearer-token attribute. See the ccache 4.13.6 manual.

sccache

Use the generated sccache endpoint and token, or copy the [cache.webdav] configuration provided by Admin. The equivalent environment variables are:

export SCCACHE_WEBDAV_ENDPOINT='REPLACE_WITH_ADMIN_GENERATED_ENDPOINT'
export SCCACHE_WEBDAV_TOKEN='REPLACE_WITH_CREATED_MACHINE_TOKEN'

The endpoint path is /sccache/v1/<namespace>. The native WebDAV backend handles both HTTP and HTTPS. If a sccache daemon is already running, restart it under the new environment before building: run sccache --stop-server followed by sccache --start-server when no builds are running.

This configuration targets sccache v0.15.0. Do not add rw_mode or SCCACHE_WEBDAV_RW_MODE, which were not included in that release. This version tests write access using a .sccache_check probe. Depsilo rejects writes from read-only credentials, after which the client uses a read-only backend.

Setting remote-storage variables does not replace compiler invocations in your build system. Confirm that the project actually compiles through ccache or sccache, then inspect its --show-stats output.

4. Verify remote hits

A faster second compilation or a cache-hit counter alone does not prove a Depsilo hit. The client may have satisfied the request from its local cache. Resetting statistics does not clear that cache.

On Linux or macOS, you can run the v0.11.0 repository’s real-client verification. It requires Git, Make, ccache 4.7+, official sccache v0.15.0+, and GCC/Clang. HTTPS additionally requires ccache 4.13+ and the helper above. Use a newly created readwrite credential and its namespace endpoint:

git clone --branch v0.11.0 --depth 1 https://github.com/depsilo/depsilo.git depsilo-cache-check
cd depsilo-cache-check
bash -c '
  read -rp "Namespace endpoint from Admin: " COMPILER_CACHE_ENDPOINT
  read -rsp "Readwrite token: " COMPILER_CACHE_TOKEN
  printf "\n"
  export COMPILER_CACHE_ENDPOINT COMPILER_CACHE_TOKEN
  make test-compiler-cache
'

The endpoint must end in /ccache/v1/<namespace> or /sccache/v1/<namespace>, without ccache’s |bearer-token=… attribute. The hidden token prompt keeps the token out of shell history.

The script produces a separate compilation miss and remote write for each client, removes its isolated local cache, and compiles again to confirm a remote hit through client statistics. The sccache check also removes its isolated disk L0 and restarts the test daemon to exclude local hits. Missing tools or old versions cause a failure instead of a skip. The test leaves a few entries in the selected namespace that LRU can reclaim.

Capacity and operating boundaries

• Separate storage and quotas. Compiler caching enforces global and per-namespace byte and entry limits, reclaiming entries by LRU. Reserve additional space for uploads; max_inflight_upload_size_mb defaults to 1024. Admin provides status, credential revocation, and manual cleanup.
• Writers must be trusted. A machine with write access can affect artifacts consumed within its namespace. Keep readwrite tokens away from untrusted devices. Revocation rejects subsequent authentication; it does not interrupt uploads that have already authenticated.
• S3 is internal storage. Compiler caching can use a separate S3 bucket, but Depsilo does not expose an S3-compatible client endpoint. sccache should use the WebDAV path above, without bypassing Depsilo to access that bucket directly.
• Run a single instance. Do not share a compiler-cache database, directory, or bucket between Depsilo instances. This feature provides shared compiler caching; it is not a general WebDAV file service or a sccache-dist remote execution service.

For complete capacity, concurrency, timeout, and storage settings, see the Depsilo v0.11.0 compiler-cache guide.