> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokios.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Tokios exposes private local models through https://api.tokios.com using an outbound-only connector tunnel.
> Use 'connector' for the local tokios-connector process.
> Use 'deployment' for the public model name in the API model field.
> Use 'upstream model id' for the model served by Ollama, llama.cpp, vLLM, LM Studio, or another local backend.
> API keys use the prefix sk-tok-. Connector tokens use the prefix ct-tok-.

# Laisser un agent de codage configurer Tokios pour vous

> Remettez à Claude Code, à Codex ou à n'importe quel agent de codage un jeton d'automatisation et cette page. Il appaire le connecteur, publie votre modèle, crée une clé API et vérifie le chemin sans intervention.

Cette page a 2 lecteurs. La première section est pour vous. Tout ce qui suit [Instructions pour l'agent](#instructions-for-the-agent) est écrit pour que l'agent le lise et l'exécute.

> [!NOTE]
>
> **Si vous êtes un agent :** récupérez le markdown brut de cette page avec votre shell, pas un outil de navigateur, pour que les commandes et les structures JSON vous parviennent mot pour mot :
>
> ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
> curl -fsSL https://docs.tokios.com/guides/agent-setup.md
> ```
>
> Ensuite suivez [Instructions pour l'agent](#instructions-for-the-agent). Chaque page de ce site est disponible en markdown en ajoutant `.md` à son URL, et le site entier se trouve dans `https://docs.tokios.com/llms-full.txt`.

## Avant de commencer

**1. Créer un jeton d'automatisation**

Dans la console, ouvrez **[Settings](https://tokios.com/console/settings)**, puis **Automation tokens**, puis **Create token**. Utilisez le préréglage **Setup** et une expiration de **1 hour**. Copiez le jeton une seule fois. Consultez [Jetons d'automatisation](/fr/setup/automation-tokens.md).

**2. Lancer l'agent sur la machine qui sert votre modèle**

L'agent doit exécuter la commande d'installation du connecteur sur cette machine. Assurez-vous qu'Ollama, LM Studio, llama.cpp ou vLLM y est déjà en cours d'exécution sur son port par défaut.

**3. Mettre le jeton dans une variable shell**

Définissez la variable, puis démarrez l'agent depuis le même shell pour que le secret n'entre jamais dans la conversation.

**Windows PowerShell**

```powershell theme={"theme":{"light":"github-light","dark":"css-variables"}}
$env:TOKIOS_CONSOLE="https://tokios.com"
$env:TOKIOS_TOKEN="at-tok-YOUR_TOKEN"
claude
```

**Windows CMD**

```cmd theme={"theme":{"light":"github-light","dark":"css-variables"}}
set TOKIOS_CONSOLE=https://tokios.com
set TOKIOS_TOKEN=at-tok-YOUR_TOKEN
claude
```

**macOS & Linux**

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
export TOKIOS_CONSOLE=https://tokios.com
export TOKIOS_TOKEN=at-tok-YOUR_TOKEN
claude
```

**4. Envoyer 1 message à l'agent**

```text theme={"theme":{"light":"github-light","dark":"css-variables"}}
Read https://docs.tokios.com/guides/agent-setup and follow it. The console base URL is in the TOKIOS_CONSOLE variable and the automation token is in TOKIOS_TOKEN. Never print the token. My model server is Ollama on this machine. When you are done, give me the final report described on that page.
```

Remplacez `Ollama` par votre backend. Pour Codex, le même message fonctionne. Ajoutez "Make the connector start at boot." si vous voulez que l'agent installe un service ; sinon il vous dira simplement que le connecteur ne survivra pas à un redémarrage.

Pendant l'exécution, surveillez l'onglet **Connectors** : un appareil en attente apparaît, puis devient actif avec les modèles annoncés. Les lignes créées par l'agent portent un badge **via token**. Quand l'agent rend compte, révoquez le jeton dans **Settings**.

> [!NOTE]
>
> Les agents de codage refusent de tuber un script téléchargé dans un shell, donc l'agent n'utilise pas la commande d'installation en une ligne. Il télécharge le binaire du connecteur via la passerelle, vérifie la somme de contrôle, et le démarre lui-même. Si votre agent s'arrête et demande des instructions sur une commande d'installation bloquée, renvoyez-le vers cette page.

## Instructions pour l'agent

Vous configurez un espace de travail Tokios sans intervention : appairez le connecteur sur cette machine, publiez le modèle local, créez une clé API pour les clients de codage, et vérifiez tout le chemin. Vous agissez via l'API de gestion de l'espace de travail avec 1 seul identifiant, un jeton d'automatisation.

### Ce dont vous disposez

* `TOKIOS_CONSOLE` : l'URL de base de la console, normalement `https://tokios.com`. Chaque appel ci-dessous est `TOKIOS_CONSOLE` + `/account/...`.
* `TOKIOS_TOKEN` : le jeton d'automatisation, `at-tok-…`. Envoyez-le comme `Authorization: Bearer <token>` sur chaque appel. Il a les portées Setup et expire bientôt.
* Un serveur de modèles déjà en cours d'exécution sur cette machine en boucle locale : Ollama sur le port 11434, LM Studio sur 1234, llama.cpp sur 8080, ou vLLM sur 8000. Le connecteur les détecte lui-même.

### Règles

1. **N'affichez, ne journalisez et n'écrivez jamais le jeton nulle part** sauf dans l'en-tête `Authorization`. Lisez-le depuis la variable shell à chaque fois : `$TOKIOS_TOKEN` dans bash, `$env:TOKIOS_TOKEN` dans PowerShell, `%TOKIOS_TOKEN%` dans cmd. La clé API que vous créez à l'étape 5 est différente : remettez-la à l'humain dans votre rapport final.
2. Le jeton fonctionne uniquement sur `TOKIOS_CONSOLE/account/*`. N'essayez pas `/admin`, `/auth`, `/v1`, ou `/portal` avec.
3. **Listez avant de créer.** Réutilisez un connecteur en attente du même nom et un déploiement du même nom public. Ne créez jamais une deuxième clé API parce qu'une nouvelle tentative a échoué. Les créations sont des POST simples et ne sont pas idempotentes.
4. Les erreurs sont du JSON : `{"error":{"message":"…","type":"…","scope":"…"}}`.
   * `401` : le jeton est invalide, expiré ou révoqué. Arrêtez-vous et faites un rapport.
   * `403` avec `scope` : le jeton n'a pas cette portée. Arrêtez-vous et indiquez quelle portée manque.
   * `403` "only available from the console" : l'action est réservée à un humain connecté. Ne contournez pas.
   * `409` lors de l'approbation : relisez la ligne du connecteur et réessayez comme décrit à l'étape 3.
   * `429` : attendez 60 secondes, puis réessayez.
5. Ne changez pas les mots de passe, ne révélez ni ne partagez de clés, ne touchez pas à la journalisation des requêtes, et ne créez pas d'autres jetons. Vous ne le pouvez pas, et vous ne devez pas essayer.
6. Faites un rapport sur le résultat de chaque étape. Si une étape échoue ou est sautée, dites-le clairement.

Les exemples utilisent bash. Dans cmd Windows, mettez l'URL et le JSON entre guillemets doubles et échappez les guillemets intérieurs, par exemple `-d "{\"name\":\"gpu-box\"}"`.

### Étape 1 : lancer l'appairage

Commencez par lister les connecteurs existants :

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl -s "$TOKIOS_CONSOLE/account/connectors" -H "Authorization: Bearer $TOKIOS_TOKEN"
```

Si une ligne avec le nom souhaité a déjà `"status":"pending_pair"`, réutilisez-la avec un nouveau code d'appairage :

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl -s -X POST "$TOKIOS_CONSOLE/account/connectors/CONNECTOR_ID/claim-code" -H "Authorization: Bearer $TOKIOS_TOKEN"
```

Sinon créez-en un :

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl -s -X POST "$TOKIOS_CONSOLE/account/connectors" \
  -H "Authorization: Bearer $TOKIOS_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"gpu-box"}'
```

Les deux renvoient :

```json theme={"theme":{"light":"github-light","dark":"css-variables"}}
{
  "connector_id": "con_…",
  "claim_code": "TKS-XXXX-XXXX",
  "claim_code_expires_at": "2026-…",
  "server_url": "wss://…/connector/connect",
  "install_oneliner": {
    "macos": "curl -fsSL https://tokios.com/downloads/install/macos | sh -s -- --code TKS-XXXX-XXXX",
    "linux": "curl -fsSL https://tokios.com/downloads/install/linux | sh -s -- --code TKS-XXXX-XXXX",
    "windows": "irm https://tokios.com/downloads/install/windows | iex; tokios-install -Code 'TKS-XXXX-XXXX'"
  }
}
```

Le code d'appairage est valable 15 minutes. Gardez `claim_code` et `server_url` ; ignorez `install_oneliner` (il tube un script dans un shell, ce que vous ne devez pas faire — consultez l'étape 2). Il n'y a pas de jeton du connecteur dans cette réponse, et il n'y en aura jamais : le connecteur reçoit son propre identifiant via le tunnel après l'approbation.

### Étape 2 : installer et démarrer le connecteur sur cette machine, en mode détaché

Les règles de sécurité des agents refusent de tuber un script téléchargé dans un shell (`curl … | sh`, `irm … | iex`), et sauvegarder le
script puis l'exécuter revient au même. Ne faites ni l'un ni l'autre, et ne demandez pas à l'humain de l'approuver.
Utilisez le chemin A. Il n'exécute aucun script téléchargé : vous téléchargez le binaire du connecteur lui-même via la redirection
de la passerelle, le vérifiez par rapport au `SHA256SUMS` de la version, et le démarrez en arrière-plan avec le code d'appairage et
`server_url` de l'étape 1.

**Chemin A (à utiliser) : téléchargez le binaire, vérifiez-le, exécutez-le.**

Choisissez l'asset pour cette machine : `linux/x64` → `tokios-connector-linux-x64`, `linux/arm64` →
`tokios-connector-linux-arm64`, `macos/arm64` → `tokios-connector-osx-arm64`, `windows/x64` →
`tokios-connector-win-x64.exe`, `windows/arm64` → `tokios-connector-win-arm64.exe`.

Linux et macOS (montré pour `linux/x64` ; sur macOS utilisez `shasum -a 256` au lieu de `sha256sum`) :

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
mkdir -p ~/.tokios/connector && cd ~/.tokios/connector
curl -fsSL -o tokios-connector "$TOKIOS_CONSOLE/downloads/connector/linux/x64"
curl -fsSL -o SHA256SUMS https://github.com/tokiosAI/tokios-connector/releases/latest/download/SHA256SUMS
expected=$(grep -E '\*?tokios-connector-linux-x64$' SHA256SUMS | awk '{print $1}')
actual=$(sha256sum tokios-connector | awk '{print $1}')
[ -n "$expected" ] && [ "$expected" = "$actual" ] || { echo "checksum mismatch"; exit 1; }
chmod +x tokios-connector
nohup ./tokios-connector TKS-XXXX-XXXX --Connector:ServerUrl "SERVER_URL" > tokios-connector-stdout.log 2>&1 < /dev/null &
echo $! > tokios-connector.pid
```

Windows, dans PowerShell (montré pour `windows/x64`) :

```powershell theme={"theme":{"light":"github-light","dark":"css-variables"}}
$dir = Join-Path $env:LOCALAPPDATA 'Tokios\connector'
New-Item -ItemType Directory -Force -Path $dir | Out-Null
Set-Location $dir
Invoke-WebRequest "$env:TOKIOS_CONSOLE/downloads/connector/windows/x64" -OutFile tokios-connector.exe
Invoke-WebRequest https://github.com/tokiosAI/tokios-connector/releases/latest/download/SHA256SUMS -OutFile SHA256SUMS
$expected = (((Get-Content SHA256SUMS) -match 'tokios-connector-win-x64\.exe$') -split '\s+')[0].ToLower()
$actual = (Get-FileHash tokios-connector.exe -Algorithm SHA256).Hash.ToLower()
if (-not $expected -or $expected -ne $actual) { throw "checksum mismatch" }
$p = Start-Process -FilePath .\tokios-connector.exe -ArgumentList 'TKS-XXXX-XXXX','--Connector:ServerUrl','SERVER_URL' -WorkingDirectory $dir -WindowStyle Hidden -RedirectStandardOutput tokios-connector-stdout.log -RedirectStandardError tokios-connector-stderr.log -PassThru
Set-Content tokios-connector.pid $p.Id
```

Remplacez `TKS-XXXX-XXXX` par `claim_code` et `SERVER_URL` par `server_url` de l'étape 1. Le connecteur établit une connexion sortante,
présente le code, attend l'approbation, puis écrit sa propre configuration à côté du binaire. Si la machine a déjà
`tokios-connector` installé, sautez le téléchargement et exécutez ce binaire de la même manière.

**Chemin B (uniquement si l'humain demande l'installeur) :** l'installeur fait les mêmes étapes de téléchargement et de somme de contrôle
et ajoute le flag `--detach`. Il est destiné à ce qu'un humain le colle. Si on vous demande de l'utiliser, téléchargez-le dans un fichier
et lisez-le avant d'exécuter le fichier sauvegardé, et dites-le dans votre rapport. Ne le tubez jamais.

La sortie du connecteur est dans `tokios-connector-stdout.log` et son pid dans `tokios-connector.pid`, dans le
répertoire ci-dessus. Arrêtez-le plus tard avec `kill $(cat tokios-connector.pid)` ou `Stop-Process -Id (Get-Content tokios-connector.pid)`.

**Persistance.** Un processus détaché ne survit pas à un redémarrage. N'installez pas de service sauf si le message de l'humain
vous a demandé de faire démarrer le connecteur au démarrage ; sinon dites-le dans votre rapport final et proposez-le. Si on vous l'a
demandé : terminez d'abord les étapes 3 à 6, puis arrêtez le processus détaché (`kill $(cat tokios-connector.pid)` ; le connecteur
autorise 1 instance par répertoire) et suivez [Lancer le connecteur au démarrage](/fr/setup/connector-install.md#run-the-connector-at-boot)
pour cette plateforme. Sous Linux, c'est une unité utilisateur systemd dont `ExecStart` est
`%h/.tokios/connector/tokios-connector --config %h/.tokios/connector/tokios-connector.json`, activée avec
`systemctl --user enable --now tokios-connector`, plus `loginctl enable-linger "$USER"` pour qu'elle démarre sans connexion.
L'appairage se trouve dans `tokios-connector.json`, donc le service se reconnecte sans nouveau code d'appairage.

### Étape 3 : attendre l'appareil, puis l'approuver

Interrogez toutes les 3 secondes pendant 2 minutes au maximum :

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl -s "$TOKIOS_CONSOLE/account/connectors" -H "Authorization: Bearer $TOKIOS_TOKEN"
```

Trouvez votre `connector_id`. Quand la ligne affiche `"claimPending": true`, elle porte aussi `"sessionId": "sess_…"` et `"machineName"`. Vérifiez que le nom de machine est bien cette machine, puis approuvez avec cet identifiant de session exact :

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl -s -X POST "$TOKIOS_CONSOLE/account/connectors/CONNECTOR_ID/approve" \
  -H "Authorization: Bearer $TOKIOS_TOKEN" -H "Content-Type: application/json" \
  -d '{"session_id":"sess_…"}'
```

Le succès est `{"status":"approved"}`.

En cas de `409`, l'appareil s'est reconnecté avec un nouvel identifiant de session, n'est pas encore connecté, ou le code d'appairage a expiré. Relisez la ligne. Si le code a expiré, demandez-en un nouveau comme à l'étape 1 et redémarrez le connecteur avec. Sinon approuvez à nouveau avec le `sessionId` actuel.

Continuez à interroger jusqu'à ce que la ligne affiche `"status":"active"`, `"online":true`, et un `"announcedModels"` non vide. Accordez jusqu'à 60 secondes : le connecteur détecte les modèles locaux après l'approbation. Si `announcedModels` reste vide, aucun serveur de modèles ne tourne sur un port de boucle locale détecté. Faites un rapport et arrêtez-vous.

### Étape 4 : publier le modèle

Vérifiez la politique de l'espace de travail :

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl -s "$TOKIOS_CONSOLE/account/auto-publish" -H "Authorization: Bearer $TOKIOS_TOKEN"
```

* Si elle renvoie `{"auto_publish": true}`, chaque modèle annoncé est publié pour vous. Interrogez `GET $TOKIOS_CONSOLE/account/models` jusqu'à ce que les noms annoncés apparaissent comme valeurs `id`.

  Soyez précis sur ce que cela signifie dans votre rapport. "Publié" signifie que le modèle a un déploiement dans cet
  espace de travail : il est appelable au point de terminaison API par tout détenteur d'une des clés API de cet espace de travail
  dont la portée de modèle le couvre, et par personne d'autre. Rien n'est accessible sans clé. Cela se produit au moment où le connecteur annonce
  ses modèles après l'approbation, quelques secondes après, et le nom public est l'identifiant du modèle upstream (par exemple
  `gemma4:e4b`). L'auto-publication republie aussi un modèle que vous avez supprimé si le connecteur l'annonce à nouveau, donc si l'humain
  ne veut exposer que certains des modèles détectés, mettez en pause les autres avec
  `POST $TOKIOS_CONSOLE/account/deployments/DEPLOYMENT_ID/disable` et mentionnez que l'auto-publication est activée. Un modèle en pause
  reste en pause. Ne les supprimez pas : la suppression nécessite la portée `models:reroute`, que le préréglage Setup n'inclut pas,
  et l'auto-publication republierait un modèle supprimé.
* Si elle renvoie `false`, listez d'abord `GET $TOKIOS_CONSOLE/account/deployments`, puis créez 1 déploiement par modèle qui doit être appelable :

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl -s -X POST "$TOKIOS_CONSOLE/account/deployments" \
  -H "Authorization: Bearer $TOKIOS_TOKEN" -H "Content-Type: application/json" \
  -d '{"public_name":"gemma4:e4b","upstream_model":"gemma4:e4b","connector_id":"con_…"}'
```

`public_name` est ce que les clients enverront dans le champ `model`. `upstream_model` doit être 1 des `announcedModels`. Un `409` signifie que le nom existe déjà ; laissez-le tel quel.

### Étape 5 : créer la clé API

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl -s -X POST "$TOKIOS_CONSOLE/account/keys" \
  -H "Authorization: Bearer $TOKIOS_TOKEN" -H "Content-Type: application/json" \
  -d '{"display_name":"laptop 2026-10-16","model_patterns":["gemma4:e4b"]}'
```

Réponse : `{"id":"key_…","secret":"sk-tok-…","retrievable":true}`. Le `secret` n'est affiché qu'une fois. Gardez-le pour le rapport. Restreignez `model_patterns` aux modèles que vous avez publiés ; omettez-le uniquement si l'humain a demandé tous les modèles.

### Étape 6 : vérifier

Exécutez la vérification de santé, un ping d'1 jeton via le tunnel :

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl -s -X POST "$TOKIOS_CONSOLE/account/models/healthcheck" \
  -H "Authorization: Bearer $TOKIOS_TOKEN" -H "Content-Type: application/json" \
  -d '{"model":"gemma4:e4b"}'
```

Attendez-vous à `"status":"ok"` avec un `latency_ms`. Ensuite faites 1 vrai appel avec la **clé API**, pas le jeton. L'URL de base du client est `https://api.tokios.com` ; confirmez-la avec `GET $TOKIOS_CONSOLE/account/connection`, qui renvoie `base_url`.

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl -s -X POST "https://api.tokios.com/v1/chat/completions" \
  -H "Authorization: Bearer sk-tok-…" -H "Content-Type: application/json" \
  -d '{"model":"gemma4:e4b","messages":[{"role":"user","content":"Say hello in five words."}],"max_tokens":32}'
```

### Étape 7 : rapport final

Donnez à l'humain :

* Connecteur : nom, id, statut, nom de machine.
* Modèles publiés : les noms publics, et si l'auto-publication les a créés ou si vous l'avez fait. Rappelez à l'humain qu'ils sont appelables par les détenteurs des clés API de l'espace de travail, pas par le public.
* Si le connecteur survit à un redémarrage : "non, il tourne détaché" sauf si vous avez installé un service, auquel cas dites lequel.
* Clé API : son id **et le secret `sk-tok-` lui-même**. C'est le 1 secret que vous devez remettre.
* Configuration client, depuis `GET $TOKIOS_CONSOLE/account/connection` :
  * Claude Code : `ANTHROPIC_BASE_URL=<base_url>`, `ANTHROPIC_API_KEY=<sk-tok-…>`, et le nom du modèle à passer avec `--model`.
  * Codex : `OPENAI_BASE_URL=<base_url>/v1`, `wire_api=responses`, `disable_response_storage=true`.
* Le résultat de la vérification : le statut du bilan de santé et la réponse du chat.
* Tout ce que vous avez sauté ou n'avez pas pu faire, et pourquoi.

> **[Jetons d'automatisation](/fr/setup/automation-tokens.md)**
>
> Portées, préréglages, expiration, et comment révoquer ou régénérer un jeton.

> **[Claude Code](/fr/guides/claude-code.md)**
>
> Pointez Claude Code vers la clé et le modèle que l'agent vient de créer.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.