> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xkat.space/llms.txt
> Use this file to discover all available pages before exploring further.

# xkat-cli: Agent와 Lab

> 브라우저를 PC에 연결(Agent)하거나, 강의용 격리 Ubuntu 실습 환경(Lab)을 사용합니다.

**xkat-cli**는 xkat 명령줄 패키지입니다. 명령 `xkat` 하나에 **도구 두 가지**가
들어 있습니다. 서로 섞지 마세요.

| 도구        | 명령                            | 용도                            |
| :-------- | :---------------------------- | :---------------------------- |
| **Agent** | `xkat up` · `status` · `down` | 브라우저 워크스페이스를 **이 컴퓨터**에 연결    |
| **Lab**   | `xkat lab …`                  | 강의용 **Ubuntu 24.04** 격리 실습 환경 |

<CardGroup cols={2}>
  <Card title="다운로드 페이지" icon="download" href="https://xkat.space/ko/download">
    데스크톱 앱과 xkat-cli 설치 — [xkat.space/download](https://xkat.space/ko/download)
  </Card>

  <Card title="npm에서 보기" icon="npm" href="https://www.npmjs.com/package/xkat-cli">
    npm 레지스트리의 xkat-cli
  </Card>
</CardGroup>

***

## 설치

```bash theme={null}
# 전역 설치 없이 한 번 실행
npx xkat-cli@latest

# 또는 전역 설치
npm install -g xkat-cli
```

요구 사항: **Node.js 18+** (전역 설치 시). OS별 호스트 준비는
[로컬 환경 설정](/ko/learn/workspace/local-setup)을 참고하세요.

**xkat 데스크톱** 앱의 **Tools** 메뉴에서도 같은 명령을 실행할 수 있습니다
(로컬/모노레포 에이전트 바이너리). Lab은 한 번 `xkat lab install`(또는
**Tools → Lab: Install**)로 준비해야 합니다.

***

## 1) Agent — 로컬 브릿지

기본적으로 [다이나믹 워크스페이스](/ko/learn/workspace/overview)는 클라우드에서도
동작할 수 있습니다. **Agent**를 쓰면 브라우저가 **내 PC**에 연결되어 로컬 셸·도구·
파일 실시간 동기화를 씁니다.

### 무엇을 하나

<CardGroup cols={2}>
  <Card title="로컬 셸 브릿지" icon="terminal">
    웹 IDE 터미널 ↔ 이 PC 네이티브 셸(PTY), 내 사용자 권한.
  </Card>

  <Card title="실시간 파일 동기화" icon="arrows-rotate">
    작업 디렉터리 변경을 웹 대시보드와 즉시 동기화.
  </Card>

  <Card title="localhost 전용" icon="shield-check">
    <code>127.0.0.1:10022</code>에만 바인딩하고 요청 출처를 검증.
  </Card>

  <Card title="백그라운드 실행" icon="bolt">
    <code>xkat up</code>으로 시작하고 터미널은 바로 비워 둡니다.
  </Card>
</CardGroup>

### 명령

```bash theme={null}
xkat up        # 에이전트 시작 (별칭: start)
xkat status    # 실행 중인지 확인
xkat down      # 에이전트 중지 (별칭: stop)
```

전역 설치 없이:

```bash theme={null}
npx xkat-cli@latest up
npx xkat-cli@latest status
npx xkat-cli@latest down
```

### 퀵스타트

<Steps>
  <Step title="에이전트 시작">
    ```bash theme={null}
    npx xkat-cli@latest up
    ```
  </Step>

  <Step title="워크스페이스 열기">
    브라우저에서 **내 컴퓨터** / 로컬 브릿지를 쓰는 강의를 실행합니다.
  </Step>

  <Step title="끝나면 중지">
    ```bash theme={null}
    xkat down
    ```
  </Step>
</Steps>

### 보안

* **로컬호스트 전용** — 네트워크에 포트를 열지 않습니다.
* **출처 검증** — 공식 xkat 도메인만 연결 가능.
* **감사 로그** — `~/.xkat/agent.log`

적합한 경우: 호스트의 CLI 도구(bash, vercel-cli 등), 내 파일·환경 그대로 사용.

***

## 2) Lab — Ubuntu 실습 환경

리눅스·네트워크·Hermes 같은 에이전트 강의는 **호스트에 직접 돌리기 부담**될 수
있습니다. **Lab**은 학습자마다 같은 **Ubuntu 24.04**를 줍니다. VirtualBox /
Hyper-V를 직접 설정할 필요 없이 `xkat lab` 명령만 쓰면 됩니다.

### 무엇을 하나

<CardGroup cols={2}>
  <Card title="격리된 Ubuntu" icon="server">
    Ubuntu 24.04 LTS 클라우드 이미지 — Windows·macOS·Linux에서 동일.
  </Card>

  <Card title="한 번 준비" icon="download">
    <code>xkat lab install</code>로 Lab 도구 설치 (관리자 권한 요청 가능).
  </Card>

  <Card title="단순한 수명 주기" icon="play">
    up · shell · stop · delete — 하이퍼바이저 UI를 배울 필요 없음.
  </Card>

  <Card title="깔끔한 종료" icon="trash">
    <code>xkat lab delete</code>로 실습 환경을 지우고 디스크를 비웁니다.
  </Card>
</CardGroup>

### 명령

```bash theme={null}
xkat lab install   # PC당 한 번 (동의·관리자 권한 가능)
xkat lab up        # Lab 생성/기동
xkat lab shell     # Lab 안 셸 (꺼져 있으면 기동)
xkat lab stop      # 중지 (데이터 유지)
xkat lab delete    # Lab 완전 삭제
xkat lab status    # 준비 상태
xkat lab doctor    # 진단·안내
xkat lab reset     # 지우고 새로 생성
```

### 전형적인 강의 흐름

<Steps>
  <Step title="한 번 준비">
    ```bash theme={null}
    xkat lab install
    ```

    관리자 프롬프트가 나오면 수락합니다. VM을 손으로 설정하지 않습니다.
  </Step>

  <Step title="Lab 시작">
    ```bash theme={null}
    xkat lab up
    ```

    첫 실행은 Ubuntu 다운로드가 있을 수 있으며, 진행 상황이 터미널에 표시됩니다.
  </Step>

  <Step title="강의 따라하기">
    ```bash theme={null}
    xkat lab shell
    ```
  </Step>

  <Step title="끝나면">
    ```bash theme={null}
    xkat lab stop      # 일시 중지
    # 또는
    xkat lab delete    # 남은 환경 제거
    ```
  </Step>
</Steps>

### Agent vs Lab (혼동 주의)

| 확인                    | 명령                | 의미    |
| :-------------------- | :---------------- | :---- |
| **로컬 브릿지**가 떴나?       | `xkat status`     | Agent |
| **Ubuntu Lab**이 준비됐나? | `xkat lab status` | Lab   |

***

## 데스크톱 앱

[다운로드](https://xkat.space/ko/download)에서 설치합니다. 설치 파일은
`…/desktop/v{버전}/…` 처럼 **표시 버전과 같은 경로**로 제공됩니다.

타이틀바 **Tools** 메뉴에서 Agent / Lab 명령을 실행할 수 있습니다.
**Lab: Open Shell** 은 시스템 터미널을 엽니다.

데스크톱 로그인은 시스템 브라우저 → `auth-bridge` → `xkat://` 딥링크 후
앱이 `https://xkat.space/api/auth/desktop/complete` 로 이동합니다 (localhost 아님).

***

## 클라우드 워크스페이스와의 관계

|        | 클라우드                                  | Agent (이 PC) | Lab (Ubuntu)              |
| :----- | :------------------------------------ | :----------- | :------------------------ |
| 설정     | [무설치](/ko/learn/workspace/zero-setup) | `xkat up`    | `xkat lab install` 후 `up` |
| 실행 위치  | xkat 클라우드                             | 호스트 OS       | 격리 Ubuntu VM              |
| 적합한 경우 | 빠른 시작                                 | 호스트 도구·파일    | 리눅스/네트워크/에이전트 강의          |

브라우저 [다이나믹 워크스페이스](/ko/learn/workspace/overview) 경험은 같고,
**코드가 어디서 도는지**만 달라집니다.

***

## 더 보기

* [데스크톱 앱·CLI 다운로드](https://xkat.space/ko/download)
* [로컬 환경 설정](/ko/learn/workspace/local-setup)
* [npm: xkat-cli](https://www.npmjs.com/package/xkat-cli)