Online Auth Guide
online-auth is the gateway that unlocks the rest of Kodachi: it establishes your session, keeps it alive with a heartbeat, manages your license, and hands routing-switch the encrypted card it needs. This guide is scenario-first: authenticate, activate a license, transfer a device, recover a session.
v10.0.3 (build 75) · 21 commands · 9.2 MB · HTTPS to kodachi.cloud only, system CA
Documentation Navigation
This page is scenario-first (operational workflows, real run order, and troubleshooting). For the full autogenerated command/flag catalog, use the CLI Reference.
Binary Facts and Checksum
The full metadata table, raw signer JSON, and the current SHA-256 checksum are maintained on the generated reference page so this guide never drifts out of date. Verify a downloaded binary in one click with the browser-side tool.
Where to confirm the binary
- online-auth CLI reference, authoritative version, build, size, and SHA-256.
- File verification tool, drop the binary in and match it against the published hash, entirely in your browser.
Key Features
Authentication Management
| Feature | Description |
|---|---|
| Centralized Authentication | Single sign-on for all Kodachi security services |
| Session Persistence | Keep-alive functionality prevents unwanted disconnections |
| Access Control | Determines user privileges |
| Secure Card System | Provides encrypted routing configurations for routing-switch |
Why Online Auth is Critical
| Benefit | Description |
|---|---|
| Security Gateway | Most Kodachi binaries require authentication to unlock their full functionality |
| Routing Card Provider | Supplies encrypted configuration cards essential for routing-switch operations |
| Session Management | Maintains persistent connections for long-running security operations |
| Premium Access | Premium users get dedicated fast servers, faster updates, and priority support for the project |
TL;DR - Essential Commands
# Authenticate to unlock Kodachi features
sudo online-auth authenticate
# Authenticate with automatic keep-alive (prevents disconnection)
sudo online-auth authenticate --keep-alive
# Authenticate with auto-relogin on disconnection (includes keep-alive)
sudo online-auth authenticate --relogin
# Authenticate with explicit heartbeat and auto-relogin
sudo online-auth authenticate --keep-alive --relogin
# Check authentication status
sudo online-auth check-login
# Check if user ID is blocked
sudo online-auth check-if-blocked
# Logout when finished
sudo online-auth logout
# (Tip) For long sessions, use --relogin for automatic reconnection:
sudo online-auth authenticate --relogin
Note: Authentication commands require sudo as they manage system services.
Understanding the Card System
What is the Card?
The card is an encrypted configuration package containing personalized routing and security settings required for establishing secure connections.
# Get your encrypted card (required for routing-switch)
sudo online-auth get-card
Card Components:
| Component | Description |
|---|---|
| VPN Config | VPN server lists and routing tables |
| Certificates | Security certificates and authentication tokens |
| Encryption | Encrypted with your unique session key |
| Routing | Required by routing-switch for anonymous connections |
Note
The card output is in JSON format which you can view if needed, however routing-switch handles all the card processing automatically for connections, so you don't need to worry about the technical details.
Automatic Service Management
Online-auth automatically manages essential system services during authentication, eliminating the need for manual service startup.
Managed Services
| Service | Purpose | Automatic Action |
|---|---|---|
| Permission Guard | Fixes file permission issues | Starts daemon, monitors working directory |
| Global Launcher | Enables system-wide binary access | Deploys all dashboard binaries |
Authentication Workflow
sudo online-auth authenticate
# Automatically executes:
# 1. Start permission-guard daemon → Monitor file permissions
# 2. Deploy global-launcher → Enable binary access
# 3. Complete authentication → Unlock all features
# For auto-reconnection on session expiry:
sudo online-auth authenticate --relogin
# This automatically enables heartbeat and re-authenticates when needed
Service Behavior
| Phase | Behavior | Details |
|---|---|---|
| During Authentication | Both services start automatically | Services launch seamlessly during user login |
| During Authentication | Failures don't block authentication | Login continues even if services encounter issues |
| During Authentication | Services run with proper user context | Correct permissions and user privileges applied |
| During Logout | Services are managed appropriately | Clean shutdown and resource release |
| During Logout | Session cleanup is performed | Temporary data and tokens are cleared |
Benefits
| Benefit | Description |
|---|---|
| One Command | Everything starts with authentication |
| No Manual Steps | Services activate automatically |
| Consistent Environment | Same setup for all users |
| Reduced Errors | No forgotten services |
Manual Override
For special cases, manual control remains available:
# Custom permission-guard monitoring
sudo permission-guard watch /custom/path --scan-interval 30
# Force global-launcher redeployment (clean then deploy)
cd /opt/kodachi/dashboard/hooks && sudo ./global-launcher cleanup --yes && sudo ./global-launcher deploy
Note
Manual control is rarely needed. Authentication handles service management transparently.
Block Status Verification
Check if the current user ID has been blocked from accessing Kodachi services:
# Check if user ID is blocked
sudo online-auth check-if-blocked
# JSON output
sudo online-auth check-if-blocked --json
Purpose: Verify account standing before attempting authentication. Useful for diagnosing authentication failures.
Advanced Commands
All 21 commands across the six groups (authentication, heartbeat, license, API management, permission-guard, information), with every flag, JSON option, and debug control, are documented on the auto-generated online-auth reference. This guide covers the ones you reach for day to day; the reference is the exhaustive catalog.
Security Notes
Important Security Practices:
| Practice | Description |
|---|---|
| Credential Security | Never share session IDs or API keys |
| Session Hygiene | Always logout when finished working |
| Long Sessions | Use --relogin for automatic reconnection on session expiry |
| Persistent Sessions | Use --keep-alive to maintain heartbeat, or --relogin which includes it |
| Status Check | Check authentication status before running critical operations |
| Regular Monitoring | Monitor your login status regularly |
Performance
| Metric | Value |
|---|---|
| Authentication Time | < 500ms |
| Memory Usage | ~15MB active, < 1MB idle |
| CPU Usage | < 5% active, 0% idle |
| Heartbeat Traffic | < 1KB every 15 minutes |
Support
| Resource | Link |
|---|---|
| Website | digi77.com |
| Anonymity Verifier | kodachi.cloud |
| Discord Support | discord.gg/KEFErEx |
| GitHub | github.com/WMAL |
Scenario 1: Initial Authentication and Session Establishment
Complete authentication setup for establishing secure connections and routing operations.
# Step 1: Authenticate with auto-relogin (includes heartbeat)
sudo online-auth authenticate --relogin
# Step 2: Verify authentication status
sudo online-auth check-login
# Expected: Login status should show "authenticated"
# Step 3: Get user and session IDs
sudo online-auth get-ids
# Step 4: Check account tier (Premium features)
sudo online-auth which-group
# Step 5: Retrieve encrypted configuration card for routing-switch
sudo online-auth get-card
# Step 6: Enable routing with the card
sudo routing-switch connect wireguard
# Expected: VPN routing enabled using online-auth card
Cross-binary workflow: online-auth + routing-switch
When to run: Before establishing any secure connections. Or Automate this with workflow-manager.
Scenario 2: License Activation and Premium Feature Access
Activate a license key to unlock premium features and verify access.
# Step 1: Check current license status
sudo online-auth license-status
# Step 2: Activate premium license key
printf '%s\n' "H7KM-P2Q9-R5TW-X3YZ-A4B2" | sudo online-auth activate-license --stdin-key
# Expected: License activated with tier and feature details
# Step 3: Verify new license status and features
sudo online-auth license-status --json
# Step 4: Confirm premium group access
sudo online-auth which-group
# Expected: Account tier should show "Premium"
# Step 5: Re-authenticate to apply premium settings
sudo online-auth logout
sudo online-auth authenticate --relogin
# Step 6: Get premium configuration card
sudo online-auth get-card
# Step 7: Verify premium features in routing-switch
sudo routing-switch status
# Expected: Premium servers should be available
Cross-binary workflow: online-auth + routing-switch
When to run: After purchasing a Premium license or when upgrading tiers.
Scenario 3: Multi-Device License Management (Transfer)
Transfer license from one device to another by releasing and reactivating.
# Step 1: Check current device license status
sudo online-auth license-status --json
# Step 2: Release license from current device
sudo online-auth release-license
# Expected: License released, can be activated on new device
# Step 3: Verify license is no longer active
sudo online-auth which-group
# Expected: Should revert to free tier
# Step 4: Logout from current session
sudo online-auth logout
# Step 5: On new device, authenticate first
sudo online-auth authenticate --relogin
# Step 6: Activate license on new device
printf '%s\n' "H7KM-P2Q9-R5TW-X3YZ-A4B2" | sudo online-auth activate-license --stdin-key
# Step 7: Verify license activated on new device
sudo online-auth license-status
# Step 8: Check system security after transfer
sudo health-control security-score
Cross-binary workflow: online-auth + health-control
When to run: When moving to new hardware, reinstalling OS, or switching between systems.
Scenario 4: Permission Guard Daemon Management
Manage the permission guard daemon for file permission monitoring and correction.
# Step 1: Enable permission guard daemon during authentication
sudo online-auth authenticate --relogin
# Expected: Automatically starts permission-guard daemon
# Step 2: Verify permission guard is running
sudo online-auth permission-guard-status
# Expected: Permission guard daemon is running
# Step 3: Check for permission issues in working directory
sudo permission-guard scan
# Step 4: Monitor permission guard logs
sudo permission-guard watch --scan-interval 30
# Step 5: Disable permission guard if needed
sudo online-auth disable-permission-guard
# Step 6: Re-enable permission guard
sudo online-auth enable-permission-guard --json
# Expected: {"status": "success", "message": "Permission guard daemon enabled", "is_running": true}
# Step 7: Verify automatic fixes are working
sudo permission-guard status
Cross-binary workflow: online-auth + permission-guard
When to run: After authentication to ensure file permissions remain correct, or when troubleshooting permission issues.
Scenario 5: API Key Resync After Network Failure
Recover authentication after network disruptions or API key synchronization issues.
# Step 1: Check current network connectivity
sudo health-control net-check
# Step 2: Verify IP and network status
sudo ip-fetch fetch --json
# Step 3: Check authentication status
sudo online-auth check-login --json
# Step 4: Manually sync API key with server
sudo online-auth sync-api-key
# Expected: API key synchronized successfully
# Step 5: Re-authenticate with fresh credentials
sudo online-auth logout
sudo online-auth authenticate --relogin
# Step 6: Verify heartbeat is active
sudo online-auth check-heartbeat
# Step 7: Send test heartbeat to confirm connectivity
sudo online-auth send-heartbeat-with-retry
# Step 8: Verify all status information
sudo online-auth check-all-status --json
Cross-binary workflow: online-auth + health-control + ip-fetch
When to run: After network failures, VPN disconnections, or when authentication commands fail unexpectedly.
Scenario 6: Heartbeat Monitoring for Long-Running Operations
Maintain persistent authentication during long-running routing or security operations.
# Step 1: Authenticate with automatic heartbeat
sudo online-auth authenticate --keep-alive --relogin
# Step 2: Start heartbeat service manually (if not auto-started)
sudo online-auth start-heartbeat
# Step 3: Verify heartbeat is active
sudo online-auth check-heartbeat
# Expected: Heartbeat service is running
# Step 4: Send manual heartbeat test
sudo online-auth send-heartbeat --json
# Step 5: Start long-running routing operation
sudo routing-switch connect wireguard
# Expected: Heartbeat maintains authentication during the connection setup
# Step 6: Monitor heartbeat during operation
sudo online-auth check-heartbeat
# Step 7: After operation completes, verify session is still active
sudo online-auth check-login
# Step 8: Stop heartbeat when no longer needed
sudo online-auth stop-heartbeat
Cross-binary workflow: online-auth + routing-switch + workflow-manager
When to run: Before starting extended operations requiring authentication. Or Automate this with workflow-manager for continuous monitoring.
Related Workflows
- Routing Configuration, Requires online-auth card for VPN/Tor setup
- Permission Management, Automated daemon management through online-auth
- System Health Monitoring, Security scoring and network checks
- IP Geolocation, Network status verification for authentication troubleshooting
- Full CLI Reference: online-auth commands