Installation

Install the Agent

npm

npm install -g @katachi/agent

Verify

katachi version

The installer automatically downloads a pinned, SHA256-verified cloudflared binary for your platform. No additional setup is needed.

Skipping Cloudflared Download

In CI/CD pipelines or Docker containers where you already have cloudflared installed:

CLOUDFLARED_SKIP=1 npm install -g @katachi/agent

The agent will fall back to using cloudflared from your system PATH.

System Requirements

Requirement	Minimum
Node.js	v18.0.0+
OS	Linux, macOS, or Windows
Architecture	x64, arm64, or arm (Linux only)
Network	Outbound HTTPS (port 443)
Git	v2.38.0+ (required for advanced merge-tree workflows)

What Gets Installed

• katachi CLI — The command-line tool to manage the agent daemon
• cloudflared — Cloudflare’s tunnel binary (downloaded automatically)
• Agent runtime — The TypeScript daemon that connects to Katachi

All agent data is stored in ~/.katachi/ (or the directory specified by --home).

Updating

npm update -g @katachi/agent

This will download the latest agent and update cloudflared if a new version is pinned.

Uninstalling

# First unregister to clean up the tunnel
katachi unregister

# Then remove the package
npm uninstall -g @katachi/agent

# Optionally remove agent data
# Linux/macOS:
rm -rf ~/.katachi
# Windows:
rmdir /s %USERPROFILE%\.katachi