---
title: Install
description: Install Agent Layer and get started.
---

Install Agent Layer once per machine, then initialize each repo you want to use. The CLI is named `al`.

## Requirements

- A supported client installed separately (Antigravity `agy`, Claude, Codex, Copilot CLI, VS Code)

Agent Layer does not install client CLIs for you.

:::note
If you manage multiple repos, you still install `al` only once. Each repo gets its own `.agent-layer/` config.
:::

## Homebrew (macOS/Linux)

```bash
brew install conn-castle/tap/agent-layer
```

## Script (macOS/Linux)

```bash
curl -fsSL https://github.com/conn-castle/agent-layer/releases/latest/download/al-install.sh | bash
```

The script installs to `~/.local/bin` by default and verifies checksums. If `~/.local/bin` is not on your `PATH`, it prints an exact line to add.

If you prefer not to pipe a script into your shell, download it first and inspect it:

```bash
curl -fsSL -o al-install.sh https://github.com/conn-castle/agent-layer/releases/latest/download/al-install.sh
less al-install.sh
bash al-install.sh
```

By default, the script also installs shell completions for your current interactive shell. You can manage completions manually with `al completion <bash|zsh|fish> --install`.

## Verify

```bash
al --version
```

## First run

```bash
cd /path/to/repo
al init
al <client> # e.g., al claude
```

`al init` seeds:

- `.agent-layer/` for configuration
- `docs/agent-layer/` for project memory
- a managed `.gitignore` block

By default, `al init` prompts to run the setup wizard. Skip it with `--no-wizard` if you prefer to configure manually.

You can also run `al wizard` later to revisit approvals, enabled clients, MCP servers, and warnings.

:::tip
For a safe evaluation, run `al init` in a disposable repository first.
:::

## Recommended next steps

- Read the docs: [/docs/getting-started](/docs/getting-started)
- Run `al doctor` to validate config and MCP connectivity
- Edit `.agent-layer/instructions/` to set team rules
- Review `.agent-layer/commands.allow` to keep approvals tight
- Enable only MCP servers you trust (see [/docs/concepts#mcp-servers](/docs/concepts#mcp-servers))
- Skim [/security](/security) for network behavior and secret handling

## Update

Update the global CLI:

- Homebrew: `brew upgrade conn-castle/tap/agent-layer`
- macOS/Linux script: re-run the install script above

Run `al upgrade plan` and then `al upgrade` inside the repo. This updates the repo pin (`.agent-layer/al.version`) and refreshes template-managed files.
For a concise runbook (interactive + CI), use [/docs/upgrade-checklist](/docs/upgrade-checklist).

For the complete upgrade contract (event model, compatibility guarantees, migration rules, and platform matrix), see [/docs/upgrades](/docs/upgrades).

:::caution
To upgrade a repo safely, use `al upgrade plan` (dry-run) and then `al upgrade` (apply).
For CI-safe non-interactive apply, use `al upgrade --yes --apply-managed-updates`. Include `--apply-memory-updates` and/or `--apply-deletions` only when explicitly intended.
:::
