# Droid

Source: https://docs.aicentos.com/en/clients/droid

Language: en

> Use aicentos in Factory Droid — register custom models through settings.json (BYOK)

Droid is a command-line coding agent from Factory with BYOK support: register a custom model in `~/.factory/settings.json` and point `baseUrl` at aicentos. Droid requires a model context window of at least 64k — keep that in mind when choosing a model.

## Prerequisites

First create a dedicated key for Droid on the console's "API Keys" page (naming it `droid` makes usage easier to track):

* Console: [https://aicentos.com](https://aicentos.com)
* Create a key: [https://aicentos.com/keys](https://aicentos.com/keys)
* Top up when the balance runs out: [https://aicentos.com/wallet](https://aicentos.com/wallet)

## Configuration to fill in

| Field       | Value                                              |
| ----------- | -------------------------------------------------- |
| Config file | `~/.factory/settings.json`                         |
| provider    | `generic-chat-completion-api`                      |
| baseUrl     | `https://aicentos.com/v1`                          |
| apiKey      | `${AICENTOS_API_KEY}`                              |
| Model       | A model name from the Model Gallery in the console |

## Setup steps

### 1. Set the API Key environment variable

```bash
export AICENTOS_API_KEY="sk-your-API-Key"
```

Add it to `~/.zshrc` or `~/.bashrc` to persist it.

### 2. Edit settings.json

Edit `~/.factory/settings.json` and add a `customModels` array:

```json
{
  "customModels": [
    {
      "model": "gpt-4o",
      "displayName": "GPT-4o (aicentos)",
      "baseUrl": "https://aicentos.com/v1",
      "apiKey": "${AICENTOS_API_KEY}",
      "provider": "generic-chat-completion-api",
      "maxOutputTokens": 8192
    }
  ]
}
```

Key fields:

| Field         | Description                                                                             |
| ------------- | --------------------------------------------------------------------------------------- |
| `model`       | The model ID actually sent to the endpoint; must match the Model Gallery in the console |
| `displayName` | Display name in the model picker; customizable                                          |
| `baseUrl`     | API address; `/v1` recommended                                                          |
| `apiKey`      | Supports `${VAR_NAME}` expansion                                                        |
| `provider`    | `anthropic` / `openai` / `generic-chat-completion-api`                                  |

### 3. Select the model

After starting `droid`, run `/model` and pick the model you just registered. **After changing the configuration, you need to restart `droid` in a new terminal** for the file to be re-read.

## Test

After selecting the model, send a simple request:

```
Answer in one sentence: what is 1+1?
```

A normal response means the integration works.

## Notes

* **Set `provider` to `generic-chat-completion-api`**. It uses the OpenAI Chat Completions protocol and is the right choice for most BYOK scenarios. `openai` uses the Responses API, and under some gateways that value ignores `base_url` and points straight at `api.openai.com`; `anthropic` uses `/v1/messages`.
* **Clear environment variables first**. If `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_BASE_URL` or `ANTHROPIC_API_KEY` is exported in your shell, they override the configuration file and cause requests to bypass your configured gateway. It is advisable to `unset` these variables before connecting.
* Droid reads both `~/.factory/settings.json` and the legacy `~/.factory/config.json`, with the former taking precedence. The legacy field names are snake\_case `custom_models` / `model_display_name` / `base_url` / `api_key`, and it does **not** support `${VAR_NAME}` expansion — stick to `settings.json`.
* The model context window must be at least 64k; overly small local models may behave oddly.
* Factory only benchmarks the official Anthropic / OpenAI endpoints, and compatibility of custom models is not guaranteed; subagents are known to occasionally fall back to the official Anthropic endpoint.
* Troubleshooting order: can you see the model in `/model` → are the environment variables being overridden by ANTHROPIC\_\* → does baseUrl include `/v1` → is the balance sufficient.

## Related links

* Official BYOK documentation: [https://docs.factory.ai/model-independence/byok](https://docs.factory.ai/model-independence/byok)