Skip to main content
xkat-cli is the command-line package for xkat. One command (xkat) provides two tools — do not mix them up:

Download page

Desktop apps and xkat-cli install on xkat.space/download

View on npm

xkat-cli on the npm registry

​
Install

Keeping up to date. xkat-cli checks once a day whether a newer version is on npm and prints a one-line notice — it never updates itself. Update with npm install -g xkat-cli@latest (or just run npx xkat-cli@latest up). To turn the check off, set XKAT_NO_UPDATE_CHECK=1.
Requirements: Node.js 18+ (global install). For OS-specific host setup, see Local Environment Setup. The xkat Desktop app can also run the same commands from the Tools menu (uses the xkat-cli bundled with the app). You still need Lab tools prepared once via xkat-cli lab install (or Tools → Lab: Install).

​
1) Agent — local bridge

By default, the Dynamic Workspace 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

Local shell bridge

Web IDE terminal ↔ native shell (PTY) on this PC, with your user permissions.

Real-time file sync

Watches your working directory and syncs changes to the web dashboard.

Localhost only

Listens on 127.0.0.1:38000–38050 and checks request origin.

Background process

xkat-cli up starts the agent and returns immediately.

​
Commands

Or without a global install:

​
Quickstart

1

Start the agent

2

Open the workspace

In the browser, use lessons that run on My computer / local bridge.
3

Stop when done

​
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.
  • Run in Windows Host Terminal: The agent bridges with your Windows host browser. Run npx xkat-cli@latest up in Windows PowerShell/CMD, not inside WSL.
  • PermissionDenied (10013) Error: Occurs when Hyper-V/WSL2 (winnat) reserves port 38000–38050. Run net stop winnat followed by net start winnat in Administrator PowerShell to release port 38000–38050.

​
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, run as a container by Podman. You do not set up Podman, VirtualBox or Hyper-V yourself — xkat-cli lab install does it, and after that you only use xkat-cli lab commands. Courses that install an operating system (Ubuntu, Fedora, openSUSE…) run a real virtual machine inside that container, so you can watch the installer as you would on your own computer.

​
What it does

Isolated Ubuntu

Fixed Ubuntu 24.04 LTS cloud image — consistent across Windows, macOS, and Linux.

One-time prepare

xkat-cli lab install sets up Lab tools (may ask for admin permission).

Simple lifecycle

up · shell · stop · delete — no hypervisor UI to learn.

Clean finish

xkat-cli lab delete removes the containers; your saved work stays. To free the disk too, use xkat-cli lab purge.

​
Commands

​
Typical lecture flow

1

Prepare once

Accept admin prompts if asked. You are not configuring a VM by hand.
2

Start Lab

First run may download Ubuntu (progress is shown in the terminal).
3

Follow the lecture

4

When finished

​
Agent vs Lab (do not mix)

​
Desktop app

Install the desktop app from Download. Installers are versioned (…/desktop/v{version}/…) so the file matches the version on the page. The app bundles xkat-cli, so you do not need npm install to use it from the app. In the desktop title bar, Tools runs the same Agent / Lab commands against that bundled copy. Interactive Lab: Open Shell opens a system terminal. A newer app brings a newer bundled xkat-cli; a copy you installed from npm is updated separately. Desktop login happens in the system browser; when it finishes, the app signs in automatically (127.0.0.1 loopback redirect, authorization code + PKCE).

​
How this relates to the cloud workspace

The browser Dynamic Workspace is the same; only where code runs changes.

​
More