> For the complete documentation index, see [llms.txt](https://docs.nexos.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nexos.ai/gateway-api/integrations/jetbrains-air-integration.md).

# JetBrains Air Integration

Learn how to connect JetBrains Air to the nexos.ai API Gateway through ACP agents, so every agent task in Air runs on models from your nexos.ai workspace.

Connecting JetBrains Air to nexos.ai lets you delegate coding tasks to Claude Agent, Codex, or OpenCode inside your JetBrains IDE while routing all model traffic through the gateway instead of authenticating with each provider separately. This guide covers installation, agent configuration, model selection, and troubleshooting.

### What is JetBrains Air? <a href="#what-is-jetbrains-air" id="what-is-jetbrains-air"></a>

JetBrains Air is an agentic development environment from JetBrains. You start a session, pick an agent and model, and Air runs the agent against your codebase while you review the diffs and commit from the IDE. Air runs as a plugin inside JetBrains IDEs (IntelliJ IDEA, GoLand, PyCharm, WebStorm, and others) and in the browser (Air Teams).

Air works with built-in agents (Claude, Codex, Junie, OpenCode, Gemini CLI, GitHub Copilot) and with any agent that supports the **Agent Client Protocol (ACP)**. Custom ACP agents are configured in an `acp.json` file, which accepts per-agent environment variables. This is how you point an agent at nexos.ai.

#### JetBrains Air key features <a href="#jetbrains-air-key-features" id="jetbrains-air-key-features"></a>

* **Multi-Agent Support** – run Claude, Codex, Junie, OpenCode, Copilot, and any other ACP-compatible agent from a single interface.
* **Parallel Sessions** – keep several sessions open side by side and track changed files and outgoing commits across all of them.
* **Review in Context** – open diffs directly from an agent session, validate changes with IDE tools, and comment on specific lines.
* **Precise Task Context** – attach a specific line, commit, class, or method to a session so the agent works with exactly what you point it at.
* **Permission Modes** – control what an agent can do without asking, from read-only planning to autonomous edits.
* **MCP Servers** – connect external tools to agents through the Model Context Protocol.
* **Flexible Provider Access** – use a JetBrains AI subscription, your own provider account, or custom ACP agents that bring their own endpoint, such as nexos.ai.

***

### Prerequisites <a href="#prerequisites" id="prerequisites"></a>

* A JetBrains IDE, version 2026.2 or later, with the **Air** plugin installed. In the IDE, go to `Settings` -> `Plugins` -> `Marketplace`, search for `Air`, click `Install`, and restart the IDE. You can also install it from the [JetBrains Marketplace](https://plugins.jetbrains.com/plugin/33314-air-alpha).
* Node.js 22 or later (for the Claude Agent and Codex ACP adapters).
* A nexos.ai team or user API key.
* Base URL: `https://api.nexos.ai/v1` for OpenAI-compatible agents, or `https://api.nexos.ai` for Claude Agent, which appends `/v1/messages` itself.
* To check which models are available to you, call [Gateway API Models](https://docs.nexos.ai/gateway-api/models). You can use either `nexos_model_id` or `id` as the model.

{% hint style="info" %}
**Note:** The built-in agents in Air's **New Session** menu (**Claude**, **Codex**, **OpenCode**, and others) use your own vendor accounts or local tool configuration. To route Air through nexos.ai, add the agents as **custom ACP agents** as described below. They appear in the menu as separate entries, such as **Claude (nexos.ai)**.
{% endhint %}

***

### Integrating JetBrains Air with nexos.ai <a href="#integrating-jetbrains-air-with-nexos.ai" id="integrating-jetbrains-air-with-nexos.ai"></a>

Choose the agent you want to run in Air. You can configure one, two, or all three. Each one appears as a separate entry in Air's **New Session** menu.

| **Agent**    | **nexos.ai endpoint**        | **Best for**                                      |
| ------------ | ---------------------------- | ------------------------------------------------- |
| Claude Agent | Anthropic Messages API       | Anthropic models, the Claude Code experience      |
| OpenCode     | OpenAI-compatible Chat API   | Any model in your workspace (Claude, GPT, Gemini) |
| Codex        | OpenAI Responses or Chat API | OpenAI models, the Codex experience               |

#### 1. Create the ACP configuration file <a href="#id-1.-create-the-acp-configuration-file" id="id-1.-create-the-acp-configuration-file"></a>

Air reads custom ACP agents from `acp.json` in the `.jetbrains` folder of your home directory:

* **macOS / Linux:** `~/.jetbrains/acp.json`
* **Windows:** `%USERPROFILE%\.jetbrains\acp.json`

The file is not created automatically. Create it if it does not exist:

{% code lineNumbers="true" %}

```shellscript
mkdir -p ~/.jetbrains 
touch ~/.jetbrains/acp.json
```

{% endcode %}

Each entry under `agent_servers` has:

* **Key** (for example, `Claude (nexos.ai)`): the label shown in the **New Session** menu
* `command`: the executable that runs the agent
* `args`: the arguments that start the agent's ACP server
* `env`: optional environment variables passed to the agent

{% hint style="warning" %}
**Important:** Put your API key and base URL in the `env` block, not only in your shell profile. This way the agent always gets the right credentials, no matter how the IDE was started.
{% endhint %}

***

#### 2A. Claude Agent via nexos.ai <a href="#id-2a.-claude-agent-via-nexos.ai" id="id-2a.-claude-agent-via-nexos.ai"></a>

nexos.ai exposes an endpoint compatible with the Anthropic Messages API, so Claude Agent talks to the gateway directly.

**Install the Claude Agent ACP adapter:**

{% code lineNumbers="true" %}

```
npm install -g @agentclientprotocol/claude-agent-acp
```

{% endcode %}

**Add the agent to** `acp.json`**:**

{% code lineNumbers="true" %}

```json
{ 
   "agent_servers": { 
      "Claude (nexos.ai)": { 
         "command": "claude-agent-acp", 
         "args": [], 
         "env": { 
           "ANTHROPIC_BASE_URL": "https://api.nexos.ai", 
           "ANTHROPIC_AUTH_TOKEN": "{YOUR_API_KEY}", 
           "ANTHROPIC_API_KEY": "", 
           "ANTHROPIC_DEFAULT_OPUS_MODEL": "<opus-class-model-name-or-uuid>", 
           "ANTHROPIC_DEFAULT_SONNET_MODEL": "<sonnet-class-model-name-or-uuid>", 
           "ANTHROPIC_DEFAULT_HAIKU_MODEL": "<haiku-class-model-name-or-uuid>" 
         }  
     } 
   } 
}
```

{% endcode %}

**Configuration breakdown:**

| **Variable**                     | **Description**                                                             |
| -------------------------------- | --------------------------------------------------------------------------- |
| `ANTHROPIC_BASE_URL`             | nexos.ai gateway: `https://api.nexos.ai`. Do not add `/v1`.                 |
| `ANTHROPIC_AUTH_TOKEN`           | Your nexos.ai API key                                                       |
| `ANTHROPIC_API_KEY`              | **Must be an empty string** to prevent fallback to Anthropic authentication |
| `ANTHROPIC_DEFAULT_OPUS_MODEL`   | Model used for Opus-class tasks such as complex reasoning                   |
| `ANTHROPIC_DEFAULT_SONNET_MODEL` | Model used for Sonnet-class tasks such as general coding                    |
| `ANTHROPIC_DEFAULT_HAIKU_MODEL`  | Model used for Haiku-class tasks such as quick completions                  |

The model variables are optional. Use either the model name (for example, `Claude Sonnet 5`) or the UUID from your nexos.ai workspace. Claude Agent is optimized for Anthropic models and may not behave correctly with other providers.

{% hint style="info" %}
**Note:** If you have previously logged in to Claude Code with an Anthropic account, run `claude` in a terminal and type `/logout` once. A cached Anthropic login combined with `ANTHROPIC_AUTH_TOKEN` can cause model-not-found errors.
{% endhint %}

***

#### 2B. OpenCode via nexos.ai <a href="#id-2b.-opencode-via-nexos.ai" id="id-2b.-opencode-via-nexos.ai"></a>

OpenCode supports ACP natively and reads its nexos.ai provider from its own configuration, so it can use any model in your workspace.

1. Install and configure OpenCode with nexos.ai by following the [OpenCode integration guide](https://docs.nexos.ai/gateway-api/integrations/opencode) (steps 1 to 3). When you finish, `~/.config/opencode/opencode.json` contains the `nexosai` provider with `baseURL` set to `https://api.nexos.ai/v1`, and your API key is stored through `/connect`.
2. Make sure every model listed in `opencode.json` exists in your workspace. Use the exact names returned by `GET /v1/models` (for example, `Claude Haiku 4.5`). A model that is not available to your API key fails with `Model not found`.
3. Add OpenCode to `acp.json`:

{% code lineNumbers="true" %}

```json
{ 
    "agent_servers": { 
     "OpenCode (nexos.ai)": { 
      "command": "opencode", 
      "args": ["acp"], 
      "env": {} 
     } 
   } 
}
```

{% endcode %}

If Air cannot find the `opencode` command, use the full path from `which opencode` (for example, `/opt/homebrew/bin/opencode`).

The default model comes from the `model` field in `opencode.json` (for example, `nexosai/Claude Haiku 4.5`). You can switch to any other model from `opencode.json` in the session's model selector.

***

#### 2C. Codex via nexos.ai <a href="#id-2c.-codex-via-nexos.ai" id="id-2c.-codex-via-nexos.ai"></a>

**Step 1.** Install the Codex ACP adapter:

{% code lineNumbers="true" %}

```shellscript
npm install -g @agentclientprotocol/codex-acp
```

{% endcode %}

**Step 2.** Create or edit `~/.codex/config.toml`. Set `model_provider` at the top level. Air starts Codex for you, so you cannot pass the `--config model_provider="nexosai"` flag used in the [Codex CLI integration guide](https://docs.nexos.ai/gateway-api/integrations/codex-cli):

{% code lineNumbers="true" %}

```toml
model = "<your-model-uuid-or-name>"
model_provider = "nexosai"

[model_providers.nexosai]
name = "nexos.ai"
base_url = "https://api.nexos.ai/v1"
env_key = "NEXOS_AI_API_KEY"
# Use "responses" for models supporting the responses endpoint (e.g., OpenAI models)
# Use "chat" for models that do not support the responses endpoint (e.g., some Claude models)
wire_api = "responses"
```

{% endcode %}

**Step 3.** Add Codex to `acp.json` and pass the API key through `env`:

{% code lineNumbers="true" %}

```json
{ 
    "agent_servers": { 
     "Codex (nexos.ai)": { 
      "command": "codex-acp", 
      "args": [], 
      "env": { 
      "NEXOS_AI_API_KEY": "{YOUR_API_KEY}" 
     } 
    } 
  } 
}
```

{% endcode %}

For details on every `config.toml` option, see the [Codex CLI integration guide](https://docs.nexos.ai/gateway-api/integrations/codex-cli).

***

#### 3. Restart the IDE <a href="#id-3.-restart-the-ide" id="id-3.-restart-the-ide"></a>

After you create or change `acp.json`, quit the IDE completely and open it again. The **New Session** menu may not show new or changed agents until the IDE restarts.

***

#### 4. Start a session <a href="#id-4.-start-a-session" id="id-4.-start-a-session"></a>

1. Open the **Air** tool window.
2. Click the arrow next to **New Session** and choose the nexos.ai agent you added, for example **Claude (nexos.ai)**. Custom agents are marked with a list icon.
3. Pick a model and permission mode, then send your first prompt, for example: `What model are you?`

<figure><img src="https://4112003433-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDcOhapgXnoeDvgGQ8Jm4%2Fuploads%2FixMm1oxPz1gtVfxVQM0b%2Fimage%20(3).png?alt=media&amp;token=097e01d1-dff9-4dd9-92ff-d6f7a7f9c8a7" alt="" width="220"><figcaption></figcaption></figure>

{% hint style="warning" %}
**Important:** Do not confuse the nexos.ai entries with the built-in **Claude**, **Codex**, and **OpenCode** entries in the same menu. The built-in **Claude** agent opens Claude Code in a terminal and uses your own Anthropic login. It does not go through nexos.ai unless Claude Code itself is configured for nexos.ai.
{% endhint %}

You can choose the agent only when you create a new session. Once a session has started, you can change the model but not the agent.

<figure><img src="https://4112003433-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDcOhapgXnoeDvgGQ8Jm4%2Fuploads%2FD8AZRkahHV91YaIHHn2b%2Fimage%20(1).png?alt=media&amp;token=5676f309-bc5c-4665-b46c-106cd92bedfb" alt=""><figcaption></figcaption></figure>

***

### Advanced Configuration <a href="#advanced-configuration" id="advanced-configuration"></a>

#### Using several agents side by side <a href="#using-several-agents-side-by-side" id="using-several-agents-side-by-side"></a>

All agents can live in one `acp.json` file. Each one appears as its own entry in the **New Session** menu, so you can use a strong model for planning in one session and a faster one for iteration in another.

{% code lineNumbers="true" %}

```json
{
  "agent_servers": {
    "Claude (nexos.ai)": {
      "command": "claude-agent-acp",
      "args": [],
      "env": {
        "ANTHROPIC_BASE_URL": "https://api.nexos.ai",
        "ANTHROPIC_AUTH_TOKEN": "{YOUR_API_KEY}",
        "ANTHROPIC_API_KEY": ""
      }
    },
    "OpenCode (nexos.ai)": {
      "command": "opencode",
      "args": ["acp"]
    },
    "Codex (nexos.ai)": {
      "command": "codex-acp",
      "args": [],
      "env": {
        "NEXOS_AI_API_KEY": "{YOUR_API_KEY}"
      }
    }
  }
}

```

{% endcode %}

#### Finding available models <a href="#finding-available-models" id="finding-available-models"></a>

Fetch all models available to your API key:

{% code lineNumbers="true" %}

```shellscript
curl -X GET "https://api.nexos.ai/v1/models" \
  -H "Authorization: Bearer {YOUR_API_KEY}"
```

{% endcode %}

Use either `nexos_model_id` or `id` from the response in your agent configuration. For Codex, pick a model whose `endpoints` include `responses`, or set `wire_api = "chat"`. See [Gateway API Models](https://docs.nexos.ai/gateway-api/models) for details.

#### Using nexos.ai agents <a href="#using-nexos.ai-agents" id="using-nexos.ai-agents"></a>

To check which nexos.ai AI agents are available to you, call [Agent Management](https://docs.nexos.ai/gateway-api/agent-management).

***

### Troubleshooting <a href="#troubleshooting" id="troubleshooting"></a>

| Issue                                                     | Solution                                                                                                                                                                                       |
| --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| nexos.ai agents do not appear in the **New Session** menu | Restart the IDE. The menu may not pick up `acp.json` changes until a restart. Also check that the file is at `~/.jetbrains/acp.json`, is valid JSON, and has each agent under `agent_servers`. |
| `command not found` / agent fails to start                | The IDE may not see your shell `PATH`. Use the absolute path to the executable in `command` (run `which claude-agent-acp`, `which opencode`, or `which codex-acp`).                            |
| Authentication errors                                     | Make sure the API key is in the agent's `env` block in `acp.json`.                                                                                                                             |
| Session opens a terminal or shows your Anthropic plan     | You started the built-in **Claude** agent. Start a new session and choose **Claude (nexos.ai)** instead.                                                                                       |
| Claude Agent: model-not-found errors                      | Confirm `ANTHROPIC_API_KEY` is set to `""` and run `/logout` in Claude Code once to clear a cached Anthropic login.                                                                            |
| Claude Agent: connection errors                           | `ANTHROPIC_BASE_URL` must be `https://api.nexos.ai` without `/v1`.                                                                                                                             |
| OpenCode: `Model not found`                               | A model in `opencode.json` is not available to your API key. Replace it with a name returned by `GET /v1/models` and start a new session.                                                      |
| OpenCode / Codex: connection errors                       | The base URL must include `/v1`: `https://api.nexos.ai/v1`.                                                                                                                                    |
| Codex: `Model metadata for '<model>' not found`           | Expected warning. Codex has no built-in metadata for nexos.ai model names and falls back to defaults. Requests still work.                                                                     |
| Codex: API format errors                                  | Switch `wire_api` from `"responses"` to `"chat"` for models that do not support the Responses endpoint.                                                                                        |

***

### Verification <a href="#verification" id="verification"></a>

To verify your nexos.ai integration is working:

1. Start a new session in Air and choose your nexos.ai agent.
2. Open the model selector and confirm your configured models are listed.
3. Send a simple prompt, such as `What model are you?`, and confirm you get a response.
4. Open the nexos.ai platform and check that the request appears in your usage and observability data.

Your Air sessions now run through the nexos.ai gateway, with the load balancing, cost tracking, and observability that the platform provides.

### FAQ <a href="#faq" id="faq"></a>

#### Can I use the built-in Claude or Codex agents in Air with nexos.ai? <a href="#can-i-use-the-built-in-claude-or-codex-agents-in-air-with-nexos.ai" id="can-i-use-the-built-in-claude-or-codex-agents-in-air-with-nexos.ai"></a>

The built-in agents use your own vendor accounts. To route them through nexos.ai, add them as custom ACP agents through `acp.json` as described above.

#### Does this work for Air cloud sessions and Air Teams? <a href="#does-this-work-for-air-cloud-sessions-and-air-teams" id="does-this-work-for-air-cloud-sessions-and-air-teams"></a>

No. Custom ACP agents run locally in the IDE. Cloud sessions and Air Teams in the browser use only the providers enabled by your organization administrator in JetBrains Central Console.

#### Which other integrations are available in nexos.ai Gateway? <a href="#which-other-integrations-are-available-in-nexos.ai-gateway" id="which-other-integrations-are-available-in-nexos.ai-gateway"></a>

nexos.ai Gateway supports integrations with the following coding tools:

* [CrewAI](/gateway-api/integrations/crewai.md)
* [Codex CLI](https://docs.nexos.ai/gateway-api/integrations/codex-cli)
* [OpenCode](https://docs.nexos.ai/gateway-api/integrations/opencode)
* [Claude Code](https://docs.nexos.ai/gateway-api/integrations/claude-code)
* [Claude Cowork](https://docs.nexos.ai/gateway-api/integrations/claude-cowork)
* [Bubble](https://docs.nexos.ai/gateway-api/integrations/bubble)
* [GitLab CI](https://docs.nexos.ai/gateway-api/integrations/gitlab-ci)
* [OpenAI Agents SDK](https://docs.nexos.ai/gateway-api/integrations/openai-agents-sdk)
* [Vercel AI SDK](https://docs.nexos.ai/gateway-api/integrations/vercel-ai-sdk)
* [Streamlit](https://docs.nexos.ai/gateway-api/integrations/streamlit)
* [ProxyAI](https://docs.nexos.ai/gateway-api/integrations/proxyai)
* [Langfuse](https://docs.nexos.ai/gateway-api/integrations/langfuse)
* [LangGraph](https://docs.nexos.ai/gateway-api/integrations/langgraph)
* [LangChain](https://docs.nexos.ai/gateway-api/integrations/langchain)
* [Zoo Code](https://docs.nexos.ai/gateway-api/integrations/zoo-code)
* [Pi Agent](https://docs.nexos.ai/gateway-api/integrations/pi-agent)
* [n8n](https://docs.nexos.ai/gateway-api/integrations/n8n)


---

# 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.nexos.ai/gateway-api/integrations/jetbrains-air-integration.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.