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

> Bridge the browser to your PC (Agent) or use an isolated Ubuntu practice environment (Lab).

**xkat-cli** is the command-line package for xkat. One command (`xkat`) provides
**two tools** — do not mix them up:

| Tool      | Commands                      | What it is for                                              |
| :-------- | :---------------------------- | :---------------------------------------------------------- |
| **Agent** | `xkat up` · `status` · `down` | Connect the browser workspace to **this computer**          |
| **Lab**   | `xkat lab …`                  | Isolated **Ubuntu 24.04** practice environment for lectures |

<CardGroup cols={2}>
  <Card title="Download page" icon="download" href="https://xkat.space/en/download">
    Desktop apps and xkat-cli install on [xkat.space/download](https://xkat.space/en/download)
  </Card>

  <Card title="View on npm" icon="npm" href="https://www.npmjs.com/package/xkat-cli">
    xkat-cli on the npm registry
  </Card>
</CardGroup>

***

## Install

```bash theme={null}
# One-off (no global install)
npx xkat-cli@latest

# Or install globally
npm install -g xkat-cli
```

Requirements: **Node.js 18+** (global install). For OS-specific host setup, see
[Local Environment Setup](/en/learn/workspace/local-setup).

The **xkat Desktop** app can also run the same commands from the **Tools** menu
(uses a local or monorepo agent binary). You still need Lab tools prepared once
via `xkat lab install` (or **Tools → Lab: Install**).

***

## 1) Agent — local bridge

By default, the [Dynamic Workspace](/en/learn/workspace/overview) can run on
xkat cloud. With the **Agent**, the browser connects to **your machine** instead
— local shell, your tools, real-time file sync.

### What it does

<CardGroup cols={2}>
  <Card title="Local shell bridge" icon="terminal">
    Web IDE terminal ↔ native shell (PTY) on this PC, with your user permissions.
  </Card>

  <Card title="Real-time file sync" icon="arrows-rotate">
    Watches your working directory and syncs changes to the web dashboard.
  </Card>

  <Card title="Localhost only" icon="shield-check">
    Listens on <code>127.0.0.1:10022</code> and checks request origin.
  </Card>

  <Card title="Background process" icon="bolt">
    <code>xkat up</code> starts the agent and returns immediately.
  </Card>
</CardGroup>

### Commands

```bash theme={null}
xkat up        # start agent (alias: start)
xkat status    # is the agent running?
xkat down      # stop agent (alias: stop)
```

Or without a global install:

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

### Quickstart

<Steps>
  <Step title="Start the agent">
    ```bash theme={null}
    npx xkat-cli@latest up
    ```
  </Step>

  <Step title="Open the workspace">
    In the browser, use lessons that run on **My computer** / local bridge.
  </Step>

  <Step title="Stop when done">
    ```bash theme={null}
    xkat down
    ```
  </Step>
</Steps>

### Security

* **Localhost only** — the port is not exposed to the network.
* **Origin verification** — only official xkat domains can connect.
* **Audit log** — `~/.xkat/agent.log`

Best for: CLI tools on your host (e.g. bash, vercel-cli), using your own files
and environment.

***

## 2) Lab — Ubuntu practice environment

Some courses (Linux, networking, agents such as Hermes) should **not** run
directly on your host. **Lab** gives every learner the same **Ubuntu 24.04**
environment. You do **not** need to configure VirtualBox, Hyper-V, or similar
yourself — use only `xkat lab` commands.

### What it does

<CardGroup cols={2}>
  <Card title="Isolated Ubuntu" icon="server">
    Fixed Ubuntu 24.04 LTS cloud image — consistent across Windows, macOS, and Linux.
  </Card>

  <Card title="One-time prepare" icon="download">
    <code>xkat lab install</code> sets up Lab tools (may ask for admin permission).
  </Card>

  <Card title="Simple lifecycle" icon="play">
    up · shell · stop · delete — no hypervisor UI to learn.
  </Card>

  <Card title="Clean finish" icon="trash">
    <code>xkat lab delete</code> removes the practice environment and frees disk.
  </Card>
</CardGroup>

### Commands

```bash theme={null}
xkat lab install   # once per computer (user consent / admin if needed)
xkat lab up        # create / start Lab
xkat lab shell     # open a shell inside Lab (starts Lab if needed)
xkat lab stop      # stop Lab (keeps data)
xkat lab delete    # remove Lab completely
xkat lab status    # is Lab ready?
xkat lab doctor    # setup checks + fix hints
xkat lab reset     # delete and create a fresh Lab
```

### Typical lecture flow

<Steps>
  <Step title="Prepare once">
    ```bash theme={null}
    xkat lab install
    ```

    Accept admin prompts if asked. You are not configuring a VM by hand.
  </Step>

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

    First run may download Ubuntu (progress is shown in the terminal).
  </Step>

  <Step title="Follow the lecture">
    ```bash theme={null}
    xkat lab shell
    ```
  </Step>

  <Step title="When finished">
    ```bash theme={null}
    xkat lab stop      # pause
    # or
    xkat lab delete    # remove leftovers
    ```
  </Step>
</Steps>

### Agent vs Lab (do not mix)

| Check                        | Command           | Meaning |
| :--------------------------- | :---------------- | :------ |
| Is the **local bridge** up?  | `xkat status`     | Agent   |
| Is the **Ubuntu Lab** ready? | `xkat lab status` | Lab     |

***

## Desktop app

Install the desktop app from [Download](https://xkat.space/en/download). Installers
are versioned (`…/desktop/v{version}/…`) so the file matches the version on the page.

In the desktop title bar, **Tools** can run the same Agent / Lab commands against
a local xkat-cli binary (monorepo build or future bundled binary). Interactive
**Lab: Open Shell** opens a system terminal.

Desktop login uses the system browser → `auth-bridge` → `xkat://` deep link, then
the app opens `https://xkat.space/api/auth/desktop/complete` (not localhost).

***

## How this relates to the cloud workspace

|          | Cloud workspace                              | Agent (this PC)    | Lab (Ubuntu)                 |
| :------- | :------------------------------------------- | :----------------- | :--------------------------- |
| Setup    | [Zero-setup](/en/learn/workspace/zero-setup) | `xkat up`          | `xkat lab install` then `up` |
| Runs on  | xkat cloud                                   | Your host OS       | Isolated Ubuntu VM           |
| Best for | Quick start                                  | Host tools & files | Linux / net / agent courses  |

The browser [Dynamic Workspace](/en/learn/workspace/overview) is the same; only
**where code runs** changes.

***

## More

* [Download desktop apps & CLI](https://xkat.space/en/download)
* [Local Environment Setup](/en/learn/workspace/local-setup)
* [npm: xkat-cli](https://www.npmjs.com/package/xkat-cli)