> 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/zoo-code.md).
# Zoo Code Integration
Configure Zoo Code with the nexos.ai API Gateway for multi-provider LLM access in VS Code. A guide for API keys, provider config, and model selection.
Connect **Zoo Code** to the **nexos.ai API Gateway** to use the models available in your nexos.ai platform directly inside Visual Studio Code.
Zoo Code supports any OpenAI-compatible endpoint through its **OpenAI Compatible** provider. By pointing that provider at the Gateway, every request Zoo Code makes (chat, tool calls, optional codebase indexing) is routed through nexos.ai using your nexos.ai API key, with the usual load balancing, cost tracking and observability.
{% hint style="info" %}
**Coming from** [**Roo Code**](/gateway-api/integrations/roo-code.md)**?** Roo Code was discontinued on May 15, 2026 and its extension is no longer maintained. Zoo Code is the community continuation of the same codebase, so the nexos.ai setup is almost identical. See [Migrating from Roo Code](#migrating-from-roo-code) below.
{% endhint %}
## What is Zoo Code?
Zoo Code is a free, open-source (Apache 2.0) AI coding agent for Visual Studio Code, developed by former Roo Code contributors after the Roo team wound down the extension. It gives you "a whole dev team of AI agents in your editor": it can read and edit files, run terminal commands, browse the web and use MCP servers to complete multi-step tasks.
**Key features:**
* **Modes** – built-in Code, Architect, Ask, Debug and Orchestrator modes, plus custom modes, keep the model focused on a specific kind of work.
* **Provider agnostic** – works with dozens of providers and any OpenAI-compatible endpoint, including the nexos.ai Gateway.
* **Native tool calling** – tools are sent using the OpenAI function-calling schema and tool arguments stream incrementally.
* **API configuration profiles** – several provider/model profiles that can be switched from the chat window or pinned to specific modes.
* **MCP support** – connect Model Context Protocol servers to extend the agent with external tools.
* **Codebase indexing** – semantic search over your project using an embedding model and a Qdrant vector store.
* **Auto-approve** – gradually allow Zoo Code to perform actions without confirmation as you gain confidence.
Useful links: [Zoo Code documentation](https://docs.zoocode.dev/), [GitHub repository](https://github.com/Zoo-Code-Org/Zoo-Code), [VS Code Marketplace listing](https://marketplace.visualstudio.com/items?itemName=ZooCodeOrganization.zoo-code).
***
## Prerequisites
* A **nexos.ai API key** (user key or team key). See [How to generate a nexos.ai API key](https://docs.nexos.ai/gateway-api/api-keys).
* **Visual Studio Code 1.84.0 or later** (Cursor, VSCodium and Windsurf also work, see installation below).
* At least one model in your nexos.ai workspace that supports the **Chat Completions** endpoint **and native tool calling**. Zoo Code has no XML fallback: a model without function calling cannot be used at all.
{% hint style="warning" icon="memo" %}
Gateway base URL used throughout this guide: `https://api.nexos.ai/v1`. The `/v1` suffix is required.
{% endhint %}
***
## How to connect Zoo Code with nexos.ai
{% stepper %}
{% step %}
### Generate your nexos.ai API key
In your nexos.ai workspace open the **API Keys** tab, select **Generate API Key**, enter a name for the key and click **Generate**. Copy the key immediately: it is shown only once and cannot be retrieved after the dialog is closed.
The key inherits the settings configured by your organization owner (enabled models, fallbacks, limits). API usage requires purchased API credits.
{% hint style="warning" icon="exclamation" %}
Store your API key safely and never share it. Zoo Code keeps the key in VS Code secret storage, but exported provider profiles contain it in plain text.
{% endhint %}
{% endstep %}
{% step %}
### Install the Zoo Code extension
You can install Zoo Code in several ways:
* **VS Code Extensions tab (recommended)** – open the Extensions view (`Ctrl+Shift+X` / `Cmd+Shift+X`), search for **"Zoo Code"**, select the extension published by **ZooCodeOrg** and click **Install**. This works in VS Code and Cursor.
* **Command line** – run the following in a terminal:
{% code lineNumbers="true" %}
```
code --install-extension ZooCodeOrganization.zoo-code
```
{% endcode %}
* **Marketplace website** –
* **Open VSX** (VSCodium, Windsurf and other editors without Marketplace access) – search for "Zoo Code" in the editor's Extensions view, or use .
* **Manual VSIX** – download the `.vsix` from [GitHub Releases](https://github.com/Zoo-Code-Org/Zoo-Code/releases) and use **Extensions → ... → Install from VSIX...**.
{% hint style="warning" %}
You may be asked whether you trust the publisher of the extension. Make sure you are familiar with the risks of installing third-party extensions.
{% endhint %}
After installation a Zoo Code icon appears in the VS Code Activity Bar.
{% endstep %}
{% step %}
### Configure the OpenAI Compatible provider
Open the Zoo Code panel by clicking the Zoo Code icon in the Activity Bar. On first launch a welcome screen asks you to choose your LLM provider; later you can reach the same form through the **gear icon → Providers** in the Zoo Code panel.
Fill in the provider settings as follows:
| **Setting** | **Value** |
| ---------------- | --------------------------------------------------------------------------------------------------- |
| **API Provider** | `OpenAI Compatible` |
| **Base URL** | `https://api.nexos.ai/v1` |
| **API Key** | The nexos.ai key generated in step 1 |
| **Model** | The ID of a model available in your workspace, exactly as returned by `GET /v1/models` (see step 4) |
| **Use Azure** | Leave unchecked |
| **Extra Body** | Leave empty (optional provider-specific JSON fields; do not put secrets here) |
Then confirm the form with the button at the bottom of the screen (**Let's go!** on the welcome screen, **Save** in Settings).
Optionally expand **Model Configuration** to tell Zoo Code about the model you selected. The values can be copied from the `/v1/models` response:
| **Zoo Code field** | **Source in `/v1/models`** | **Why it matters** |
| -------------------------- | -------------------------- | ------------------------------------------------------------------------- |
| Context Window | `context_length` | Zoo Code uses it to condense the conversation before the limit is reached |
| Max Output Tokens | `max_tokens` | Upper bound for a single response |
| Image Support | model capabilities | Enables sending screenshots/images to the model |
| Input Price / Output Price | `pricing` | Only used for the cost estimate shown in the task header |
| {% endstep %} | | |
{% step %}
### Choose a model
Once the Base URL and API key are filled in, Zoo Code tries to load the model list from the provider's `/models` endpoint and offers it in the **Model** field. If the list does not load, or you want to double-check a model's capabilities, query the nexos.ai Models endpoint directly:
{% code lineNumbers="true" %}
```javascript
curl "https://api.nexos.ai/v1/models" \
-H "Authorization: Bearer $NEXOS_API_KEY"
```
{% endcode %}
Each entry in `data` contains the `id` to paste into the **Model** field, together with `context_length`, `max_tokens`, `pricing` and the supported `endpoints`. Matching of the model ID is case-insensitive but otherwise exact. You can also use the internal `nexos_model_id` value instead of the display name.
When picking a model for Zoo Code make sure that:
* its `endpoints` include `chat_completion` (Zoo Code talks to the OpenAI Compatible provider through the Chat Completions API), and
* it supports **native tool calling / function calling**. Frontier coding models such as the current Claude Sonnet/Opus, GPT-5 family or Gemini Pro models do; small or older models often do not.
{% hint style="warning" %}
Treat `GET /v1/models` as the source of truth for the models your key can use. Model availability is controlled by your workspace administrator. Learn more at .
{% endhint %}
{% endstep %}
{% step %}
### Send your first message
Open a project folder, pick **Code** mode in the Zoo Code chat window and send a simple request, for example *"Explain what this repository does"*. The response should stream in and any file reads should appear as tool calls in the task timeline. The request is visible in your nexos.ai usage dashboard, which confirms that traffic is flowing through the Gateway.
Zoo Code now routes all requests through the **nexos.ai API Gateway**, giving you access to multiple LLM providers through a single endpoint with centralized cost tracking, limits and observability.
{% endstep %}
{% endstepper %}
***
## Advanced configuration
### API configuration profiles
You will usually want more than one nexos.ai model, for example a strong model for **Code** and **Architect** modes and a cheaper, faster model for **Ask** or **Debug**. Zoo Code handles this with **API configuration profiles**:
1. Open **Settings (gear icon) → Providers** and click **+** next to the profile dropdown.
2. Give the profile a name such as `nexos – Claude Sonnet` or `nexos – GPT small`.
3. Select **OpenAI Compatible**, enter the same Base URL and API key, and a different **Model** ID.
4. Repeat for each model you want to use.
Switch between profiles from the dropdown in the Settings panel or from the **API Configuration** dropdown directly in the chat window. In the **Prompts** tab you can assign a default profile to each mode; Zoo Code remembers the last profile used per mode. Hover over a profile to **pin** it to the top of the list.
### Codebase indexing with nexos.ai embeddings (optional)
Advanced feature for power users: semantic search over your project. It requires an embedding model and a self-hosted or cloud **Qdrant** vector database. Skip this unless you need it.
Show setup steps
The embedding requests are routed through the nexos.ai Gateway, which exposes an OpenAI-compatible [Embeddings endpoint](https://docs.nexos.ai/gateway-api/embeddings).
1. Start a Qdrant instance, either [Qdrant Cloud](https://cloud.qdrant.io/) (free tier) or locally:
{% code lineNumbers="true" %}
```
docker run -p 6333:6333 -v qdrant_storage:/qdrant/storage qdrant/qdrant
```
{% endcode %}
2. In Zoo Code open **Settings → Codebase Indexing** and enable it.
3. Set **Embedder Provider** to **OpenAI Compatible**.
4. Set **Base URL** to `https://api.nexos.ai/v1` and **API Key** to your nexos.ai key.
5. Set **Model** to the ID of an embedding model available in your workspace (an entry from `/v1/models` whose `endpoints` include `embedding`) and enter its **Embedding Dimension**.
6. Set **Qdrant URL** (for the local container: `http://localhost:6333`) and the Qdrant API key if your instance requires one.
7. Click **Save** and **Start Indexing**.
{% hint style="warning" %}
Changing the embedding model or dimension later requires a full re-index. Indexing a large repository sends one embedding request per code chunk, so expect a burst of embedding traffic in your nexos.ai usage.
{% endhint %}
### MCP servers
MCP servers are configured independently of the model provider (Zoo Code panel → **MCP Servers**). They work unchanged with the nexos.ai Gateway, as long as the selected model supports tool calling.
***
## Migrating from Roo Code
If you followed the previous [Roo Code integration guide](https://docs.nexos.ai/gateway-api/integrations/roo-code), you can carry your configuration over instead of setting it up again:
1. In **Roo Code**, open Settings and choose **Export**. Save the settings file somewhere safe.
2. Install Zoo Code (step 2 above).
3. In **Zoo Code**, open Settings and click **Import Settings**, then select the exported file. Zoo Code merges the imported provider profiles (including your nexos.ai *OpenAI Compatible* profile), modes and other settings into its own configuration.
4. Verify the imported profile still points at `https://api.nexos.ai/v1` and that the model ID is still available via `/v1/models`.
5. Uninstall the archived Roo Code extension (`RooVeterinaryInc.roo-cline`) to avoid two agents competing for the same keyboard shortcuts.
{% hint style="warning" %}
The exported settings file contains your API keys in plain text. Delete it after importing, or store it in a secure location.
{% endhint %}
Zoo Code project files (`.roo/` rules, custom modes, `.roomodes`) are still recognised, so per-repository configuration usually needs no changes. See the official [Roo to Zoo migration guide](https://docs.zoocode.dev/roo-to-zoo-migration) for details.
***
## Troubleshooting
* **"Model Not Found"** – the **Model** field must contain a model ID exactly as returned by `GET /v1/models` for your key (case does not matter). If the model is missing from the list, ask your workspace administrator to enable it.
* **Connection errors or 404 on every request** – check that the Base URL is exactly `https://api.nexos.ai/v1`, including `/v1`, and that **Use Azure** is unchecked.
* **The agent answers in plain text but never edits files, or errors mention** `tools` – the selected model does not support native tool calling. Switch to a model that does (see step 4).
For detailed logs open **View → Output** in VS Code and select **Zoo Code**. Community help: [Zoo Code Discord](https://discord.gg/SfHYG44NUA), [GitHub Issues](https://github.com/Zoo-Code-Org/Zoo-Code/issues).
---
# 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/zoo-code.md?ask=&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.