---
title: Install AIP
description: Install signed GetAIP 2.1.0 tools with npm, connect a supported agent, or build from reviewed source
kind: how-to
audience: developer
appliesTo: "GetAIP 2.1.x / AIP 1.0"
writingStandard: "aip-docs/1.0"
lastReviewedRevision: "e6222fc36ebd7d8a723d773606c073d5da9cd281"
---

# Install AIP

For most users, the supported entry point is the public `getaip` npm package.
It installs the signed GetAIP 2.1.0 native distribution and can connect a
supported agent to the verified GetAIP MCP server. Developers and operators can
still build the same CLI, server, and connector-fleet components from a pinned
source revision when they need source-level review or a custom artifact.

The npm package is a verified setup launcher, not a general JavaScript library.
The command shown by npm, `npm i getaip`, only adds the launcher to the current
project; it does not run setup or connect an agent.

## Install the signed release with npm

You need:

- Node.js `22.14.0` or newer with npm and `npx`;
- macOS or Linux on ARM64 or x64;
- network access to the npm registry and the GetAIP GitHub Release assets;
- write access to the current user's platform-native data and configuration
  directories.

Install or repair the signed native distribution and create the default
loopback configuration:

```sh
npx getaip setup
```

This command does not configure an agent unless you also select a client and
scope. To reproduce the currently reviewed release exactly, pin the package
version:

```sh
npx getaip@2.1.0 setup
```

Do not prefix setup with `sudo`. The installer deliberately writes to
user-owned platform directories and retains the signed manifest, signature,
artifact digests, active version, and rollback state for later verification.

## Connect a supported agent

Choose one command for a user-global configuration:

| Agent | Command |
|---|---|
| Codex | `npx getaip setup --codex --global` |
| Claude Code | `npx getaip setup --claude --global` |
| Cursor | `npx getaip setup --cursor --global` |
| Gemini CLI | `npx getaip setup --gemini --global` |
| OpenCode | `npx getaip setup --opencode --global` |

You can select multiple clients in one command, for example:

```sh
npx getaip setup --codex --claude --global
```

For a project-local configuration, run setup from the project root and use
`--project` instead:

```sh
npx getaip setup --codex --project
```

Use `--project-root /absolute/path/to/project` when the target is not the
current directory. Client configuration requires exactly one scope:
`--global` or `--project`.

## Preview and verify setup

Inspect the signed plan and proposed client mutation without changing the
filesystem:

```sh
npx getaip setup --codex --global --dry-run
```

For automation, request the stable JSON output:

```sh
npx getaip setup --codex --global --dry-run --output json
```

The npm launcher accepts only the `setup` command. It selects a compatible
macOS or Linux bootstrap, verifies the Ed25519-signed release manifest against
its embedded trust store, enforces bounded downloads and approved GitHub
release redirects, verifies artifact size and SHA-256 identity, and only then
executes native setup. A successful non-dry-run reports the active version and
every configured client adapter.

## Build from source

Use the source path for implementation development, reviewed custom builds,
connector-fleet assembly, or qualification work. The Rust workspace packages
remain non-publishable on crates.io, so this procedure starts from a source
checkout. A successful build proves that the selected source compiles in the
current environment; it does not by itself qualify the resulting artifact for
production.

## Choose an installation target

Select the smallest target that matches the work you intend to perform:

| Target | Build | Use it for |
|---|---|---|
| Local native AIP | `getaip-server` and `getaip` | Run a product-neutral daemon and make native or compatibility-profile calls |
| Connector fleet | `getaip-server`, `getaip`, `aip-connector-control-plane`, and selected standalone hosts | Keep product adapters and credentials outside the central daemon |
| Legacy migration | `getaip-server-legacy-bundled` | Move an existing bundled deployment to separate connector processes |
| Rust integration | `aip` facade with selected features | Embed AIP types and product-neutral implementation components in Rust code |

The `getaip-server` dependency graph contains no product connector crate. Do not use
`getaip-server-legacy-bundled` for a new deployment; it retains only the older bundled
composition needed during migration.

## Prerequisites

You need:

- a checkout containing commit
  `e6222fc36ebd7d8a723d773606c073d5da9cd281`;
- Rust `1.88` or newer with Cargo, `rustfmt`, and Clippy;
- write access to a dedicated Cargo target directory;
- enough local disk space for Rust dependencies and release artifacts.

`rust-toolchain.toml` selects the moving `stable` channel, while `Cargo.toml`
declares Rust `1.88` as the minimum supported version. Repository CI at this
revision runs the full Linux jobs on Ubuntu 24.04 and a portable-core subset on
macOS 15. It has no Windows job, so use a validated Linux environment for
release-affecting work that would otherwise run on Windows.

Check the local toolchain before building:

```sh
rustc --version
cargo --version
```

Both commands must exit successfully, and `rustc` must report version `1.88.0`
or newer.

## Pin the source revision

Run these commands from the repository root. Inspect local changes before
switching revisions:

```sh
git status --short
git rev-parse --verify e6222fc36ebd7d8a723d773606c073d5da9cd281^{commit}
```

If `git status --short` reports work you need, preserve it before continuing.
Then select the reviewed source in detached-HEAD mode:

```sh
export AIP_SOURCE_REVISION=e6222fc36ebd7d8a723d773606c073d5da9cd281
git checkout --detach "$AIP_SOURCE_REVISION"
test "$(git rev-parse HEAD)" = "$AIP_SOURCE_REVISION"
test -z "$(git status --porcelain)"
```

The last two commands must exit with status `0`. A dirty checkout produces a
development artifact whose identity is not the recorded commit alone.

## Build the core tools

Build the product-neutral daemon and operator CLI with the reviewed lockfile:

```sh
cargo build --locked --release -p getaip-server -p getaip-cli
```

Cargo writes the binaries to `target/release/getaip-server` and
`target/release/getaip` unless `CARGO_TARGET_DIR` is set. Verify both command
surfaces without starting a service:

```sh
target/release/getaip-server --help
target/release/getaip --help
```

To place these commands in Cargo's binary directory instead, install the same
source paths with the lockfile enforced:

```sh
cargo install --locked --path crates/getaip-server
cargo install --locked --path crates/getaip-cli
```

Cargo normally installs them under `$HOME/.cargo/bin`. This path installation
is permitted even though the packages are not publishable.

## Build connector-fleet components

A fleet adds the standalone lifecycle control plane and one host binary for
each selected product boundary. The maintained product-host packages are:

| Connector | Host package and binary |
|---|---|
| Cal.diy | `aip-host-cal-diy` |
| Hermes Agent | `aip-host-hermes-agent` |
| Chatwoot | `aip-host-chatwoot` |
| Dify | `aip-host-dify` |
| CrewAI | `aip-host-crewai` |
| Twenty | `aip-host-twenty` |

For example, build a core daemon, control plane, CLI, and Cal.diy host:

```sh
cargo build --locked --release \
  -p getaip-server \
  -p getaip-cli \
  -p aip-connector-control-plane \
  -p aip-host-cal-diy
```

Replace or add host packages only for the connectors admitted by the target
deployment. Compiling a host does not admit it, create registry credentials, or
qualify its provider behavior.

For an existing bundled deployment that is being migrated, build the legacy
binary explicitly and keep it separate from the new core artifact:

```sh
cargo build --locked --release -p getaip-server-legacy-bundled
```

## Use AIP from Rust

The `aip` facade defaults to the semantic core. New applications that need the
complete product-neutral implementation surface should select `full-core` at
the same pinned revision:

```toml
[dependencies]
aip = { git = "https://github.com/getaip/core", rev = "e6222fc36ebd7d8a723d773606c073d5da9cd281", features = ["full-core"] }
```

The legacy `full` feature also selects product connector features. Do not use it
as a shortcut for a new product-neutral integration. Product connectors remain
separate packages and processes at the fleet boundary.

## Add runtime dependencies only when required

The binaries can be built without starting external services. Runtime
requirements depend on the selected topology:

| Dependency | Required when |
|---|---|
| PostgreSQL | A deployment uses shared durable runtime state, connector registry state, or production connector-host bootstrap |
| NATS | The deployment enables the native NATS transport |
| Product credentials | A selected connector host calls its external product |
| Docker with Compose and BuildKit | An operator runs the repository's isolated qualification stacks |

The local native quickstart uses file-backed state and does not require
PostgreSQL, NATS, Docker, or product credentials.

## Verify the installation

Confirm the source identity and the installed command surfaces:

```sh
test "$(git rev-parse HEAD)" = "$AIP_SOURCE_REVISION"
test -z "$(git status --porcelain)"
target/release/getaip-server --help >/dev/null
target/release/getaip --help >/dev/null
cargo metadata --locked --offline --no-deps --format-version 1 >/dev/null
```

If you built fleet components, run `--help` on the control-plane binary and
each selected host as well. Record the source revision, Cargo metadata, build
profile, and artifact digest before qualification or deployment. A tag, source
checkout, compiled binary, container image, and running deployment are distinct
artifact identities.

## Resolve build failures

| Symptom | Decision |
|---|---|
| `rustc` is older than `1.88` | Install or select a newer stable Rust toolchain, then rerun the same locked build |
| Cargo reports that `Cargo.lock` must change | Confirm the source revision and restore its lockfile; do not remove `--locked` |
| Cargo cannot work offline during final verification | Complete the locked build so dependencies are present, then rerun the verification command |
| The linker or filesystem reports insufficient space | Inspect the configured target directory and remove only artifacts whose rebuild cost is acceptable |
| A binary reports missing runtime configuration | Treat the build as installed and follow the configuration guide; rebuilding does not create credentials or deployment state |
| The build is being attempted on Windows | Move release-affecting work to a validated Linux environment until a Windows job and qualification scope exist |

`cargo clean` acts on the target directory selected by the current invocation.
Review its scope first when `CARGO_TARGET_DIR` is shared by multiple checkouts.
Docker cleanup affects shared machine state and is not an installation repair.

## Remove a local installation

If the binaries were installed into Cargo's binary directory, remove only the
named packages:

```sh
cargo uninstall getaip-server
cargo uninstall getaip-cli
```

For binaries that were only built in the checkout, remove their Cargo build
artifacts with:

```sh
cargo clean -p getaip-server -p getaip-cli
```

Remove selected control-plane or host packages by name only when they were part
of the installation. Uninstalling binaries does not remove runtime databases,
credential files, registry state, or product-side effects; review those assets
through the applicable deployment or connector runbook.

## Related pages

- [Quickstart](quickstart.md)
- [Connector fleet quickstart](connector-fleet-quickstart.md)
- [Profiles, transports, and connectors](../concepts/profiles-and-connectors.md)
- [Production deployment](../guides/production-deployment.md)
- [Release artifacts](../reference/release-artifacts.md)