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

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

에이전트라면: 브라우저 도구가 아닌 셸로 이 페이지의 원본 마크다운을 가져와야 명령과 JSON 구조가 그대로 전달됩니다:

curl -fsSL https://docs.tokios.com/guides/agent-setup.md

그 다음 에이전트를 위한 안내를 따르십시오. 이 사이트의 모든 페이지는 URL 뒤에 .md 를 추가하여 마크다운으로 이용할 수 있으며, 전체 사이트는 https://docs.tokios.com/llms-full.txt 에서 확인할 수 있습니다.

시작하기 전에

자동화 토큰 발급

콘솔에서 Settings 를 열고, Automation tokens 를 열고, Create token 을 클릭합니다. 프리셋은 Setup 을, 만료는 1 hour 를 사용합니다. 토큰은 한 번만 복사합니다. 자세한 내용은 자동화 토큰을 참조하십시오.

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

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

토큰을 셸 변수에 설정

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

Windows PowerShell
Windows CMD
macOS & Linux

$env:TOKIOS_CONSOLE="https://tokios.com"
$env:TOKIOS_TOKEN="at-tok-YOUR_TOKEN"
claude

set TOKIOS_CONSOLE=https://tokios.com
set TOKIOS_TOKEN=at-tok-YOUR_TOKEN
claude

export TOKIOS_CONSOLE=https://tokios.com
export TOKIOS_TOKEN=at-tok-YOUR_TOKEN
claude

에이전트에게 메시지 1회 전송

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 에서 토큰을 취소합니다.

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

에이전트를 위한 안내

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입니다. 커넥터가 자동으로 감지합니다.

규칙

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

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

1단계: 페어링 시작

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

curl -s "$TOKIOS_CONSOLE/account/connectors" -H "Authorization: Bearer $TOKIOS_TOKEN"

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

curl -s -X POST "$TOKIOS_CONSOLE/account/connectors/CONNECTOR_ID/claim-code" -H "Authorization: Bearer $TOKIOS_TOKEN"

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

curl -s -X POST "$TOKIOS_CONSOLE/account/connectors" \
  -H "Authorization: Bearer $TOKIOS_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"gpu-box"}'

둘 다 다음을 반환합니다:

{
  "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 대신 사용):

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 기준 표시):

$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개 인스턴스만 허용) 이 플랫폼에 대한 부팅 시 커넥터 실행 을 따릅니다. 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분간 폴링합니다:

curl -s "$TOKIOS_CONSOLE/account/connectors" -H "Authorization: Bearer $TOKIOS_TOKEN"

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

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단계: 모델 게시

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

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개의 배포를 생성합니다:

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 키 발급

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토큰 핑입니다:

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 을 반환합니다.

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.
검증 결과: 헬스 체크 상태와 채팅 응답.
건너뛰었거나 수행하지 못한 작업과 그 이유.

자동화 토큰

스코프, 프리셋, 만료, 토큰 취소 및 재생성 방법입니다.

Claude Code

에이전트가 방금 생성한 키와 모델로 Claude Code를 설정합니다.

하드웨어와 호환성

런타임 서빙과 연결

클라이언트 또는 앱 연결

비교

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

시작하기 전에

에이전트를 위한 안내

현재 보유한 정보

규칙

1단계: 페어링 시작

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

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

4단계: 모델 게시

5단계: API 키 발급

6단계: 검증

7단계: 최종 보고

자동화 토큰

Claude Code

​시작하기 전에

​에이전트를 위한 안내

​현재 보유한 정보

​규칙

​1단계: 페어링 시작

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

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

​4단계: 모델 게시

​5단계: API 키 발급

​6단계: 검증

​7단계: 최종 보고

자동화 토큰

Claude Code

시작하기 전에

에이전트를 위한 안내

현재 보유한 정보

규칙

1단계: 페어링 시작

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

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

4단계: 모델 게시

5단계: API 키 발급

6단계: 검증

7단계: 최종 보고