Configuration

Agent Configuration

The Katachi agent can be configured through CLI flags, environment variables, or both.

Startup Options

# Custom port (default: 7676)
katachi start --port 3001

# Debug logging
katachi start --debug

# Custom data directory (default: ~/.katachi)
katachi start --home /path/to/data

Environment Variables

Variable	Default	Description
KATACHI_PORT	7676	HTTP server port
KATACHI_HOME	~/.katachi	Agent data directory
KATACHI_DEBUG	—	Set to true for debug logging
KATACHI_API_URL	https://api.katachi.live	Backend API URL
CLOUDFLARED_SKIP	—	Set to 1 to skip cloudflared download during install

CLI flags take priority over environment variables.

Data Directory

The agent stores all its data in ~/.katachi/ (or the path specified by --home):

~/.katachi/
├── credentials.json.enc    # Encrypted tunnel credentials
├── katachi.db              # Local SQLite database (sessions, history)
└── logs/                   # Daily-rotated log files
    ├── agent-2026-03-17.log
    └── agent-2026-03-16.log

Credentials

Tunnel credentials are encrypted at rest and tied to your device’s hardware fingerprint. They cannot be copied to another machine.

Logs

Logs are automatically rotated daily. Use katachi logs to view them:

# View recent logs
katachi logs

# Follow logs in real-time
katachi logs -f

Firewall & Network

The agent only needs outbound HTTPS access (port 443) to:

• api.katachi.live — Backend API
• *.cfargotunnel.com — Cloudflare tunnel infrastructure
• github.com — Cloudflared binary downloads (during install only)

No inbound ports need to be opened.