---
draft: false
title: Installation
description: Install AgentsMesh via Homebrew, a standalone binary, or any Node.js package manager (npm, pnpm, yarn, npx). Works on Linux, macOS, and Windows.
sidebar:
  order: 1
---

import { Tabs, TabItem, Aside } from '@astrojs/starlight/components';

AgentsMesh ships three ways. Pick whichever matches your environment — every install method delivers the same CLI (`agentsmesh` and the shorter alias `amsh`) and the same TypeScript library.

## Quick install

<Tabs>
  <TabItem label="Homebrew (macOS / Linux)">
    No Node.js required.

    ```bash
    brew tap samplexbro/agentsmesh
    brew install agentsmesh
    ```
  </TabItem>
  <TabItem label="Standalone binary">
    No Node.js required. Linux, macOS, and Windows binaries are published with each release.

    ```bash
    curl -fsSL https://github.com/sampleXbro/agentsmesh/releases/latest/download/install.sh | sh
    ```

    Or download a binary directly from [GitHub Releases](https://github.com/sampleXbro/agentsmesh/releases/latest).
  </TabItem>
  <TabItem label="npm / pnpm / yarn">
    Requires Node.js 20+. Recommended when AgentsMesh is part of a Node.js project's dev tooling so it's pinned per repo.

    ```bash
    # Global install
    npm install -g agentsmesh

    # Or as a dev dependency
    npm install -D agentsmesh        # npm
    pnpm add -D agentsmesh           # pnpm
    yarn add -D agentsmesh           # yarn

    # Or run without installing
    npx agentsmesh --help
    ```
  </TabItem>
</Tabs>

## Platform support

Linux, macOS, and **Windows** (native, not WSL).

<Aside type="tip">
  **Windows support** is first-class for every install method: paths are normalized internally so generated configs and `installs.yaml` are portable across platforms. Watch mode uses polling on Windows because `ReadDirectoryChangesW` can miss just-created files in tmpdirs. CI runs the full test suite on Linux, macOS, and Windows.
</Aside>

## Which install method should I use?

| Method | Requires Node.js | Best for |
|--------|:----------------:|---------|
| **Homebrew** | No | macOS / Linux engineers who want a single managed install |
| **Standalone binary** | No | CI runners without Node, locked-down environments, Windows users without npm |
| **npm / pnpm / yarn (`-D`)** | Yes | Node.js projects — pins AgentsMesh per repo so teammates and CI get the exact same version |
| **npx** | Yes | Trying it out, one-off commands in Node.js projects |

## Verify installation

```bash
agentsmesh --version
agentsmesh --help
```

Both `agentsmesh` and the shorter `amsh` alias resolve to the same CLI regardless of install method.

## IDE autocomplete via JSON Schema

Every canonical config file ships with a generated JSON Schema, so VS Code, JetBrains, and other editors give you autocomplete and validation out of the box. `agentsmesh init` and `agentsmesh install` stamp the appropriate `# yaml-language-server: $schema=...` directive (or `$schema` field for JSON) into every file at write time. The URL is pinned to the running package version so the schema referenced always matches the format the file was written with.

| Config file | Schema | Written by |
|---|---|---|
| `agentsmesh.yaml` / `agentsmesh.local.yaml` | `schemas/agentsmesh.json` | `init` |
| `.agentsmesh/hooks.yaml` | `schemas/hooks.json` | `init` |
| `.agentsmesh/permissions.yaml` | `schemas/permissions.json` | `init` |
| `.agentsmesh/mcp.json` | `schemas/mcp.json` | `init` |
| `.agentsmesh/installs.yaml` | `schemas/installs.json` | `install` / `uninstall` |
| `.agentsmesh/packs/<name>/pack.yaml` | `schemas/pack.json` | `install` |
| `.agentsmesh/packs/<name>/.agentsmesh-install-manifest.json` | `schemas/install-manifest.json` | `install` |

All schemas resolve via the published `https://unpkg.com/agentsmesh@<version>/schemas/<name>.json` URLs (no extension required when AgentsMesh is in `node_modules/`). VS Code needs the [Red Hat YAML extension](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml); JetBrains IDEs honor the directive out of the box. See the [JSON Schemas reference](../../reference/json-schemas/) for the full breakdown, CI validation examples, and SchemaStore plans.

## Use as a TypeScript / Node.js library

In addition to the CLI, AgentsMesh exports a typed programmatic API for scripts, IDE extensions, and CI tooling. This path requires Node.js 20+ and `npm install agentsmesh` (or pnpm/yarn equivalent).

```typescript
import { generate, importFrom, loadCanonical } from 'agentsmesh';
```

See the [programmatic API reference](../../reference/programmatic-api/) for the full entrypoint table.

## Add scripts to package.json

If you installed via npm/pnpm/yarn, wire AgentsMesh into your project scripts:

```json
{
  "scripts": {
    "sync": "agentsmesh generate",
    "sync:check": "agentsmesh check",
    "sync:watch": "agentsmesh watch"
  }
}
```

## Next step

Continue to [Quick Start](./quick-start/) to scaffold your first canonical config directory.
