{
  "schemaVersion": "1.0",
  "title": "Install AIP",
  "description": "Install signed GetAIP 2.1.0 tools with npm, connect a supported agent, or build from reviewed source",
  "canonical": "https://getaip.org/docs/getting-started/installation",
  "route": "/docs/getting-started/installation",
  "source": "docs/getting-started/installation.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Start Here",
  "documentType": "Getting started",
  "language": "en",
  "revision": {
    "lastReviewedRevision": "e6222fc36ebd7d8a723d773606c073d5da9cd281",
    "documentationSourceRevision": "9192fef3695ad294994f2712f6d156241e5e92fb",
    "basis": "frontmatter"
  },
  "downloads": {
    "md": "/docs/download/getting-started/installation.md",
    "txt": "/docs/download/getting-started/installation.txt",
    "json": "/docs/download/getting-started/installation.json",
    "pdf": "/docs/download/getting-started/installation.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Install AIP\ndescription: Install signed GetAIP 2.1.0 tools with npm, connect a supported agent, or build from reviewed source\nkind: how-to\naudience: developer\nappliesTo: \"GetAIP 2.1.x / AIP 1.0\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"e6222fc36ebd7d8a723d773606c073d5da9cd281\"\n---\n\n# Install AIP\n\nFor most users, the supported entry point is the public `getaip` npm package.\nIt installs the signed GetAIP 2.1.0 native distribution and can connect a\nsupported agent to the verified GetAIP MCP server. Developers and operators can\nstill build the same CLI, server, and connector-fleet components from a pinned\nsource revision when they need source-level review or a custom artifact.\n\nThe npm package is a verified setup launcher, not a general JavaScript library.\nThe command shown by npm, `npm i getaip`, only adds the launcher to the current\nproject; it does not run setup or connect an agent.\n\n## Install the signed release with npm\n\nYou need:\n\n- Node.js `22.14.0` or newer with npm and `npx`;\n- macOS or Linux on ARM64 or x64;\n- network access to the npm registry and the GetAIP GitHub Release assets;\n- write access to the current user's platform-native data and configuration\n  directories.\n\nInstall or repair the signed native distribution and create the default\nloopback configuration:\n\n```sh\nnpx getaip setup\n```\n\nThis command does not configure an agent unless you also select a client and\nscope. To reproduce the currently reviewed release exactly, pin the package\nversion:\n\n```sh\nnpx getaip@2.1.0 setup\n```\n\nDo not prefix setup with `sudo`. The installer deliberately writes to\nuser-owned platform directories and retains the signed manifest, signature,\nartifact digests, active version, and rollback state for later verification.\n\n## Connect a supported agent\n\nChoose one command for a user-global configuration:\n\n| Agent | Command |\n|---|---|\n| Codex | `npx getaip setup --codex --global` |\n| Claude Code | `npx getaip setup --claude --global` |\n| Cursor | `npx getaip setup --cursor --global` |\n| Gemini CLI | `npx getaip setup --gemini --global` |\n| OpenCode | `npx getaip setup --opencode --global` |\n\nYou can select multiple clients in one command, for example:\n\n```sh\nnpx getaip setup --codex --claude --global\n```\n\nFor a project-local configuration, run setup from the project root and use\n`--project` instead:\n\n```sh\nnpx getaip setup --codex --project\n```\n\nUse `--project-root /absolute/path/to/project` when the target is not the\ncurrent directory. Client configuration requires exactly one scope:\n`--global` or `--project`.\n\n## Preview and verify setup\n\nInspect the signed plan and proposed client mutation without changing the\nfilesystem:\n\n```sh\nnpx getaip setup --codex --global --dry-run\n```\n\nFor automation, request the stable JSON output:\n\n```sh\nnpx getaip setup --codex --global --dry-run --output json\n```\n\nThe npm launcher accepts only the `setup` command. It selects a compatible\nmacOS or Linux bootstrap, verifies the Ed25519-signed release manifest against\nits embedded trust store, enforces bounded downloads and approved GitHub\nrelease redirects, verifies artifact size and SHA-256 identity, and only then\nexecutes native setup. A successful non-dry-run reports the active version and\nevery configured client adapter.\n\n## Build from source\n\nUse the source path for implementation development, reviewed custom builds,\nconnector-fleet assembly, or qualification work. The Rust workspace packages\nremain non-publishable on crates.io, so this procedure starts from a source\ncheckout. A successful build proves that the selected source compiles in the\ncurrent environment; it does not by itself qualify the resulting artifact for\nproduction.\n\n## Choose an installation target\n\nSelect the smallest target that matches the work you intend to perform:\n\n| Target | Build | Use it for |\n|---|---|---|\n| Local native AIP | `getaip-server` and `getaip` | Run a product-neutral daemon and make native or compatibility-profile calls |\n| Connector fleet | `getaip-server`, `getaip`, `aip-connector-control-plane`, and selected standalone hosts | Keep product adapters and credentials outside the central daemon |\n| Legacy migration | `getaip-server-legacy-bundled` | Move an existing bundled deployment to separate connector processes |\n| Rust integration | `aip` facade with selected features | Embed AIP types and product-neutral implementation components in Rust code |\n\nThe `getaip-server` dependency graph contains no product connector crate. Do not use\n`getaip-server-legacy-bundled` for a new deployment; it retains only the older bundled\ncomposition needed during migration.\n\n## Prerequisites\n\nYou need:\n\n- a checkout containing commit\n  `e6222fc36ebd7d8a723d773606c073d5da9cd281`;\n- Rust `1.88` or newer with Cargo, `rustfmt`, and Clippy;\n- write access to a dedicated Cargo target directory;\n- enough local disk space for Rust dependencies and release artifacts.\n\n`rust-toolchain.toml` selects the moving `stable` channel, while `Cargo.toml`\ndeclares Rust `1.88` as the minimum supported version. Repository CI at this\nrevision runs the full Linux jobs on Ubuntu 24.04 and a portable-core subset on\nmacOS 15. It has no Windows job, so use a validated Linux environment for\nrelease-affecting work that would otherwise run on Windows.\n\nCheck the local toolchain before building:\n\n```sh\nrustc --version\ncargo --version\n```\n\nBoth commands must exit successfully, and `rustc` must report version `1.88.0`\nor newer.\n\n## Pin the source revision\n\nRun these commands from the repository root. Inspect local changes before\nswitching revisions:\n\n```sh\ngit status --short\ngit rev-parse --verify e6222fc36ebd7d8a723d773606c073d5da9cd281^{commit}\n```\n\nIf `git status --short` reports work you need, preserve it before continuing.\nThen select the reviewed source in detached-HEAD mode:\n\n```sh\nexport AIP_SOURCE_REVISION=e6222fc36ebd7d8a723d773606c073d5da9cd281\ngit checkout --detach \"$AIP_SOURCE_REVISION\"\ntest \"$(git rev-parse HEAD)\" = \"$AIP_SOURCE_REVISION\"\ntest -z \"$(git status --porcelain)\"\n```\n\nThe last two commands must exit with status `0`. A dirty checkout produces a\ndevelopment artifact whose identity is not the recorded commit alone.\n\n## Build the core tools\n\nBuild the product-neutral daemon and operator CLI with the reviewed lockfile:\n\n```sh\ncargo build --locked --release -p getaip-server -p getaip-cli\n```\n\nCargo writes the binaries to `target/release/getaip-server` and\n`target/release/getaip` unless `CARGO_TARGET_DIR` is set. Verify both command\nsurfaces without starting a service:\n\n```sh\ntarget/release/getaip-server --help\ntarget/release/getaip --help\n```\n\nTo place these commands in Cargo's binary directory instead, install the same\nsource paths with the lockfile enforced:\n\n```sh\ncargo install --locked --path crates/getaip-server\ncargo install --locked --path crates/getaip-cli\n```\n\nCargo normally installs them under `$HOME/.cargo/bin`. This path installation\nis permitted even though the packages are not publishable.\n\n## Build connector-fleet components\n\nA fleet adds the standalone lifecycle control plane and one host binary for\neach selected product boundary. The maintained product-host packages are:\n\n| Connector | Host package and binary |\n|---|---|\n| Cal.diy | `aip-host-cal-diy` |\n| Hermes Agent | `aip-host-hermes-agent` |\n| Chatwoot | `aip-host-chatwoot` |\n| Dify | `aip-host-dify` |\n| CrewAI | `aip-host-crewai` |\n| Twenty | `aip-host-twenty` |\n\nFor example, build a core daemon, control plane, CLI, and Cal.diy host:\n\n```sh\ncargo build --locked --release \\\n  -p getaip-server \\\n  -p getaip-cli \\\n  -p aip-connector-control-plane \\\n  -p aip-host-cal-diy\n```\n\nReplace or add host packages only for the connectors admitted by the target\ndeployment. Compiling a host does not admit it, create registry credentials, or\nqualify its provider behavior.\n\nFor an existing bundled deployment that is being migrated, build the legacy\nbinary explicitly and keep it separate from the new core artifact:\n\n```sh\ncargo build --locked --release -p getaip-server-legacy-bundled\n```\n\n## Use AIP from Rust\n\nThe `aip` facade defaults to the semantic core. New applications that need the\ncomplete product-neutral implementation surface should select `full-core` at\nthe same pinned revision:\n\n```toml\n[dependencies]\naip = { git = \"https://github.com/getaip/core\", rev = \"e6222fc36ebd7d8a723d773606c073d5da9cd281\", features = [\"full-core\"] }\n```\n\nThe legacy `full` feature also selects product connector features. Do not use it\nas a shortcut for a new product-neutral integration. Product connectors remain\nseparate packages and processes at the fleet boundary.\n\n## Add runtime dependencies only when required\n\nThe binaries can be built without starting external services. Runtime\nrequirements depend on the selected topology:\n\n| Dependency | Required when |\n|---|---|\n| PostgreSQL | A deployment uses shared durable runtime state, connector registry state, or production connector-host bootstrap |\n| NATS | The deployment enables the native NATS transport |\n| Product credentials | A selected connector host calls its external product |\n| Docker with Compose and BuildKit | An operator runs the repository's isolated qualification stacks |\n\nThe local native quickstart uses file-backed state and does not require\nPostgreSQL, NATS, Docker, or product credentials.\n\n## Verify the installation\n\nConfirm the source identity and the installed command surfaces:\n\n```sh\ntest \"$(git rev-parse HEAD)\" = \"$AIP_SOURCE_REVISION\"\ntest -z \"$(git status --porcelain)\"\ntarget/release/getaip-server --help >/dev/null\ntarget/release/getaip --help >/dev/null\ncargo metadata --locked --offline --no-deps --format-version 1 >/dev/null\n```\n\nIf you built fleet components, run `--help` on the control-plane binary and\neach selected host as well. Record the source revision, Cargo metadata, build\nprofile, and artifact digest before qualification or deployment. A tag, source\ncheckout, compiled binary, container image, and running deployment are distinct\nartifact identities.\n\n## Resolve build failures\n\n| Symptom | Decision |\n|---|---|\n| `rustc` is older than `1.88` | Install or select a newer stable Rust toolchain, then rerun the same locked build |\n| Cargo reports that `Cargo.lock` must change | Confirm the source revision and restore its lockfile; do not remove `--locked` |\n| Cargo cannot work offline during final verification | Complete the locked build so dependencies are present, then rerun the verification command |\n| The linker or filesystem reports insufficient space | Inspect the configured target directory and remove only artifacts whose rebuild cost is acceptable |\n| A binary reports missing runtime configuration | Treat the build as installed and follow the configuration guide; rebuilding does not create credentials or deployment state |\n| The build is being attempted on Windows | Move release-affecting work to a validated Linux environment until a Windows job and qualification scope exist |\n\n`cargo clean` acts on the target directory selected by the current invocation.\nReview its scope first when `CARGO_TARGET_DIR` is shared by multiple checkouts.\nDocker cleanup affects shared machine state and is not an installation repair.\n\n## Remove a local installation\n\nIf the binaries were installed into Cargo's binary directory, remove only the\nnamed packages:\n\n```sh\ncargo uninstall getaip-server\ncargo uninstall getaip-cli\n```\n\nFor binaries that were only built in the checkout, remove their Cargo build\nartifacts with:\n\n```sh\ncargo clean -p getaip-server -p getaip-cli\n```\n\nRemove selected control-plane or host packages by name only when they were part\nof the installation. Uninstalling binaries does not remove runtime databases,\ncredential files, registry state, or product-side effects; review those assets\nthrough the applicable deployment or connector runbook.\n\n## Related pages\n\n- [Quickstart](quickstart.md)\n- [Connector fleet quickstart](connector-fleet-quickstart.md)\n- [Profiles, transports, and connectors](../concepts/profiles-and-connectors.md)\n- [Production deployment](../guides/production-deployment.md)\n- [Release artifacts](../reference/release-artifacts.md)\n",
    "text": "Install AIP\n\nFor most users, the supported entry point is the public getaip npm package.\nIt installs the signed GetAIP 2.1.0 native distribution and can connect a\nsupported agent to the verified GetAIP MCP server. Developers and operators can\nstill build the same CLI, server, and connector-fleet components from a pinned\nsource revision when they need source-level review or a custom artifact.\n\nThe npm package is a verified setup launcher, not a general JavaScript library.\nThe command shown by npm, npm i getaip, only adds the launcher to the current\nproject; it does not run setup or connect an agent.\n\nInstall the signed release with npm\n\nYou need:\n\n- Node.js 22.14.0 or newer with npm and npx;\n- macOS or Linux on ARM64 or x64;\n- network access to the npm registry and the GetAIP GitHub Release assets;\n- write access to the current user's platform-native data and configuration directories.\n\nInstall or repair the signed native distribution and create the default\nloopback configuration:\n\nnpx getaip setup\n\nThis command does not configure an agent unless you also select a client and\nscope. To reproduce the currently reviewed release exactly, pin the package\nversion:\n\nnpx getaip@2.1.0 setup\n\nDo not prefix setup with sudo. The installer deliberately writes to\nuser-owned platform directories and retains the signed manifest, signature,\nartifact digests, active version, and rollback state for later verification.\n\nConnect a supported agent\n\nChoose one command for a user-global configuration:\n\nAgent | Command\nCodex | npx getaip setup --codex --global\nClaude Code | npx getaip setup --claude --global\nCursor | npx getaip setup --cursor --global\nGemini CLI | npx getaip setup --gemini --global\nOpenCode | npx getaip setup --opencode --global\n\nYou can select multiple clients in one command, for example:\n\nnpx getaip setup --codex --claude --global\n\nFor a project-local configuration, run setup from the project root and use\n--project instead:\n\nnpx getaip setup --codex --project\n\nUse --project-root /absolute/path/to/project when the target is not the\ncurrent directory. Client configuration requires exactly one scope:\n--global or --project.\n\nPreview and verify setup\n\nInspect the signed plan and proposed client mutation without changing the\nfilesystem:\n\nnpx getaip setup --codex --global --dry-run\n\nFor automation, request the stable JSON output:\n\nnpx getaip setup --codex --global --dry-run --output json\n\nThe npm launcher accepts only the setup command. It selects a compatible\nmacOS or Linux bootstrap, verifies the Ed25519-signed release manifest against\nits embedded trust store, enforces bounded downloads and approved GitHub\nrelease redirects, verifies artifact size and SHA-256 identity, and only then\nexecutes native setup. A successful non-dry-run reports the active version and\nevery configured client adapter.\n\nBuild from source\n\nUse the source path for implementation development, reviewed custom builds,\nconnector-fleet assembly, or qualification work. The Rust workspace packages\nremain non-publishable on crates.io, so this procedure starts from a source\ncheckout. A successful build proves that the selected source compiles in the\ncurrent environment; it does not by itself qualify the resulting artifact for\nproduction.\n\nChoose an installation target\n\nSelect the smallest target that matches the work you intend to perform:\n\nTarget | Build | Use it for\nLocal native AIP | getaip-server and getaip | Run a product-neutral daemon and make native or compatibility-profile calls\nConnector fleet | getaip-server, getaip, aip-connector-control-plane, and selected standalone hosts | Keep product adapters and credentials outside the central daemon\nLegacy migration | getaip-server-legacy-bundled | Move an existing bundled deployment to separate connector processes\nRust integration | aip facade with selected features | Embed AIP types and product-neutral implementation components in Rust code\n\nThe getaip-server dependency graph contains no product connector crate. Do not use\ngetaip-server-legacy-bundled for a new deployment; it retains only the older bundled\ncomposition needed during migration.\n\nPrerequisites\n\nYou need:\n\n- a checkout containing commit e6222fc36ebd7d8a723d773606c073d5da9cd281;\n- Rust 1.88 or newer with Cargo, rustfmt, and Clippy;\n- write access to a dedicated Cargo target directory;\n- enough local disk space for Rust dependencies and release artifacts.\n\nrust-toolchain.toml selects the moving stable channel, while Cargo.toml\ndeclares Rust 1.88 as the minimum supported version. Repository CI at this\nrevision runs the full Linux jobs on Ubuntu 24.04 and a portable-core subset on\nmacOS 15. It has no Windows job, so use a validated Linux environment for\nrelease-affecting work that would otherwise run on Windows.\n\nCheck the local toolchain before building:\n\nrustc --version\ncargo --version\n\nBoth commands must exit successfully, and rustc must report version 1.88.0\nor newer.\n\nPin the source revision\n\nRun these commands from the repository root. Inspect local changes before\nswitching revisions:\n\ngit status --short\ngit rev-parse --verify e6222fc36ebd7d8a723d773606c073d5da9cd281^{commit}\n\nIf git status --short reports work you need, preserve it before continuing.\nThen select the reviewed source in detached-HEAD mode:\n\nexport AIP_SOURCE_REVISION=e6222fc36ebd7d8a723d773606c073d5da9cd281\ngit checkout --detach \"$AIP_SOURCE_REVISION\"\ntest \"$(git rev-parse HEAD)\" = \"$AIP_SOURCE_REVISION\"\ntest -z \"$(git status --porcelain)\"\n\nThe last two commands must exit with status 0. A dirty checkout produces a\ndevelopment artifact whose identity is not the recorded commit alone.\n\nBuild the core tools\n\nBuild the product-neutral daemon and operator CLI with the reviewed lockfile:\n\ncargo build --locked --release -p getaip-server -p getaip-cli\n\nCargo writes the binaries to target/release/getaip-server and\ntarget/release/getaip unless CARGO_TARGET_DIR is set. Verify both command\nsurfaces without starting a service:\n\ntarget/release/getaip-server --help\ntarget/release/getaip --help\n\nTo place these commands in Cargo's binary directory instead, install the same\nsource paths with the lockfile enforced:\n\ncargo install --locked --path crates/getaip-server\ncargo install --locked --path crates/getaip-cli\n\nCargo normally installs them under $HOME/.cargo/bin. This path installation\nis permitted even though the packages are not publishable.\n\nBuild connector-fleet components\n\nA fleet adds the standalone lifecycle control plane and one host binary for\neach selected product boundary. The maintained product-host packages are:\n\nConnector | Host package and binary\nCal.diy | aip-host-cal-diy\nHermes Agent | aip-host-hermes-agent\nChatwoot | aip-host-chatwoot\nDify | aip-host-dify\nCrewAI | aip-host-crewai\nTwenty | aip-host-twenty\n\nFor example, build a core daemon, control plane, CLI, and Cal.diy host:\n\ncargo build --locked --release \\\n  -p getaip-server \\\n  -p getaip-cli \\\n  -p aip-connector-control-plane \\\n  -p aip-host-cal-diy\n\nReplace or add host packages only for the connectors admitted by the target\ndeployment. Compiling a host does not admit it, create registry credentials, or\nqualify its provider behavior.\n\nFor an existing bundled deployment that is being migrated, build the legacy\nbinary explicitly and keep it separate from the new core artifact:\n\ncargo build --locked --release -p getaip-server-legacy-bundled\n\nUse AIP from Rust\n\nThe aip facade defaults to the semantic core. New applications that need the\ncomplete product-neutral implementation surface should select full-core at\nthe same pinned revision:\n\n[dependencies]\naip = { git = \"https://github.com/getaip/core\", rev = \"e6222fc36ebd7d8a723d773606c073d5da9cd281\", features = [\"full-core\"] }\n\nThe legacy full feature also selects product connector features. Do not use it\nas a shortcut for a new product-neutral integration. Product connectors remain\nseparate packages and processes at the fleet boundary.\n\nAdd runtime dependencies only when required\n\nThe binaries can be built without starting external services. Runtime\nrequirements depend on the selected topology:\n\nDependency | Required when\nPostgreSQL | A deployment uses shared durable runtime state, connector registry state, or production connector-host bootstrap\nNATS | The deployment enables the native NATS transport\nProduct credentials | A selected connector host calls its external product\nDocker with Compose and BuildKit | An operator runs the repository's isolated qualification stacks\n\nThe local native quickstart uses file-backed state and does not require\nPostgreSQL, NATS, Docker, or product credentials.\n\nVerify the installation\n\nConfirm the source identity and the installed command surfaces:\n\ntest \"$(git rev-parse HEAD)\" = \"$AIP_SOURCE_REVISION\"\ntest -z \"$(git status --porcelain)\"\ntarget/release/getaip-server --help >/dev/null\ntarget/release/getaip --help >/dev/null\ncargo metadata --locked --offline --no-deps --format-version 1 >/dev/null\n\nIf you built fleet components, run --help on the control-plane binary and\neach selected host as well. Record the source revision, Cargo metadata, build\nprofile, and artifact digest before qualification or deployment. A tag, source\ncheckout, compiled binary, container image, and running deployment are distinct\nartifact identities.\n\nResolve build failures\n\nSymptom | Decision\nrustc is older than 1.88 | Install or select a newer stable Rust toolchain, then rerun the same locked build\nCargo reports that Cargo.lock must change | Confirm the source revision and restore its lockfile; do not remove --locked\nCargo cannot work offline during final verification | Complete the locked build so dependencies are present, then rerun the verification command\nThe linker or filesystem reports insufficient space | Inspect the configured target directory and remove only artifacts whose rebuild cost is acceptable\nA binary reports missing runtime configuration | Treat the build as installed and follow the configuration guide; rebuilding does not create credentials or deployment state\nThe build is being attempted on Windows | Move release-affecting work to a validated Linux environment until a Windows job and qualification scope exist\n\ncargo clean acts on the target directory selected by the current invocation.\nReview its scope first when CARGO_TARGET_DIR is shared by multiple checkouts.\nDocker cleanup affects shared machine state and is not an installation repair.\n\nRemove a local installation\n\nIf the binaries were installed into Cargo's binary directory, remove only the\nnamed packages:\n\ncargo uninstall getaip-server\ncargo uninstall getaip-cli\n\nFor binaries that were only built in the checkout, remove their Cargo build\nartifacts with:\n\ncargo clean -p getaip-server -p getaip-cli\n\nRemove selected control-plane or host packages by name only when they were part\nof the installation. Uninstalling binaries does not remove runtime databases,\ncredential files, registry state, or product-side effects; review those assets\nthrough the applicable deployment or connector runbook.\n\nRelated pages\n\n- Quickstart\n- Connector fleet quickstart\n- Profiles, transports, and connectors\n- Production deployment\n- Release artifacts\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "1c06790685cf03a1c7d5e8ab95c6819474b7315d93ffa1ee1bb10fe76e65e9fa"
  }
}