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?

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

• 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 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.

• 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. You can use either nexos_model_id or id as the model.

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).

---

Integrating JetBrains Air with nexos.ai

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

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:

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

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

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.

---

2A. Claude Agent via nexos.ai

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:

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

Add the agent to acp.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>" 
         }  
     } 
   } 
}

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.

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.

---

2B. OpenCode via nexos.ai

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

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

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

Step 1. Install the Codex ACP adapter:

npm install -g @agentclientprotocol/codex-acp

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:

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"

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

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

For details on every config.toml option, see the Codex CLI integration guide.

---

3. Restart the IDE

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

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?

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.

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.

---

Advanced Configuration

Using several agents side by side

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.

{
  "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}"
      }
    }
  }
}

Finding available models

Fetch all models available to your API key:

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

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 for details.

Using nexos.ai agents

To check which nexos.ai AI agents are available to you, call Agent Management.

---

Troubleshooting

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

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

Can I use the built-in Claude or Codex agents in Air with nexos.ai?

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?

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?

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

• CrewAI

• Codex CLI

• OpenCode

• Claude Code

• Claude Cowork

• Bubble

• GitLab CI

• OpenAI Agents SDK

• Vercel AI SDK

• Streamlit

• ProxyAI

• Langfuse

• LangGraph

• LangChain

• Zoo Code

• Pi Agent

• n8n