> ## Documentation Index
> Fetch the complete documentation index at: https://site.aspect.build/llms.txt
> Use this file to discover all available pages before exploring further.

# Aspect Cloud local setup

> Connect your machine to Aspect Cloud: log in once, then build with aspect --remote or point vanilla bazel at the shared remote cache and Build Results UI.

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](/docs/aspect-workflows/platform/features/webui).

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](/docs/cli/install), then pin the version for everyone in `.aspect/version.axl`:

  ```python title=".aspect/version.axl" theme={null}
  version("2026.39.10")
  ```

* **An Aspect account.** [Sign up](https://signup.aspect.build/) on the Free tier. See [pricing](/pricing) for the tiers.

## 1. Log in

```shell theme={null}
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](/docs/cli/authentication-github) and [GitLab](/docs/cli/authentication-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`

```shell theme={null}
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](/contact?topic=early-access)); until then, naming `exec` against Aspect Cloud is an error.

To stop typing the flag, set it once for the repository:

```python title=".aspect/config.axl" theme={null}
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`](/docs/cli/tasks/setup_bazelrc) writes the equivalent flags where Bazel finds them.

```shell theme={null}
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:

```shell theme={null}
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:

```shell theme={null}
aspect setup bazelrc --home --remote
```

Either way, Bazel authenticates through `aspect` as a [credential helper](https://github.com/bazelbuild/proposals/blob/main/designs/2022-06-07-bazel-credential-helpers.md), serving the login from step 1. `aspect` has to be on `PATH` wherever `bazel` runs.

## Check it worked

```shell theme={null}
# 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:

```shell theme={null}
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](/docs/aspect-workflows/platform/features/webui); 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`](/docs/cli/tasks/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:

```shell theme={null}
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](/docs/cli/guides/agents) a machine-readable view, including the exact command that fixes a logged-out entry.

## Next

* [Aspect Cloud CI setup](/docs/aspect-workflows/cloud/ci-setup): the same cache on the CI runners you already have.
* [Build metadata](/docs/cli/tasks/setup_workspace_data): label vanilla `bazel` builds with their commit and branch in the Build Results UI.