Caching & Artifacts

Two separate local HTTP servers back two separate GitHub-Actions-compatible protocols. They’re easy to conflate since both are about “saving files between steps/runs” — here’s the split.

Artifact server

Backs actions/upload-artifact and actions/download-artifact. Flags: –artifact-server-path / -addr / -port. Does not start unless –artifact-server-path is set.

Cache server

Backs actions/cache. Flags: –cache-server-path / -external-url / -addr / -port, –no-cache-server. Starts automatically unless disabled.

Artifact server

Off by default — pass --artifact-server-path <dir> to turn it on, or nothing gets uploaded/downloaded and steps using actions/upload-artifact/ download-artifact will fail to reach it.

fj-act --artifact-server-path ./.artifacts

Implements both the legacy v3-and-earlier REST-ish upload/download routes and the newer v4 Twirp/protobuf API GitHub’s actions now use, so either generation of upload-artifact/download-artifact works locally.

Cache server

On by default (unless --no-cache-server, or ACTIONS_CACHE_URL is already set in your environment) — backs actions/cache’s reserve/ upload/commit/get-by-key flow against local disk storage, so cache hits persist across separate local runs.

# default location
fj-act   # cache server starts automatically

# custom storage path, or point elsewhere if it's behind a proxy
fj-act --cache-server-path ~/.cache/fj-act-cache
fj-act --cache-server-external-url https://act-cache.example.com

# turn it off entirely
fj-act --no-cache-server

Default storage path is $XDG_CACHE_HOME/fj-act-cache (or ~/.cache/fj-act-cache if XDG_CACHE_HOME is unset).

Separate again from both of these: --action-cache-path (default $XDG_CACHE_HOME/fj-act) is where the actions themselves get cloned to and cached, plus per-job host workspaces when using --bind. Three different caches, three different jobs — actions-on-disk, actions/cache data, and uploaded artifacts.

Reuse across runs

None of the above controls whether containers get reused —that’s -r/--reuse, which keeps a job’s container alive after a successful run instead of removing it, so state (installed packages, downloaded tools) persists into the next fj-act invocation for the same job. Combine it with --pull=false (the default) to avoid re-pulling an image you already have.

Runners & Platforms