Aspect Enterprise local setup

For Aspect Enterprise deployments with external endpoints enabled.

An Aspect Enterprise deployment has its own hostnames and its own sign-in, so your machine has to be told about it once. After that, builds reach its remote cache, build event service and, if the deployment runs one, its remote executor.

The external endpoint

A deployment’s CI runners reach its cache and remote execution privately, inside the deployment’s network. Developer machines, and CI you run outside that network, reach them through a second, external endpoint over the internet, authenticated by the deployment’s sign-in. It’s remote.<your-domain> by default, and it’s turned on in the deployment’s configuration, hosted by Aspect or self-hosted. It runs in one of two modes:

Separate: its own cache and remote executor fleet, sized and scaled separately from CI’s, which keeps developer traffic away from CI’s.
Shared with CI: CI’s cache and remote executor fleet.

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")
Your deployment’s host, something like remote.acme.aspect.build. Your Aspect contact gives you this, or it’s an output of your Terraform.
Workflows 6.0 or later. 5.17 and 5.18 authenticate through a standalone credential helper instead; see , and the when you’re ready to move.

1. Record the deployment

aspect auth configure remote.acme.aspect.build

The CLI fetches the host’s /.well-known/oauth-protected-resource document (RFC 9728 discovery). That document names the deployment’s sign-in and the endpoints it serves: cache, build events, remote execution and the Build Results UI. The CLI records them in ~/.aspect/config.json, then runs the login. The argument can be a bare host or any URL the deployment serves; scheme, port and path are stripped. remote is only the default DNS label, so if your deployment uses a different one, use that.

Flag	What it does
`--name <name>`	Name the deployment. Defaults to the name it advertises, or one derived from the host
`--default`	Make it what `--remote` targets
`--issuer <url>`	Pick the sign-in, for a deployment advertising more than one. Required when non-interactive
`--login=false`	Record the deployment without logging in
`--no-browser`	Print the sign-in URL instead of opening a browser
`--profile <name>`	File the login under this profile instead of `default`; see profiles

If configure can’t connect, fetch the document yourself:

curl https://remote.acme.aspect.build/.well-known/oauth-protected-resource

If that fails too, the problem is reachability (DNS, VPN or a firewall), not the CLI. Your machine needs a route to the deployment’s external endpoint, or to its private one from inside its network. The deployment’s name is what --deployment, aspect auth use and the --config sections use. Without --name, it’s the name the deployment advertises or, failing that, the host minus its first label, with Aspect’s own domain dropped:

Host	Name
`remote.acme.aspect.build`	`acme`
`remote.acme.example.com`	`acme.example.com`

This page uses acme. Substitute the name aspect auth status shows, or pass --name acme to choose it.

2. Log in

configure runs the login for you. To log in again later:

aspect auth login --deployment acme

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. If your account belongs to more than one organization, you’re prompted to pick one. Pass --org <name|id> to choose without a prompt.

3. Make it the default

Configuring a deployment doesn’t make it the one --remote targets. Until you say otherwise, that’s Aspect Cloud:

aspect auth use acme

aspect auth use aspect-cloud hands the default back.

4. Build with `--remote`

aspect build //... --remote
aspect test //... --remote=exec

--remote connects the task to the deployment’s remote cache and build event service. Off CI, a task builds locally unless you ask.

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; remote execution is off unless you name exec.

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=exec`	Cache, build events and remote execution
`--remote=exec,no-bes`	Cache and remote execution
`--remote=no-exec`	Cache and build events; cancels an `exec` set in `config.axl`
`--remote=none`	Nothing
`--remote=auto`	The default when the flag is left off: bare `--remote` on CI, nothing off it

Remote execution is never implied. It changes where your actions run, which means every action needs a toolchain available on a remote worker and an exec platform matching a worker pool; see Targeting remote execution worker pools. Naming a capability the deployment doesn’t serve is an error, and aspect auth status lists what each deployment serves. More than one deployment, such as staging and production? --deployment picks which one for a single build, without changing the default:

aspect build //... --remote --deployment staging

--deployment without --remote is an error on a build or test: it names a deployment without saying what to use it for. 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 = "exec"

--remote=none opts a single build out, and --remote=no-exec keeps the cache and build events while running that one build’s actions locally.

5. 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 gives every configured deployment a section of its own and turns nothing on, so it’s safe for everyone who builds the repository. Opt a build in by name:

bazel build //... --config=aspect-acme        # cache and build events
bazel build //... --config=aspect-acme-exec   # ... and remote execution

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 your login. aspect has to be on PATH wherever bazel runs.

Check it worked

# Is the deployment recorded, is it the default, and are you logged in?
aspect auth status

# Is Bazel picking the flags up? --announce_rc names the --config group each flag came from.
bazel build //... --config=aspect-acme --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 chart gives you the hit rate. Hits show only when CI and your machine share cache storage: CI on runners you manage does when it points at the same external endpoint, and Workflows runners do only where the external cache shares CI’s storage. 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.

If the deployment uses your own identity provider

Every deployment signs in through Aspect sign-in or through your own identity provider. For a developer at a terminal it makes no difference: the browser flow works the same, and --no-browser covers SSH and containers. It matters for two things:

CI: there’s no Aspect API token, so CI brings its own credential helper. See CI setup.
Registering redirect URIs, which your identity provider admin does once. On Aspect sign-in, Aspect registers them for you. Getting one wrong produces redirect_uri_mismatch at login.

Login	AWS	GCP
Build Results UI	`https://app.<domain>/oauth2/idpresponse`	`https://app.<domain>/oauth2/callback`
Aspect CLI	`https://remote.<domain>/oauth2/callback`	`https://remote.<domain>/oauth2/callback`

app and remote are the default DNS labels. If yours differ, use the hostnames your deployment serves; aspect auth status prints them. If logins stop renewing on your own identity provider, look at the scopes the deployment advertises. The CLI sends that set verbatim and adds nothing; it never adds offline_access, because some providers reject scopes they don’t expect.

Your credential

It renews itself. A browser login also obtains a refresh token, so you log in again only when that expires. It’s separate per deployment. Each deployment has its own sign-in, so a credential for one isn’t accepted by any other, or by Aspect Cloud. With Aspect sign-in you’re still the same Aspect account everywhere. 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. One profile holds one credential per deployment, so switching profiles switches them all:

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

Log out and forget:

aspect auth logout --deployment acme   # clear the credential, keep the deployment
aspect auth logout --all               # every credential, every profile
aspect auth remove acme                # forget the deployment entirely

Logging out of the default deployment also clears the default.

CI setup: point CI at the deployment, on Workflows runners or runners you manage.
Targeting remote execution worker pools: route actions to the right remote execution worker pool.
Build metadata: label vanilla bazel builds with their commit and branch in the Build Results UI.

​The external endpoint

​Before you start

​1. Record the deployment

​2. Log in

​3. Make it the default

​4. Build with --remote

​What the flag accepts

​5. Or use vanilla bazel

​Check it worked

​If the deployment uses your own identity provider

​Your credential

​Next

The external endpoint

Before you start

1. Record the deployment

2. Log in

3. Make it the default

4. Build with `--remote`

What the flag accepts

5. Or use vanilla `bazel`

Check it worked

If the deployment uses your own identity provider

Your credential

Next