xenocast 레퍼런스

xenocast는 macOS 빌드와 테스트를 실행하는 프로그램 하나입니다, 터미널에서는 명령으로 쓰고 AI 앱에는 같은 프로그램이 직접 연결됩니다, 이 페이지에서 설치, 로그인, 명령과 출력 전체를 확인할 수 있습니다, 옛 이름 xenoci도 같은 명령으로 동작합니다

API 키는 xenocast의 로그인 수단입니다, 콘솔에서 크레딧을 충전하고 API 키 화면에서 키를 만든 직후 복사해 키를 담은 지시문 하나를 Claude Code, Codex, Cursor 같은 AI 에이전트에 붙여 넣습니다, 에이전트가 설치 한 줄로 xenocast를 설치하고 키를 키체인이나 암호화 파일에 저장한 뒤 이 컴퓨터의 AI 앱에 자동으로 연결합니다, 키를 파일, 저장소, 로그에 남기거나 커밋하지 않습니다

설치를 마치면 whoami로 확인합니다, 나중에 AI 앱을 새로 설치했다면 xenocast setup을 다시 실행합니다

인증

인증은 콘솔 API 키 화면에서 발급한 키(xci_live_…) 하나뿐입니다, xenocast는 다음 순서로 키를 찾습니다

• 환경 변수 XENOCI_API_KEY(저장된 키보다 우선)
• xenocast login, xenocast setup 또는 xenocast config set api-key로 저장한 키

키가 없으면 키가 필요한 명령은 서버에 요청하지 않고 종료 코드 2, api_key_required로 끝납니다, 전달한 키로 설치와 로그인을 완료하도록 에이전트에 요청합니다, 터미널에서는 xenocast login을 쓰거나 XENOCI_API_KEY를 설정할 수도 있습니다

쓸 수 있는 명령은 login, setup, config, whoami, credits, usage, runners, build, status, jobs, logs, cancel, wait, artifacts, mcp입니다, 옛 세션 로그인 명령은 api_key_mode로, 옛 임대 명령은 runner2_unsupported로 거절됩니다

login

xenocast login

터미널의 가린 입력으로 콘솔에서 만든 키를 받아 저장합니다, 에이전트처럼 대화형 터미널이 없는 환경에서는 전달받은 키를 XENOCI_API_KEY로 사용하거나 아래 config set api-key --key-env VAR로 저장합니다, 키 값을 명령줄 인자로 넣지 않습니다

setup

xenocast setup [--agent auto|claude|cursor|codex|opencode|omo|all|none] [--force] [--key-env VAR] [--no-tui] [--from-installer] [--api-url URL]

터미널에서 키를 가린 입력으로 받아 키체인이나 암호화 파일에 저장하고, 서버에서 키를 확인한 뒤 설치된 AI 앱(Claude Code, Codex, Cursor, OpenCode, OmO)에 xenocast를 연결합니다, 화면과 출력에 키가 나오지 않고, xci_live_ 형식이 아니면 저장하지 않습니다, XENOCI_API_KEY나 저장된 키가 이미 있으면 묻지 않고 그 키를 씁니다

터미널이 아닌 곳(에이전트의 셸, CI)에서 환경 변수, 저장된 키, --key-env로 읽을 키가 없으면 기다리지 않고 종료 코드 2, api_key_required로 끝납니다, 서버에는 요청하지 않습니다

xenocast --help

--key-env VAR는 전달받은 키가 있는 환경 변수를 지정합니다, --no-tui는 TUI를 끄고 --from-installer는 설치 스크립트에서 사용하는 옵션입니다, --agent로 연결할 앱을 고르고 --agent none이면 앱 연결 없이 키만 확인합니다

공통 옵션

--이름=값과 --이름 값은 같습니다, 출력에 섞인 xci_live_… 문자열은 [REDACTED]로 가립니다

환경 변수

config

xenocast config show
xenocast config set api-key [--key-env VAR]
xenocast config unset api-key

• show: 키 출처(XENOCI_API_KEY 또는 저장된 키)와 가린 값(xci_live_…abcd), API 주소를 보여 줍니다
• set api-key: 키를 표준 입력으로 받거나 --key-env 변수이름에서 읽어 저장합니다, 명령줄 인자로는 받지 않습니다, 저장 뒤 XENOCI_API_KEY가 있으면 그것이 우선합니다
• unset api-key: 저장된 키를 지웁니다

printf %s "$XENOCI_API_KEY" | xenocast config set api-key
xenocast config set api-key --key-env MY_KEY

whoami

xenocast whoami

키의 조직, 워크스페이스, 키 이름과 ID, 권한(run 또는 read), 키 출처, 사용 가능 잔액과 충전 링크를 보여 줍니다, --json이면 조직, 워크스페이스, 키 권한과 잔액 정보를 JSON으로 출력합니다

credits

xenocast credits
xenocast credits topup [--open]

credits는 현재 잔액, 사용 가능 금액, 실행 중 잡이 쓴 금액과 충전 링크를 보여 줍니다

잔액 US$20.00 (사용 가능 US$19.92, 실행 중 잡 US$0.08)
분당 US$0.0396
만료 예정 US$20.00 (2027-10-11T03:00:00.000Z)
충전: https://xenoci.com/console/billing (로그인한 사람이 콘솔에서 결제)

• 사용 가능은 살아 있는 크레딧에서 실행 중 잡이 이미 쓴 금액을 뺀 값입니다
• 잔액이 적으면 잔액이 적습니다 (기준 US$1.19 미만) 줄이 더 붙습니다
• topup은 충전 링크만 출력합니다, --open은 브라우저로 엽니다, xenocast는 결제하지 않습니다

usage

xenocast usage [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--by day|workspace|api_key]

사용량을 조회해 묶음마다 잡 수, 과금 초, 금액(USD)을 한 줄씩 내고 합계를 붙입니다, 날짜는 한국 시간이고 양끝 포함, 최대 366일, 비우면 이번 달 1일부터 오늘까지입니다, 키로 부르면 키의 워크스페이스만 집계합니다

2026-10-11 잡 4개 7분 US$0.23
합계 잡 4개 7분 US$0.23

runners

xenocast runners [--json]

러너 목록을 한 줄씩 보여 줍니다: ID, 사용 가능 여부, 이름, vCPU와 메모리, 분당 단가, 빈 슬롯입니다, 예 macos-m4 (기본) 사용 가능, macOS M4, vCPU 4, 메모리 7GB, 분당 $0.0396, 빈 슬롯 3/8

• build --runner에는 사용 가능인 ID만 넣습니다, 준비 중인 러너(macos-m4-pro, macos-m4-max, macos-m6)는 runner_not_available로 거절됩니다
• --json은 러너 목록과 기본 러너 ID를 JSON으로 출력합니다

build

xenocast build --script FILE_OR_COMMAND
  [--dir DIR | --repo owner/name [--ref REF] | --repo-url URL [--ref REF]]
  [--runner ID] [--xcode VERSION] [--timeout MINUTES] [--artifacts GLOBS] [--no-wait]

동작

1. 소스를 올리고 업로드: 파일 N개 (MB)를 표준 오류에 씁니다
2. 잡을 접수하고 잡 접수: job_…를 씁니다, 대기 중이면 (대기: 용량)(빈 러너 없음) 또는 (대기: 동시 실행 한도)가 붙습니다
3. 로그를 2초 간격으로 받아 표준 출력에 그대로 씁니다
4. 끝나면 요약 한 줄을 표준 오류에 씁니다

잡 job_Ab12Cd34 succeeded (종료 코드 0), 실행 125초, 과금 125초, 금액 $0.0825, 남은 잔액 $19.92

Ctrl+C(SIGINT)나 CI 중단(SIGTERM)을 받으면 접수된 잡을 취소하고 130 또는 143으로 끝납니다

--json의 최종 출력

{"id":"job_Ab12Cd34","status":"succeeded","exit_code":0,"run_seconds":125,"billed_seconds":125,"billed_minutes":3,"amount_micro_usd":82500,"amount_usd":"0.0825","balance":{"available_micro_usd":19917500,"available_usd":"19.92","topup_url":"https://xenoci.com/console/billing"}}

실패한 잡은 failure_excerpt(마지막 로그에서 고른 오류 발췌)가 더 붙습니다

옛 임대 옵션(--mac, --persist, --priority, --pr, --commit, --github-status, --notify 등)은 없어졌고 주면 사용법 오류(알 수 없는 옵션)입니다

status

xenocast status job_Ab12Cd34

잡의 요약 한 줄(상태, 종료 코드, 실행 초, 과금 초, 금액)을 씁니다, 금액은 과금 초로 계산하고 1분이 안 되는 잡은 과금 60초(최소 1분)로 나옵니다, 잔액이 적으면 경고 줄이 표준 오류에 붙습니다, --json이면 잡 객체 전체입니다

jobs

xenocast jobs [--status STATUS] [--limit N] [--cursor CURSOR]

최근 잡을 조회해 최신순 목록을 JSON으로 냅니다, --limit는 1~100(기본 20), 다음 페이지는 응답의 next_cursor를 --cursor에 넘깁니다, --status는 queued, preparing, running, succeeded, failed, cancelled, credit_exhausted, platform_error, timed_out 중 하나입니다

logs

xenocast logs job_Ab12Cd34
xenocast logs job_Ab12Cd34 --wait
xenocast logs job_Ab12Cd34 --tail 200
xenocast logs job_Ab12Cd34 --failure

• 옵션 없이: 지금까지의 로그 전체를 표준 출력에 씁니다
• --wait: 끝날 때까지 따라가며 출력하고, 끝나면 요약 줄을 쓰고 잡의 종료 코드로 끝납니다
• --tail N: 마지막 N줄
• --failure: 오류로 보이는 부분만 발췌

xenocast가 로그를 받아 보여 주며 잡당 5MB까지 보관합니다

cancel

xenocast cancel job_Ab12Cd34

대기 중이거나 실행 중인 잡을 멈추고 바뀐 잡 객체를 출력합니다, 멈춘 순간까지 실행한 초는 과금됩니다, 이미 취소된 잡을 다시 취소하면 그대로 잡을 돌려줍니다

wait

xenocast wait job_Ab12Cd34 [--timeout SECONDS]

잡이 끝날 때까지 2초 간격으로 확인합니다, --timeout(기본 60초) 안에 끝나지 않으면 잡 객체를 출력하고 종료 코드 124로 끝납니다, 끝났으면 요약 줄을 쓰고 잡의 종료 코드를 돌려줍니다

xenocast wait job_Ab12Cd34 --timeout 1800 && ./deploy.sh

artifacts

xenocast artifacts job_Ab12Cd34
xenocast artifacts job_Ab12Cd34 --out ./dist

• 옵션 없이: 결과물 목록(id, name, path, bytes, sha256, expires_at)을 JSON으로 출력
• --out DIR: 각 결과물을 받아 DIR/<이름>에 저장하고 [xenocast] App.ipa 12.3MB → ./dist를 표준 오류에 씁니다

AI 앱에서 쓸 때

AI 앱에는 같은 xenocast가 MCP(AI 앱이 외부 도구를 부르는 표준 방식) 서버로 붙습니다, xenocast setup이 연결을 맡고 따로 설치할 것은 없습니다, 키 규칙도 위와 같아서 앱 설정에는 실행 명령만 들어가고 키는 들어가지 않습니다, 키를 바꾼 뒤에는 앱을 다시 시작합니다

명령과 도구 이름

에이전트에게 "xenoci whoami 도구를 불러 줘"라고 하면 연결을 확인할 수 있습니다, initialize 응답의 serverInfo.name은 xenocast이고, instructions에 에이전트용 안내가 들어 있습니다(에이전트 규칙)

직접 연결

xenocast setup은 기존 설정을 지우지 않고 xenoci 항목만 더하며, 고치기 전 파일을 .bak-xenocast- 이름으로 백업하고, 이미 있으면 건너뜁니다(--force로 다시 씁니다), Cursor는 cursor-agent mcp enable xenoci도 실행합니다, 직접 연결하려면 아래를 씁니다

Claude Code

claude mcp add --transport stdio --scope user xenoci -- "$(which xenocast)" mcp
claude mcp list

Codex

codex mcp add xenoci -- "$(which xenocast)" mcp

Cursor: ~/.cursor/mcp.json(또는 저장소의 .cursor/mcp.json)

{
  "mcpServers": {
    "xenoci": { "command": "xenocast", "args": ["mcp"] }
  }
}

그 밖의 앱은 명령 xenocast, 인자 ["mcp"]로 등록합니다(xenocast mcp가 표준 입출력으로 연결을 받습니다), 환경 변수로 로그인하는 경우 그 프로세스가 XENOCI_API_KEY를 물려받도록 합니다

도구 입력

tools/list의 inputSchema가 기준입니다, 타입을 그대로 보내야 하며(wait: "true"나 lines: "2" 불가), 스키마에 없는 인수는 unknown_argument로 거절됩니다

build

새 macOS VM에서 스크립트를 실행하는 잡을 접수하고 ID를 돌려줍니다

응답(wait: false): 잡 객체와 next: { tool: "status", arguments: { id } }, 폴더를 올렸으면 upload: { id, files }가 붙습니다

응답(wait: true): 끝난 잡 객체, exit_code, balance(잔액 뷰), 기다리는 동안 로그가 notifications/progress로 흐릅니다, 스크립트가 0이 아니면 isError: true와 failure_excerpt가 붙습니다

{"name":"build","arguments":{"dir":"/absolute/project","script":"bash ci.sh","artifacts":["build/*.xcresult"]}}

status

ID를 주면 잡 객체에 log_lines가 붙습니다, 비우면 { jobs: [...], next_cursor }입니다

cancel

대기 중이거나 실행 중인 잡을 멈춥니다, 멈춘 순간까지 실행한 초는 과금됩니다

logs

로그 전체를 <out>/<id>.log에 쓰고 파일 경로, 바이트, sha256, failure_summary, 마지막 40줄(tail)을 돌려줍니다, 로그 본문 전체는 응답에 넣지 않습니다

list_runners

인자 없음, 러너 목록을 돌려줍니다: id, chip, vcpu, ram_gb, status(available 또는 coming_soon), rate_micro_usd_per_min과 rate_per_minute_display, capacity(빈 슬롯), 에이전트는 available인 ID를 build의 runner로 넘깁니다, 지금은 macos-m4 하나이고 macos-m4-pro, macos-m4-max, macos-m6은 준비 중입니다

whoami

인수 없음, 로그인 정보(인증 종류, 키 이름과 권한, 조직, 워크스페이스)을 돌려줍니다, 키 자체는 절대 돌려주지 않습니다

credits

인수 없음, 조직 잔액을 USD로 돌려줍니다

금액은 정수 *_micro_usd(1 USD = 1,000,000)와 표시용 *_display(US$12.35)를 함께 줍니다, 결제는 어떤 도구도 하지 않습니다

usage

사용량 집계의 각 행과 합계의 amount_display를 더해 돌려줍니다

build, status, cancel이 돌려주는 잡 객체

{
  "id": "job_Ab12Cd34",
  "status": "succeeded",
  "queued_reason": null,
  "end_reason": "succeeded",
  "exit_code": 0,
  "created_at": "2026-10-11T03:00:00.000Z",
  "started_at": "2026-10-11T03:00:40.000Z",
  "ended_at": "2026-10-11T03:02:45.000Z",
  "run_seconds": 125,
  "billed_minutes": 3,
  "amount_micro_usd": 82500,
  "amount_display": "$0.0825",
  "rate_per_minute_display": "US$0.0396"
}

도구 오류는 isError: true와 error 객체로 옵니다, 프로토콜 오류는 JSON-RPC error입니다(없는 도구는 -32602)

잔액 오류 예

{"error":{"code":"insufficient_credit","message":"Available balance is below one minute at the current rate","retryable":false,"retry_after_s":null,"user_message":"잔액이 부족해 잡을 시작하지 않았습니다 (사용 가능 US$0.01, 1분 요금 US$0.04), 충전: https://xenoci.com/console/billing","topup_url":"https://xenoci.com/console/billing","next_action":{"show_user":"https://xenoci.com/console/billing","note":"A person tops up in the console, never pay"}}}

응답과 진행 알림에 섞인 키 문자열은 [REDACTED]로 가립니다

연결 오류는 error.code로 봅니다

콘솔에서 설정하는 기능

xenocast에는 잡 환경 변수 입력이 없습니다, 잡 환경 변수는 빌드 스크립트 안에서 export NAME=value로 설정합니다, 비밀 값은 GitHub Actions secrets에서 스크립트 환경으로 전달하고 출력하지 않습니다

레시피는 콘솔 레시피에서 확인하고 배치의 만들기 모달에서 골라 실행합니다, xenocast에는 레시피 옵션이 없으므로 레시피 명령을 빌드 스크립트에 작성합니다

배치, 레시피, 파일 목록과 관리, 환경 목록, IP 허용 목록, 키 관리, 지출 한도는 각각 콘솔 배치, 레시피, 파일, 환경, API 키, 설정 화면에서 다룹니다, xenocast에는 이 기능을 위한 별도 명령이 없습니다, 충전은 콘솔 설정 → 결제, CSV 내보내기는 콘솔 사용량에서 합니다

종료 코드

잔액과 한도 메시지

종료 코드 3일 때 표준 오류에 한국어 한 줄과 충전 링크가 나옵니다

--json에서는 {"error":{"code":"insufficient_credit","message":"<한국어 한 줄>","retryable":false,"topup_url":"…","next_action":"…"}} 형식입니다

다음 단계

• 에이전트 규칙: 서버가 에이전트에게 주는 안내와 지켜야 할 규칙
• 결과물 내려받기: --artifacts와 artifacts --out
• 사용량 확인: usage와 CSV