Website · Documentation · NPM Registry · Changelog

⚡ Requirements

• Node.js >= 20
• Platforms: Linux (x64, arm64, arm), macOS (x64, arm64), Windows (x64)

📦 Installation

npm install -g @katachi-live/agent

The installer automatically downloads a pinned, SHA256-verified cloudflared binary for your platform. To skip this (CI, Docker, or if you have cloudflared in PATH):

CLOUDFLARED_SKIP=1 npm install -g @katachi-live/agent

🚀 Quick Start

katachi start

On first run, you'll be guided through device-flow authentication:

First-time setup detected!
Please visit: https://katachi.live/device
Enter code: ABCD-1234
✓ Agent registered successfully
✓ Tunnel established: agent-abc123.katachi.live

🧠 AI Providers

The agent supports multiple AI providers with layered authentication:

1. OAuth (Default): Use native CLI login (e.g. gemini login)
2. API Keys (Override): Set via environment variables or the katachi.live settings UI
3. Keyring (Web UI): Enter API keys in the web interface — stored securely in your OS keyring

⌨️ Commands

| Command | Description | |---------|-------------| | katachi start | Start the agent daemon | | katachi stop | Stop the agent daemon | | katachi restart | Restart the agent daemon | | katachi status | Check daemon status and tunnel info | | katachi logs | View agent logs (-f to follow) | | katachi version | Show version information | | katachi unregister | Deregister agent and remove credentials |

⚙️ Configuration

All options can also be set via environment variables.

| Flag | Env Variable | Default | Description | |------|-------------|---------|-------------| | --port <port> | KATACHI_PORT | 7676 | HTTP server port | | --debug | KATACHI_DEBUG=1 | — | Enable debug logging | | --home <dir> | KATACHI_HOME | ~/.katachi | Agent data directory | | — | KATACHI_API_URL | https://api.katachi.live | Backend API URL |

🔌 Unregistering

# Normal: deregisters from backend, then removes local credentials
katachi unregister

# Force: removes local credentials even if backend is unreachable
katachi unregister --force

🚑 Troubleshooting

cloudflared download failed during install:

npm rebuild @katachi-live/agent

cloudflared not found at runtime:

# Install manually
# macOS:
brew install cloudflared
# Windows:
winget install Cloudflare.cloudflared
# Linux:
# See https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/

📜 License

Proprietary — see LICENSE for details.