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:

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:

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:

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

npx getaip setup --codex --claude --global

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

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:

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

For automation, request the stable JSON output:

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:

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:

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:

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:

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:

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:

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:

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:

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

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:

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:

[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:

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:

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

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:

cargo uninstall getaip-server
cargo uninstall getaip-cli

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

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
• Connector fleet quickstart
• Profiles, transports, and connectors
• Production deployment
• Release artifacts