Aspect Cloud local setup

Log in once: your builds read and write the same remote cache as your CI, and every build you run shows up in the Build Results UI. There’s nothing to configure first. Aspect Cloud’s endpoints are built into the CLI.

Before you start

The Aspect CLI, v2026.39.10 or newer. Install it, then pin the version for everyone in .aspect/version.axl:
.aspect/version.axl
version("2026.39.10")
An Aspect account. Sign up on the Free tier. See pricing for the tiers.

1. Log in

aspect auth login

This opens a browser, signs you in, and stores the credential in your OS keyring. It’s the same account that installs the GitHub and GitLab Apps. If your account belongs to more than one organization, you’re prompted to pick one. Pass --org <name|id> to choose without a prompt. Over SSH, the CLI detects the remote session and prints the sign-in URL instead of opening a browser. Open it anywhere, sign in, and paste back either the callback URL from the address bar or the authorization code. --no-browser forces this flow.

2. Build with `--remote`

aspect build //... --remote
aspect test //... --remote

--remote connects the task to the remote cache and the build event service. The first build fills the cache; after that, actions already built with the same inputs, platform and configuration come back from it. Off CI, a task builds locally unless you pass the flag, so you choose when your builds use the cache.

What the flag accepts

--remote takes a comma-separated list. The cache and build events are on unless you subtract them with a no- token.

Form	Uses
`--remote`	Cache and build events
`--remote=cache`	Cache and build events, the same as bare `--remote`
`--remote=no-bes`	Cache only, without streaming the build to the Build Results UI
`--remote=no-cache`	Build events only
`--remote=none`	Nothing
`--remote=auto`	The default when the flag is left off: bare `--remote` on CI, nothing off it

Remote execution is coming soon to Aspect Cloud (early access); until then, naming exec against Aspect Cloud is an error. To stop typing the flag, set it once for the repository:

.aspect/config.axl

load("@aspect//feature/deployment.axl", "Deployment")

def config(ctx: ConfigContext):
    ctx.features[Deployment].args.remote = "cache"  # the same as bare --remote

--remote=none on the command line opts a single build out of that default.

3. Or use vanilla `bazel`

--remote is an Aspect CLI flag, so a bazel build from the same shell doesn’t know about it. aspect setup bazelrc writes the equivalent flags where Bazel finds them.

aspect setup bazelrc

On your machine this writes the repository rc: .aspect/bazelrc in the checkout, plus a try-import at the top of the repository’s .bazelrc. Commit both. The file declares what’s available and turns nothing on, so it’s safe for everyone who builds the repository. Opt a build in by name:

bazel build //... --config=aspect-cloud

To turn the cache on for every bazel call on your machine instead, write the machine rc, which is never committed:

aspect setup bazelrc --home --remote

Either way, Bazel authenticates through aspect as a credential helper, serving the login from step 1. aspect has to be on PATH wherever bazel runs.

Check it worked

# Are you logged in, and as whom?
aspect auth status

# Is Bazel picking the flags up? --announce_rc names the --config group each flag came from.
bazel build //... --config=aspect-cloud --announce_rc

To see the cache work, clear your local outputs and build again, so nothing can come from your own machine:

aspect build //... --remote
bazel clean
aspect build //... --remote    # almost entirely "remote cache hit"

Or let CI build a commit first, then build the same commit locally. Open either invocation in the Build Results UI; its Cache tab shows the hit rate. If the rebuild still misses, the cache is reachable but something in the build isn’t deterministic. aspect cache diff names the actions that missed.

Your credential

It renews itself. A browser login also obtains a refresh token, so you log in again only when that expires, not every time the access token does. It lives in your OS keyring: the macOS Keychain, or the Linux kernel keyring. Where no keyring is reachable, the CLI falls back to a 0600 file at ~/.aspect/credentials.json. Set ASPECT_CREDENTIALS_FILE to store it in a file at that path instead. Profiles keep identities apart. Use them on a shared machine, or to separate a personal account from a work one:

aspect auth login --profile work
export ASPECT_AUTH_PROFILE=work    # for this shell; vanilla bazel follows it too

Log out with aspect auth logout, or aspect auth logout --all for every profile. aspect auth status --output=json gives scripts and AI assistants a machine-readable view, including the exact command that fixes a logged-out entry.

Aspect Cloud CI setup: the same cache on the CI runners you already have.
Build metadata: label vanilla bazel builds with their commit and branch in the Build Results UI.

​Before you start

​1. Log in

​2. Build with --remote

​What the flag accepts

​3. Or use vanilla bazel

​Check it worked

​Your credential

​Next