# XenoCI 설정 안내 (AI 에이전트용)

이 문서는 사람이 "XenoCI 설정 안내를 읽고 따라 해 줘: https://xenoci.com/agent-setup" 이라고 맡겼을 때 AI 에이전트가 따라 하는 절차입니다, XenoCI는 Mac mini M4의 깨끗한 macOS VM에서 iOS와 macOS 빌드, 테스트를 돌려 주는 러너이고, 에이전트는 `xenocast` CLI와 MCP 도구로 씁니다

사람이 미리 해 둔 일은 세 가지입니다, 콘솔에서 크레딧을 충전했고, API 키를 만들었고, 그 키를 자기 터미널에 넣었습니다 (`xenocast login` 또는 `XENOCI_API_KEY` 환경 변수), 그래서 에이전트는 키 값을 볼 일이 없습니다

## 지켜야 할 규칙

- 키를 대화로 받지 마세요, 키가 없으면 사람에게 터미널에서 `xenocast login`을 실행해 달라고 요청합니다
- 사람이 대화에 키를 붙여 넣었다면 그 키를 쓰지 말고, 콘솔 **API 키**에서 그 키를 폐기하고 새 키를 터미널에 넣어 달라고 안내합니다
- 키를 파일, 커밋, 로그, 답변, 명령줄 인자 어디에도 적지 마세요, `xenocast`는 저장된 키나 `XENOCI_API_KEY`를 스스로 읽습니다
- 잡 하나는 돈입니다, 실행한 초만큼 (최소 1분) 잔액에서 빠집니다, 같은 잡을 되풀이해 보내지 말고, 필요 없어진 잡은 바로 취소합니다
- 결제는 사람만 합니다, 잔액이 부족하다는 답이 오면 그 안에 든 충전 링크를 사람에게 보여 주고 기다립니다

## 1 설치

`xenocast`가 이미 있는지 확인합니다

```bash
xenocast --version
```

없으면 설치합니다, 설치 스크립트는 `~/.local/bin/xenocast`에 실행 파일을 놓습니다

```bash title="macOS, Linux"
curl -fsSL https://github.com/Xeno-CI/xenocast/releases/latest/download/install.sh | sh
```

```powershell title="Windows (PowerShell)"
irm https://github.com/Xeno-CI/xenocast/releases/latest/download/install.ps1 | iex
```

설치 뒤 `xenocast`를 찾지 못하면 `~/.local/bin`을 `PATH`에 더하거나 전체 경로로 실행합니다

## 2 키 확인

```bash
xenocast config show --json
```

`api_key`가 `null`이 아니면 다음 단계로 갑니다, `null`이면 여기서 멈추고 사람에게 이렇게 요청합니다

```text
XenoCI API 키가 이 컴퓨터에 아직 없습니다. 터미널에서 xenocast login 을 실행하고 콘솔에서 만든 키를 붙여 넣어 주세요, 입력한 키는 화면에 보이지 않고 이 컴퓨터에 암호화해 저장됩니다. 다 되면 알려 주세요
```

사람이 끝났다고 하면 같은 명령으로 다시 확인합니다, 키 값을 대신 받아 넣지 않습니다

## 3 도구 등록

```bash
xenocast setup --no-tui
```

키를 확인하고, 이 컴퓨터에 설치된 AI 에이전트(Claude Code, Codex, Cursor, OpenCode, OmO)에 MCP 서버 `xenocast mcp`를 등록합니다, 에이전트 설정 파일에는 실행 명령만 들어가고 키는 들어가지 않습니다, 마지막 줄이 `XenoCast 준비 완료`로 시작하면 끝입니다

MCP 도구(`build`, `status`, `cancel`, `logs`, `whoami`, `credits`, `usage`)는 에이전트를 새 세션으로 시작하면 보입니다, 지금 세션에서는 아래 CLI 명령을 그대로 쓰면 됩니다

## 4 연결 확인

```bash
xenocast whoami
```

조직, 워크스페이스, 키 권한, 잔액이 나옵니다, 권한이 `read`이면 빌드할 수 없으니 사람에게 실행과 조회 권한의 키를 새로 만들어 `xenocast login`으로 넣어 달라고 요청합니다, 여기까지 끝나면 사람에게 조직, 워크스페이스, 잔액을 한 줄로 알리고 준비됐다고 답합니다

## 5 첫 빌드

프로젝트 폴더에서 빌드를 시작하는 스크립트(예: `ci.sh`)를 정하고 보냅니다, 현재 폴더가 올라가고, 러너의 Xcode에서 스크립트가 실행되고, 로그가 끝날 때까지 흐릅니다, 명령의 종료 코드는 스크립트의 종료 코드와 같습니다

```bash
xenocast build --script ./ci.sh --xcode 27.0 --artifacts 'build/*.ipa'
```

끝나면 마지막 줄에 실행 시간과 금액, 남은 잔액이 나옵니다

```text
잡 job_4kQ9vXr2Lm7TbN3sWp8d succeeded (종료 코드 0), 실행 2분 5초, 금액 US$0.08, 남은 잔액 US$19.92
```

- `--xcode`는 `27.0`이나 `26.6`, 비워 두면 `27.0`입니다
- 공개 git 저장소는 `--repo owner/name --ref main`으로 보냅니다
- 오래 걸리는 잡은 `--no-wait`로 보내고 `xenocast wait job_...`로 기다립니다

## 6 결과 확인

```bash
xenocast status job_...
xenocast logs job_... --failure
xenocast artifacts job_... --out ./out
```

실패하면 `logs --failure`로 실패한 줄을 읽고, 고친 뒤 다시 보냅니다, 모든 명령에 `--json`을 붙이면 기계가 읽는 JSON 한 개만 나옵니다

## 종료 코드

| 코드 | 뜻 | 할 일 |
|---|---|---|
| 0 | 성공 | 결과를 사람에게 알립니다 |
| 2 | 사용법이나 키 오류 | 키 오류면 2단계로 돌아가 사람에게 `xenocast login`을 요청합니다 |
| 3 | 잔액이나 한도 때문에 거절되거나 멈춤 | 출력의 충전 링크를 사람에게 보여 주고 기다립니다 |
| 그 밖 | 스크립트의 종료 코드 | `logs --failure`로 원인을 읽습니다 |

자세한 내용은 https://xenoci.com/docs/quickstart 와 https://xenoci.com/docs/agents 에 있습니다