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

# 에이전트와 스크립트용 자동화 토큰 생성

> 스코프가 지정되고 만료 기한이 있는 자동화 토큰(at-tok-…)을 발급하면, 코딩 에이전트나 스크립트가 비밀번호 없이 API로 Tokios 워크스페이스를 설정하고 관리할 수 있습니다.

콘솔에서 직접 작업하는 것과 동일하게 **자동화 토큰**을 통해 프로그램이 워크스페이스를 관리할 수 있습니다. 커넥터 페어링, 모델 게시, API 키 생성, 사용량 조회가 가능합니다. 콘솔의 **Settings** 에서 토큰을 발급하고, 허용할 작업을 정확히 선택하며, 원하는 만료일을 설정합니다. Claude Code나 Codex 같은 코딩 에이전트, CI 작업, 또는 스크립트에 전달하면 해당 프로그램이 전체 설정을 자동으로 수행할 수 있습니다.

API 키와는 다릅니다. API 키(`sk-tok-…`)는 클라이언트가 모델을 호출할 때 사용합니다. 자동화 토큰(`at-tok-…`)은 프로그램이 워크스페이스를 관리할 때 사용하며, 이 토큰으로 모델을 호출할 수는 없습니다. 두 가지 용도는 절대 교차되지 않습니다.

> [!NOTE]
>
> 자동화 토큰은 자신의 워크스페이스에만 작동합니다. 비밀번호나 이메일을 변경하거나, API 키를 표시·공유하거나, 커넥터 토큰을 순환하거나, 저장된 프롬프트를 읽거나, 요청 로깅을 변경하거나, 다른 자동화 토큰을 생성할 수 없습니다. 이러한 작업은 로그인된 콘솔 세션에서만 가능합니다.

## 토큰 생성

워크스페이스 관리자만 자동화 토큰을 생성, 조회, 취소할 수 있습니다.

**1. Settings 열기**

콘솔에서 **[Settings](https://tokios.com/console/settings)** 를 열고 **Automation tokens** 까지 스크롤합니다. 이어서 **Create token** 을 클릭합니다.

**2. 사용 주체에 맞는 이름 지정**

토큰 목록과 해당 토큰이 생성하는 행에서 쉽게 식별할 수 있는 이름을 `claude-code on my laptop` 이나 `ci-deploy` 처럼 지정합니다.

**3. 프리셋 선택 또는 개별 스코프 지정**

**Setup** 은 커넥터 설치와 모델 호출 준비에 적합한 프리셋입니다. **Read-only** 는 모니터링에 적합합니다. **Full** 은 모든 스코프를 부여합니다. 그 외에는 개별 스코프를 선택합니다. 아래 [스코프](#scopes) 를 참조하십시오.

**4. 만료 기간 선택**

모든 토큰에는 만료 기간이 있습니다. 일회성 설정에는 1시간을, 정기 작업에는 더 긴 기간을 선택합니다. 최대 1년입니다.

**5. 토큰 복사**

토큰은 한 번만 표시됩니다. 프로그램의 비밀 저장소나 셸 변수에 복사합니다. 분실한 경우 목록에서 **Regenerate** 할 수 있으며, 이전 값은 즉시 사용 중지됩니다.

## 스코프

스코프는 `resource:verb` 형식입니다. 각 `write` 스코프에는 해당 `read` 가 포함됩니다. 어떤 스코프에도 `keys:rotate` 와 `models:reroute` 는 포함되지 않습니다.

| 스코프 | 허용 작업 |
| - | - |
| `connectors:read` | 커넥터 목록 조회 및 실시간 상태와 호스트 통계 확인 |
| `connectors:write` | 페어링 시작, 승인, 이름 변경, 취소, 커넥터 삭제. 아직 모델을 제공하는 커넥터를 삭제할 때 추가로 필요한 스코프: `models:reroute` |
| `models:read` | 모델, 배포, 모델 그룹, 가격, 한도 및 연결 정보 목록 조회 |
| `models:write` | 모델 생성, 수정, 일시 정지, 재개; 모델 그룹 생성, 수정, 삭제; 가격 설정 및 자동 게시 |
| `models:reroute` | 기존 모델을 다른 커넥터로 이동, 이름 변경 또는 삭제. 각 작업은 해당 모델의 트래픽을 받는 머신을 바꾸므로 `models:write` 도 필요하며, 포함되는 유일한 프리셋: **Full** |
| `keys:read` | API 키 목록 조회(지문 및 설정만, 비밀 값 제외) |
| `keys:write` | API 키 생성, 수정, 취소, 삭제(새로 생성한 키의 비밀 값은 한 번만 반환됨) |
| `keys:rotate` | 기존 API 키 순환 및 새 비밀 값 수신. 키 소유권을 이전하므로 포함되는 유일한 프리셋: **Full** |
| `usage:read` | 사용량, 지출 및 요청 로그 조회(개수 및 메타데이터만) |
| `playground:run` | 플레이그라운드 및 모델 상태 확인 실행(모델에 프롬프트 전송) |

| 프리셋 | 스코프 |
| - | - |
| **Setup** | `connectors:read`, `connectors:write`, `models:read`, `models:write`, `keys:read`, `keys:write`, `playground:run` |
| **Read-only** | `connectors:read`, `models:read`, `keys:read`, `usage:read` |
| **Full** | 위의 모든 스코프 |

토큰의 스코프를 벗어나는 호출은 누락된 스코프가 오류에 표시된 `403` 을 반환하므로, 프로그램이 어떤 권한이 부족한지 정확히 알려줄 수 있습니다.

## 토큰 사용

API 호스트가 아닌 콘솔 호스트에 Bearer 토큰으로 전송합니다. 모든 관리 호출은 `https://tokios.com/account/` 아래에 있습니다.

**macOS & Linux**

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl -s https://tokios.com/account/connectors \
  -H "Authorization: Bearer at-tok-YOUR_TOKEN"
```

**Windows CMD**

```cmd theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl -s "https://tokios.com/account/connectors" -H "Authorization: Bearer at-tok-YOUR_TOKEN"
```

| 응답 | 의미 |
| - | - |
| `401` | 토큰이 유효하지 않거나, 만료되었거나, 취소되었거나, 생성한 관리자가 비밀번호를 변경하거나 재설정했거나, 워크스페이스 또는 해당 관리자가 정지된 경우입니다. |
| `403` 과 `"scope"` | 토큰에 해당 스코프가 없습니다. |
| `403` "only available from the console" | 로그인된 콘솔 세션에만 예약된 작업입니다. 어떤 스코프도 이를 허용하지 않습니다. |
| `429` | 이 토큰으로 분당 240회 초과 호출이거나, 이 주소에서 토큰 시도 실패가 너무 많은 경우입니다. 잠금은 유효한 토큰을 포함해 해당 주소의 모든 토큰에 적용됩니다. 잠시 후 재시도하십시오. |

자동 설정이 호출하는 전체 호출 목록과 순서는 [코딩 에이전트가 Tokios를 자동으로 설정](/ko/guides/agent-setup.md) 을 참조하십시오.

## 에이전트에 전달

토큰을 **Setup** 프리셋으로, 만료 기간을 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 https://tokios.com and the automation token is in the TOKIOS_TOKEN environment variable. 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.
```

비밀 값이 대화에 나타나지 않도록 에이전트 시작 전에 `TOKIOS_TOKEN` 을 셸에 설정합니다. 가이드 페이지에 에이전트가 필요한 모든 정보가 안내되어 있습니다.

## 토큰 관리

콘솔의 **Settings** 각 행에는 토큰의 스코프, 지문, 만료일, 마지막 사용 일시 및 IP 주소가 표시됩니다.

* **Regenerate** 는 비밀 값을 교체합니다. 이전 값은 즉시 사용 중지되며 새 값은 한 번만 표시됩니다.
* **Revoke** 는 토큰을 영구적으로 중지합니다. 새 토큰을 생성하여 교체합니다.
* **Delete** 는 취소되었거나 만료된 토큰을 목록에서 제거합니다.

비밀번호를 변경하거나 재설정하면 생성한 모든 토큰이 취소됩니다. 도난당한 세션에서 발급된 토큰은 계정을 복구하는 즉시 작동을 멈추며, 상시 실행되는 작업에는 이후 새 토큰이 필요합니다.

자동화 토큰이 생성한 행에는 **via token** 배지가 **Connectors**, **Models**, **Keys** 탭에 표시되므로, 프로그램이 수행한 작업을 항상 확인할 수 있습니다. 배지는 토큰이 삭제된 후에도 유지됩니다.

## 토큰 보안 유지

* **스코프를 좁게 지정하십시오.** 작업을 완료한 Setup 토큰은 보관하지 말고 취소해야 합니다.
* **만료 기간을 짧게 설정하십시오.** 대화형 에이전트 세션에는 1시간을 사용합니다. 긴 만료 기간은 비밀 저장소에 등록된 정기 작업에만 적합합니다.
* **대화 기록에 남기지 마십시오.** 셸 변수에서 읽어들여야 하며, 에이전트와의 채팅에 붙여넣지 않습니다.
* **배지와 마지막 사용 열을 확인하십시오.** 알 수 없는 주소에서 토큰이 사용된 경우 즉시 취소합니다.
* **발급된 키의 의미를 이해하십시오.** 토큰에 `keys:write` 가 있으면 API 키를 생성할 수 있으며, 해당 키는 토큰이 만료된 후에도 계속 작동합니다. 1시간짜리 Setup 토큰을 훔친 사람은 만료 기간이 없는 키를 발급하여 사용자가 알아차릴 때까지 모델을 호출할 수 있습니다. 에이전트 작업 후에는 **Keys** 탭에서 **via token** 으로 표시된 행을 확인하고 예상치 못한 키를 취소합니다.
* **필요할 때만 `models:reroute` 를 부여하십시오.** 기존 모델을 이동, 이름 변경 또는 삭제하면 해당 트래픽을 받는 머신이 바뀝니다. 커넥터 페어링도 할 수 있는 토큰은 보유자가 제어하는 머신을 페어링하고 모델을 그곳으로 옮길 수 있습니다. Setup 에는 이 스코프가 필요하지 않습니다: 모델을 생성할 뿐 이동하지 않습니다.
* **공유 주소는 잠금도 공유합니다.** 한 IP 주소에서 토큰 시도가 8회 실패하면, 해당 주소의 모든 토큰이 유효한 토큰을 포함해 `429` 로 6분 동안 거부됩니다. 같은 사무실 네트워크, NAT 게이트웨이 또는 CI 러너 풀 뒤에 있는 에이전트는 이 잠금을 공유합니다. 한 클라이언트가 잘못된 토큰을 계속 보내면 루프로 재시도하게 두지 말고 중지하거나 수정하십시오.

> **[에이전트 기반 설정](/ko/guides/agent-setup.md)**
>
> 에이전트가 Setup 토큰으로 수행하는 단계별 절차입니다.

> **[API 키](/ko/setup/api-keys.md)**
>
> 클라이언트가 모델을 호출할 때 사용하는 키입니다.


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