> For the complete documentation index, see [llms.txt](https://docs.apono.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.apono.io/docs/agent-privilege-guard/apono-agentic-gateway/install-the-local-agentic-gateway.md).

# Install the Local Agentic Gateway

Connect an AI client to Apono from a user’s machine

The **Local Agentic Gateway** connects a supported AI client to Apono from the user's machine. It runs over STDIO, is launched with `npx`, and brokers agent requests and tool calls through Apono.

This guide covers the local installation for supported AI clients and operating systems. For Apono account configuration, platform-specific prerequisites, and functional verification, follow the applicable Agentic Access setup guide.

{% hint style="success" icon="lightbulb" %}
To deploy the gateway centrally instead of installing it on each user's machine, see [Deploy the Remote Agentic Gateway.](/docs/agent-privilege-guard/apono-agentic-gateway/deploy-the-remote-agentic-gateway.md) The Remote Agentic Gateway is available in private beta.
{% endhint %}

***

### How the Local Agentic Gateway works

During initial setup and first use, the Local Agentic Gateway performs the following operations:

1. **The gateway starts**. `npx` downloads and launches the Local Agentic Gateway.
2. **The user signs in to Apono**. With the quick start installation, the installer signs you in during installation. With manual installation, a browser tab opens for authentication. The session is stored locally and reused until it expires.
3. **Apono registers the agent**. The agent is linked to the signed-in user and appears on the AI Agents tab.
4. **The client can send tool calls**. The gateway begins brokering requests between the AI client and Apono.

***

### Prerequisites

<table><thead><tr><th width="211.92578125">Item</th><th>Details</th></tr></thead><tbody><tr><td><strong>Apono account setup completed</strong></td><td><p>Enablement of MCP feature for the Apono account</p><p>Confirm that an Apono admin has <a href="/docs/agent-privilege-guard/set-up-apono-agent-privilege-guard.md">set up Apono Agent Privilege Guard</a>:</p><ul><li>Enabled MCP features</li><li>Connected the applicable integration</li><li>Created an agentic access flow with <strong>Restrict to agentic access</strong> enabled</li><li>Enabled the corresponding Apono Managed MCP</li></ul></td></tr><tr><td><strong>Platform-specific setup</strong></td><td><p>Apono Managed MCPs require additional local runtimes</p><p>Review the prerequisites in the applicable platform setup guide before connecting your AI client.</p></td></tr><tr><td><strong>Supported operating systems</strong></td><td><p>Supported operating systems:</p><ul><li>macOS, Linux</li><li>Windows 11 (native)</li><li>WSL2 (Ubuntu)</li></ul></td></tr><tr><td><strong>Node.js 20+</strong></td><td><p>Required runtime</p><p><br>The gateway is launched with <code>npx</code>, which runs <code>@apono-io/apono-mcp@latest</code>, downloads the gateway binary, and manages the Apono sign-in. No separate Apono CLI installation is required.<br><br>When using the quick start installation below, the installer checks for Node.js 20+ and <code>npx</code> but does not install them. If either is missing, the installer provides the applicable installation command and exits without making changes.</p></td></tr><tr><td><strong>AI client</strong></td><td><p>Supported AI client</p><p><br>Claude Code, Claude Desktop, and Cursor are currently supported.</p></td></tr></tbody></table>

***

### Configure your AI client

{% hint style="info" %}
If the Local Agentic Gateway is already configured for this client, return to the applicable [platform setup guide](/docs/agent-privilege-guard/set-up-apono-agent-privilege-guard.md) to verify access.
{% endhint %}

To connect your AI client to Apono, configure the Local Agentic Gateway as an MCP server.

Choose one of the following installation methods based on your environment and preferred setup approach:

* [Quick start installation](#quick-start-installation): (Recommended) Automatically configure supported AI clients installed on your machine
* [Manual installation](#manual-installation): Configure selected AI clients individually using client-specific instructions

#### Quick start installation

The quick start installation uses a single shell command to install the Local Agentic Gateway and configure supported AI clients installed on your machine.

The installer:

* Checks for installation prerequisites
* Registers any detected Claude Code, Claude Desktop, and Cursor installations
* Warns about a directory-scoped Claude Code entry that would hide the new one
* Signs you in
* Offers the credential guardrails

Follow these steps:

1. Run the shell command for your operating system.

{% tabs %}
{% tab title="macOS, Linux" %}
{% code overflow="wrap" %}

```shellscript
curl -fsSL https://apono-agentic-releases.s3.amazonaws.com/install.sh | bash
```

{% endcode %}
{% endtab %}

{% tab title="WSL2 (Ubuntu)" %}
{% code overflow="wrap" %}

```shellscript
curl -fsSL https://apono-agentic-releases.s3.amazonaws.com/install.sh | bash
```

{% endcode %}

{% hint style="info" %}
Run the installer once from within Windows Subsystem for Linux (WSL). It configures Claude Code in Linux and Claude Desktop and Cursor on Windows, with all three clients sharing one Apono sign-in. Claude Desktop and Cursor launch the gateway through WSL.

**Do not run the Windows 11 installer separately.**

If `WSL_DISTRO_NAME` is not set, Windows clients launch the gateway in your default WSL distribution. The installer displays a warning when this occurs.
{% endhint %}
{% endtab %}

{% tab title="Windows 11 (native)" %}
In PowerShell:

{% code overflow="wrap" %}

```powershell
irm https://apono-agentic-releases.s3.amazonaws.com/install.ps1 | iex
```

{% endcode %}
{% endtab %}
{% endtabs %}

2. At the end of the installation, choose whether to apply the optional credential guardrails.

{% hint style="info" %}
Optional credential guardrails are written to client configuration files (including **settings.json**) to prevent AI clients from accessing local cloud credentials.

* **Claude Code**: Adds deny rules for `~/.aws/**`, `~/.kube/config`, `aws`, and `aws-vault`
* **Cursor**: Adds instructions to refuse the same commands

The installer requests permission before modifying configurations, preserves existing settings, and backs up modified files.

These guardrails rely on AI-client behavior and are not enforced by the operating system.
{% endhint %}

#### Manual installation

Manual installation lets you configure the Local Agentic Gateway for individual AI clients using their respective MCP setup methods.

Depending on the AI client, setup involves:

* Adding the gateway as an MCP server using a command, configuration file, or installation link
* Restarting the AI client, if required, to apply the configuration
* Signing in to Apono when the gateway starts for the first time

Select your AI client below and follow the installation instructions.

{% tabs %}
{% tab title="Claude Code" %}
Follow these steps:

1. Run the following command for your operating system. If this is the first run, a separate browser tab opens.

**macOS**

{% code overflow="wrap" %}

```shellscript
claude mcp add apono-agentic --npx -y @apono-io/apono-mcp@latest --agent-type claude-code
```

{% endcode %}

**Windows 11 (native)**

In Command Prompt or PowerShell:

{% code overflow="wrap" expandable="true" %}

```powershell
claude.cmd mcp add apono-agentic --npx -y @apono-io/apono-mcp@latest --agent-type claude-code
```

{% endcode %}

**WSL2 (Ubuntu)**

{% code overflow="wrap" expandable="true" %}

```shellscript
claude mcp add apono-agentic --npx -y @apono-io/apono-mcp@latest --agent-type claude-code
```

{% endcode %}

2. (First run only) Log in to Apono in the open browser tab.
   {% endtab %}

{% tab title="Claude Desktop" %}
Follow these steps:

1. In Claude, from the main navigation, click **Claude > Settings > Developer**. The **Settings** page appears.
2. Click **Edit Config**. The **claude\_desktop\_config.json** file opens.
3. Add the following configuration.

{% code overflow="wrap" %}

```json
{
  "mcpServers": {
    "apono-agentic": {
      "command": "npx",
      "args": ["-y", "@apono-io/apono-mcp@latest", "--agent-type", "claude-desktop"]
    }
  }
}
```

{% endcode %}

4. Save the file.
5. Quit and restart Claude desktop.
6. (First run only) Log in to Apono in the browser tab that opens.
   {% endtab %}

{% tab title="Cursor" %}
**Installation link**

Follow these steps:

1. Click the following button to install the MCP Server. The **MCP** page in Cursor opens.

<a href="cursor://anysphere.cursor-deeplink/mcp/install?name=apono-agentic&#x26;config=eyJjb21tYW5kIjoibnB4IC15IEBhcG9uby1pby9hcG9uby1tY3BAbGF0ZXN0IC0tYWdlbnQtdHlwZSBjdXJzb3IifQ%3D%3D" class="button primary">Add to Cursor</a>

2. Click **Install**.
3. Quit and restart Cursor.
4. (First run only) Log in to Apono in the browser tab that opens.

***

**Configuration file**

Follow these steps:

1. In Cursor, from the main navigation, click **Tools & MCPs**. The **Tools** page appears.
2. Under **Home MCP Servers**, click **New MCP Server**. The **mcp.json** file opens.
3. Add the following configuration.

{% code overflow="wrap" %}

```json
{
  "mcpServers": {
    "apono-agentic": {
      "command": "npx",
      "args": ["-y", "@apono-io/apono-mcp@latest", "--agent-type", "cursor"]
    }
  }
}
```

{% endcode %}

4. Save the file.
5. Quit and restart Cursor.
6. (First run only) Log in to Apono in the browser tab that opens.
   {% endtab %}
   {% endtabs %}

#### Gateway options

Add the applicable gateway options to your AI client’s MCP configuration. Restart the client to apply any changes.

<table><thead><tr><th width="184.2939453125">Option</th><th>Description</th></tr></thead><tbody><tr><td><code>--agent-type</code></td><td><p><strong>(Required)</strong> Identifies the AI client running the gateway</p><p>The client-specific configurations above include the applicable value.</p></td></tr><tr><td><code>--debug</code></td><td>Enables verbose request and response logging while investigating a problem</td></tr></tbody></table>

***

### Verify the gateway connection

After the first successful start, confirm that the agent appears and is linked to your user on the **AI Agents** tab.

If the agent does not appear, continue to [Troubleshoot the Local Agentic Gateway](#troubleshoot-the-local-agentic-gateway).

After confirming the gateway connection, return to the applicable platform setup guide to verify platform access.

***

### Troubleshoot the Local Agentic Gateway

<details>

<summary>No targets or integrations are listed.</summary>

Follow these steps:

1. Reauthenticate to Apono.

{% code overflow="wrap" expandable="true" %}

```shellscript
npx -y @apono-io/apono-mcp@latest login
```

{% endcode %}

2. Fully restart the AI client so the updated credentials take effect.
3. If the target is still unavailable, confirm with an Apono admin that the platform setup is complete. This includes the integration, agentic access flow, MCP feature enablement, and applicable Apono Managed MCP.
4. Follow the troubleshooting instructions in the applicable platform setup guide.

</details>

<details>

<summary>The gateway is registered but the agent does not appear in Claude Code.</summary>

Claude Code prioritizes project-specific MCP server configurations over user-level configurations. An existing apono-agentic entry in a project directory can therefore override the entry created by the installer.

The installer identifies affected directories. From each affected directory, run `claude mcp remove apono-agentic -s local` to remove the old entry. Then start a new Claude Code session.

</details>

<details>

<summary>Claude Desktop was skipped on Windows.</summary>

If Claude Desktop was installed from the Microsoft Store but never opened, it has no config file yet. Open it once, then run the installer again.

</details>

<details>

<summary>The Apono sign-in does not open or must be refreshed.</summary>

Follow these steps:

1. Start a new Apono sign-in.

{% code overflow="wrap" expandable="true" %}

```shellscript
npx -y @apono-io/apono-mcp@latest login
```

{% endcode %}

2. Fully restart the AI client so the updated credentials take effect.

</details>

<details>

<summary>More details are needed on failures.</summary>

Add `--debug` to the gateway's args in your client config to enable verbose request/response logging, then check the gateway log.

</details>

<details>

<summary>Configuration changes are not reflected in the agent.</summary>

Fully restart the client. MCP servers are only launched at startup.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.apono.io/docs/agent-privilege-guard/apono-agentic-gateway/install-the-local-agentic-gateway.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.