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

# 코딩 에이전트에게 Tokios 설정 맡기기

> Claude Code, Codex 또는 다른 코딩 에이전트에게 자동화 토큰과 이 페이지를 전달하십시오. 에이전트가 커넥터를 페어링하고, 모델을 게시하고, API 키를 발급하고, 전체 경로를 무인으로 검증합니다.

이 페이지의 독자는 2명입니다. 첫 번째 섹션은 여러분을 위한 것입니다. 그리고 [에이전트를 위한 안내](#instructions-for-the-agent) 이후의 모든 내용은 에이전트가 읽고 실행하도록 작성되었습니다.

> [!NOTE]
>
> **에이전트라면:** 브라우저 도구가 아닌 셸로 이 페이지의 원본 마크다운을 가져와야 명령과 JSON 구조가 그대로 전달됩니다:
>
> ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
> curl -fsSL https://docs.tokios.com/guides/agent-setup.md
> ```
>
> 그 다음 [에이전트를 위한 안내](#instructions-for-the-agent)를 따르십시오. 이 사이트의 모든 페이지는 URL 뒤에 `.md` 를 추가하여 마크다운으로 이용할 수 있으며, 전체 사이트는 `https://docs.tokios.com/llms-full.txt` 에서 확인할 수 있습니다.

## 시작하기 전에

**1. 자동화 토큰 발급**

콘솔에서 **[Settings](https://tokios.com/console/settings)** 를 열고, **Automation tokens** 를 열고, **Create token** 을 클릭합니다. 프리셋은 **Setup** 을, 만료는 **1 hour** 를 사용합니다. 토큰은 한 번만 복사합니다. 자세한 내용은 [자동화 토큰](/ko/setup/automation-tokens.md)을 참조하십시오.

**2. 모델을 제공하는 머신에서 에이전트 실행**

에이전트는 해당 머신에서 커넥터 설치 명령을 실행해야 합니다. Ollama, LM Studio, llama.cpp, 또는 vLLM이 이미 기본 포트에서 실행 중인지 확인합니다.

**3. 토큰을 셸 변수에 설정**

변수를 설정한 다음, 같은 셸에서 에이전트를 시작하여 비밀 값이 대화에 유입되지 않도록 합니다.

**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. 에이전트에게 메시지 1회 전송**

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

백엔드 이름으로 `Ollama` 를 실제 사용 중인 값으로 바꾸십시오. Codex도 같은 메시지가 작동합니다. 에이전트가 서비스를 설치하도록 하려면 "Make the connector start at boot." 를 추가합니다. 그렇지 않으면 에이전트는 커넥터가 재부팅 후에는 유지되지 않는다는 사실만 알려 줍니다.

에이전트가 실행되는 동안 **Connectors** 탭을 주시합니다. 대기 중인 디바이스가 나타나고, 곧 커넥터가 알린 모델과 함께 활성 상태로 전환됩니다. 에이전트가 생성한 행에는 **via token** 배지가 표시됩니다. 에이전트가 보고하면 **Settings** 에서 토큰을 취소합니다.

> [!NOTE]
>
> 코딩 에이전트는 다운로드한 스크립트를 셸에 파이프하는 것을 거부하므로, 에이전트는 설치 원라이너를 사용하지 않습니다. 게이트웨이를 통해 커넥터 바이너리를 다운로드하고, 체크섬을 검증하고, 직접 시작합니다. 에이전트가 중지되고 차단된 설치 프로그램 명령에 대해 물어보면, 이 페이지를 다시 안내합니다.

## 에이전트를 위한 안내

Tokios 워크스페이스를 자동으로 설정합니다: 이 머신의 커넥터를 페어링하고, 로컬 모델을 게시하고, 코딩 클라이언트를 위한 API 키를 발급하고, 전체 경로를 검증합니다. 워크스페이스의 관리 API를 자동화 토큰이라는 1개의 자격 증명으로 조작합니다.

### 현재 보유한 정보

* `TOKIOS_CONSOLE`: 콘솔 기본 URL, 일반적으로 `https://tokios.com` 입니다. 아래 모든 호출은 `TOKIOS_CONSOLE` + `/account/...` 입니다.
* `TOKIOS_TOKEN`: 자동화 토큰, `at-tok-…` 입니다. 모든 호출에 `Authorization: Bearer <token>` 으로 전송합니다. Setup 스코프가 있으며 곧 만료됩니다.
* 이 머신의 루프백에서 이미 실행 중인 모델 서버: Ollama는 포트 11434, LM Studio는 1234, llama.cpp는 8080, 또는 vLLM은 8000입니다. 커넥터가 자동으로 감지합니다.

### 규칙

1. **토큰을 출력하거나, 로그에 남기거나, 어디에도 기록하지 마십시오.** 단, `Authorization` 헤더는 예외입니다. 셸 변수에서 매번 읽습니다: bash에서는 `$TOKIOS_TOKEN`, PowerShell에서는 `$env:TOKIOS_TOKEN`, cmd에서는 `%TOKIOS_TOKEN%` 입니다. 5단계에서 발급하는 API 키는 다릅니다: 최종 보고에서 사람에게 전달합니다.
2. 토큰은 `TOKIOS_CONSOLE/account/*` 에서만 작동합니다. 이 토큰을 `/admin`, `/auth`, `/v1`, `/portal` 에 사용하려고 하지 않습니다.
3. **생성하기 전에 목록을 조회하십시오.** 같은 이름의 대기 중인 커넥터와 같은 공개 이름의 배포를 재사용합니다. 재시도가 실패했다고 해서 두 번째 API 키를 생성하지 않습니다. 생성은 일반 POST이며 멱등성이 없습니다.
4. 오류는 JSON입니다: `{"error":{"message":"…","type":"…","scope":"…"}}`.
   * `401`: 토큰이 유효하지 않거나, 만료되었거나, 취소된 경우입니다. 중지하고 보고합니다.
   * `403` 응답에 `scope` 가 있는 경우: 토큰에 해당 스코프가 없습니다. 중지하고 어떤 스코프가 부족한지 보고합니다.
   * `403` "only available from the console": 로그인된 사람만 수행할 수 있는 작업입니다. 우회하지 않습니다.
   * `409` (승인 시): 커넥터 행을 다시 읽고 3단계에서 설명한 대로 재시도합니다.
   * `429`: 60초 대기 후 재시도합니다.
5. 비밀번호를 변경하거나, 키를 공개·공유하거나, 요청 로깅을 변경하거나, 다른 토큰을 생성하지 않습니다. 불가능하며 시도해서도 안 됩니다.
6. 매 단계의 결과를 보고합니다. 단계를 실패하거나 건너뛴 경우 명확히 알립니다.

예시는 bash를 사용합니다. Windows cmd에서는 URL과 JSON을 큰따옴표로 감싸고 내부 따옴표를 이스케이프합니다. 예를 들어 `-d "{\"name\":\"gpu-box\"}"` 입니다.

### 1단계: 페어링 시작

먼저 기존 커넥터 목록을 조회합니다:

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

의도한 이름의 행에 이미 `"status":"pending_pair"` 가 있으면, 새 페어링 코드로 재사용합니다:

```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"
```

그렇지 않으면 새로 생성합니다:

```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"}'
```

둘 다 다음을 반환합니다:

```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'"
  }
}
```

페어링 코드는 15분 동안 유효합니다. `claim_code` 와 `server_url` 을 보관하고, `install_oneliner` 는 무시합니다(스크립트를 셸에 파이프하므로 사용하면 안 됩니다 — 2단계 참조). 이 응답에는 커넥터 토큰이 없으며 앞으로도 없을 것입니다: 커넥터는 승인 후 터널을 통해 자체 자격 증명을 받습니다.

### 2단계: 이 머신에서 커넥터를 분리 모드로 설치 및 시작

에이전트 안전 규칙은 다운로드한 스크립트를 셸에 파이프하는 것을 거부합니다(`curl … | sh`, `irm … | iex`). 스크립트를 저장하고 실행하는 것도 본질적으로 동일합니다. 둘 다 수행하지 말고, 사람에게 승인을 요청하지도 않습니다.
경로 A를 사용합니다. 다운로드한 스크립트를 실행하지 않습니다: 게이트웨이의 리다이렉트를 통해 커넥터 바이너리 자체를 다운로드하고, 릴리스의 `SHA256SUMS` 에 대해 검증하고, 1단계의 페어링 코드와 `server_url` 로 백그라운드에서 시작합니다.

**경로 A(이 경로 사용): 바이너리를 다운로드하고, 검증한 다음, 실행합니다.**

이 머신에 맞는 자산을 선택합니다: `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 및 macOS(`linux/x64` 기준 표시; macOS에서는 `shasum -a 256` 을 `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, PowerShell(`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
```

1단계의 값으로 `TKS-XXXX-XXXX` 를 `claim_code` 로, `SERVER_URL` 을 `server_url` 로 교체합니다. 커넥터가 외부로 연결하여 코드를 제시하고, 승인을 대기한 다음, 바이너리 옆에 자체 설정을 기록합니다. 머신에 이미 `tokios-connector` 가 설치되어 있으면 다운로드를 건너뛰고 해당 바이너리를 같은 방식으로 실행합니다.

**경로 B(사람이 설치 프로그램을 요청한 경우에만):** 설치 프로그램은 동일한 다운로드 및 체크섬 단계를 수행하고 `--detach` 플래그를 추가합니다. 사람이 붙여넣도록 설계되었습니다. 사용 요청을 받으면, 파일로 다운로드하여 실행 전에 저장된 파일을 읽고, 보고에 이를 알립니다. 절대 파이프하지 않습니다.

커넥터의 출력은 `tokios-connector-stdout.log` 에, pid는 `tokios-connector.pid` 에 저장되며, 위 디렉터리에 있습니다. 나중에 `kill $(cat tokios-connector.pid)` 또는 `Stop-Process -Id (Get-Content tokios-connector.pid)` 로 중지합니다.

**지속성.** 분리된 프로세스는 재부팅 후에도 유지되지 않습니다. 사람의 메시지에서 커넥터를 부팅 시 시작하도록 요청하지 않는 한 서비스를 설치하지 않습니다. 그렇지 않으면 최종 보고에 이를 알리고 옵션을 제공합니다. 요청을 받은 경우: 먼저 3단계에서 6단계까지 완료한 다음, 분리된 프로세스를 중지하고(`kill $(cat tokios-connector.pid)`; 커넥터는 디렉터리당 1개 인스턴스만 허용) 이 플랫폼에 대한 [부팅 시 커넥터 실행](/ko/setup/connector-install.md#run-the-connector-at-boot) 을 따릅니다. Linux에서는 `ExecStart` 가 `%h/.tokios/connector/tokios-connector --config %h/.tokios/connector/tokios-connector.json` 인 systemd 사용자 유닛이며, `systemctl --user enable --now tokios-connector` 로 활성화하고, `loginctl enable-linger "$USER"` 로 로그인 없이 시작되도록 합니다. 페어링은 `tokios-connector.json` 에 저장되므로, 서비스가 새 페어링 코드 없이 재연결됩니다.

### 3단계: 디바이스를 기다린 후 승인

3초마다 최대 2분간 폴링합니다:

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

자신의 `connector_id` 를 찾습니다. 행에 `"claimPending": true` 가 표시되면, `"sessionId": "sess_…"` 와 `"machineName"` 도 함께 포함됩니다. 머신 이름이 이 머신인지 확인한 다음, 해당 정확한 세션 ID로 승인합니다:

```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_…"}'
```

성공 시 `{"status":"approved"}` 입니다.

응답 코드 `409` 의 경우, 디바이스가 새 세션 ID로 재연결되었거나, 아직 연결되지 않았거나, 페어링 코드가 만료된 경우입니다. 행을 다시 읽습니다. 코드가 만료된 경우, 1단계와 같이 새 코드를 요청하고 그 코드로 커넥터를 재시작합니다. 그렇지 않으면 현재 `sessionId` 로 다시 승인합니다.

행에 `"status":"active"`, `"online":true`, 비어 있지 않은 `"announcedModels"` 가 표시될 때까지 폴링을 계속합니다. 최대 60초를 허용합니다: 커넥터는 승인 후 로컬 모델을 감지합니다. 그래도 `announcedModels` 가 비어 있으면 감지된 루프백 포트에서 실행 중인 모델 서버가 없는 것입니다. 이를 보고하고 중지합니다.

### 4단계: 모델 게시

워크스페이스 정책을 확인합니다:

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

* 반환 값이 `{"auto_publish": true}` 이면, 커넥터가 알린 모든 모델이 자동으로 게시됩니다. 이어서 `GET $TOKIOS_CONSOLE/account/models` 를 폴링하여 알린 모델 이름이 `id` 값으로 나타날 때까지 기다립니다.

  보고할 때 의미를 정확히 전달합니다. "게시됨"은 모델에 이 워크스페이스의 배포가 있다는 의미입니다: 이 워크스페이스의 API 키 중 모델 스코프가 해당 모델을 포함하는 키를 가진 사람이 API 호스트에서 호출할 수 있으며, 다른 사람은 호출할 수 없습니다. 키 없이는 아무것도 접근할 수 없습니다. 커넥터가 승인 후 몇 초 내에 모델을 알리는 순간 발생하며, 공개 이름은 업스트림 모델 ID입니다(예: `gemma4:e4b`). 자동 게시는 삭제한 모델도 커넥터가 다시 알리면 재게시합니다. 따라서 사람이 감지된 모델 중 일부만 노출하려면, `POST $TOKIOS_CONSOLE/account/deployments/DEPLOYMENT_ID/disable` 로 나머지를 일시 정지하고 자동 게시가 켜져 있음을 알립니다. 일시 정지된 모델은 계속 일시 정지 상태로 유지됩니다. 삭제하지 마십시오: 삭제에는 `models:reroute` 스코프가 필요한데 Setup 프리셋에는 포함되어 있지 않으며, 자동 게시가 삭제된 모델을 다시 게시합니다.
* 반환 값이 `false` 이면, 먼저 `GET $TOKIOS_CONSOLE/account/deployments` 로 목록을 조회한 다음, 호출 가능해야 하는 모델당 1개의 배포를 생성합니다:

```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` 은 클라이언트가 `model` 필드로 전송할 값입니다. `upstream_model` 은 `announcedModels` 중 1개여야 합니다. 응답이 `409` 이면 이름이 이미 존재한다는 뜻입니다. 그대로 둡니다.

### 5단계: 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"]}'
```

응답: `{"id":"key_…","secret":"sk-tok-…","retrievable":true}`. 응답의 `secret` 은 한 번만 표시됩니다. 보고를 위해 보관합니다. 게시한 모델로 `model_patterns` 을 제한합니다. 사람이 모든 모델을 요청한 경우에만 생략합니다.

### 6단계: 검증

헬스 체크를 실행합니다. 터널을 통한 1토큰 핑입니다:

```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"}'
```

결과로 `"status":"ok"` 와 `latency_ms` 를 예상합니다. 그 다음 토큰이 아닌 **API 키**로 실제 호출을 1회 수행합니다. 클라이언트 기본 URL은 `https://api.tokios.com` 입니다. 이 값은 `GET $TOKIOS_CONSOLE/account/connection` 으로 확인하며, 이 호출은 `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}'
```

### 7단계: 최종 보고

사람에게 다음을 제공합니다:

* 커넥터: 이름, id, 상태, 머신 이름.
* 게시된 모델: 공개 이름, 그리고 자동 게시가 생성했는지 직접 생성했는지. 사람에게 이들은 워크스페이스 API 키 보유자가 호출할 수 있으며 일반 대중이 호출할 수 없음을 상기시킵니다.
* 커넥터가 재부팅 후에도 유지되는지 여부: 서비스를 설치하지 않은 경우 "아니오, 분리 모드로 실행 중"이며, 설치한 경우 어떤 서비스인지 알립니다.
* API 키: id **및 `sk-tok-` 비밀 값**. 이것이 전달해야 하는 1개의 비밀입니다.
* 클라이언트 설정, `GET $TOKIOS_CONSOLE/account/connection` 에서:
  * Claude Code: `ANTHROPIC_BASE_URL=<base_url>`, `ANTHROPIC_API_KEY=<sk-tok-…>`, 그리고 `--model` 로 전달할 모델 이름.
  * Codex: `OPENAI_BASE_URL=<base_url>/v1`, `wire_api=responses`, `disable_response_storage=true`.
* 검증 결과: 헬스 체크 상태와 채팅 응답.
* 건너뛰었거나 수행하지 못한 작업과 그 이유.

> **[자동화 토큰](/ko/setup/automation-tokens.md)**
>
> 스코프, 프리셋, 만료, 토큰 취소 및 재생성 방법입니다.

> **[Claude Code](/ko/guides/claude-code.md)**
>
> 에이전트가 방금 생성한 키와 모델로 Claude Code를 설정합니다.


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