# Craft Agent

Source: https://docs.aicentos.com/en/clients/craft-agent

Language: en

> Connect aicentos in Craft Agent — a custom OpenAI-compatible connection that works for both the desktop app and craft-cli

Craft Agent's LLM connections support a `Custom` type, officially described as "any URL, any OpenAI-compatible or Anthropic-compatible endpoint". Point the Base URL at aicentos and both the desktop app and `craft-cli` can use it.

## Prerequisites

First create a dedicated key for Craft Agent in the console (naming it `craft-agent` is recommended) so usage can be tracked per key.

* Console: [https://aicentos.com](https://aicentos.com)
* Create a key: [https://aicentos.com/keys](https://aicentos.com/keys)
* Top up wallet: [https://aicentos.com/wallet](https://aicentos.com/wallet)

Install the desktop app:

```bash
curl -fsSL https://thecraftagents.com/install-app.sh | bash
```

Headless server and pure command-line usage are supported as well.

## Configuration to fill in

| Field           | Value                                                                                         |
| --------------- | --------------------------------------------------------------------------------------------- |
| Connection type | Custom                                                                                        |
| Protocol        | `openai-completions`, or `anthropic-messages`                                                 |
| Base URL        | `https://aicentos.com/v1` (OpenAI-compatible) / `https://aicentos.com` (Anthropic-compatible) |
| API Key         | The key created in the console                                                                |
| Model           | A model name from the Model Gallery in the console                                            |

## Setup steps

Desktop app: open the LLM connections in settings, add one, choose Custom as the type, and fill it in per the table above.

The command-line equivalent:

```bash
export AICENTOS_API_KEY="sk-your-API-Key"
craft-cli run --provider openai \
  --base-url https://aicentos.com/v1 \
  --api-key "$AICENTOS_API_KEY" \
  --model your-model-name \
  "Hello"
```

You can also edit the config file `~/.craft-agent/config.json` directly:

```json
{
  "llmConnections": [
    {
      "providerType": "pi_compat",
      "baseUrl": "https://aicentos.com/v1",
      "customEndpoint": { "api": "openai-completions" },
      "models": [{ "id": "your-model-name" }],
      "defaultModel": "your-model-name"
    }
  ]
}
```

The key is not written into the plaintext config; it is stored in `credentials.enc` in the same directory. Fill it in once through the UI and do not edit this file by hand.

## Test

```bash
craft-cli run --provider openai \
  --base-url https://aicentos.com/v1 \
  --api-key "$AICENTOS_API_KEY" \
  --model your-model-name \
  "Introduce yourself in one sentence"
```

A normal response means it works. Then go back to the console and check usage to confirm the requests are recorded against this key.

## Notes

* Keep `providerType` as `pi_compat`; that is its identifier for a custom endpoint. Changing it to the name of a built-in provider routes to the official models.
* `models` must be filled in by hand; it does not fetch the model list automatically. Names must match the Model Gallery in the console exactly (see [Supported models](https://docs.aicentos.com/en/billing/models-list)).
* When using the Anthropic-compatible endpoint, the Base URL is `https://aicentos.com` without `/v1`, and `--provider` becomes `anthropic`.
* Menu positions in the desktop app change between versions; when you cannot find something, go by the `config.json` form.

## Related links

* [Craft Agents docs](https://thecraftagents.com/docs)
* [craft-agents repository](https://github.com/craft-ai-agents/craft-agents-oss)