Documentation
KAIRO Operator Guide
Complete reference for every KAIRO page, workflow, and feature—from account setup and server fleet management to TESS chat deployments, GitHub auto-deploy, billing, and kairo-agent pairing. This documentation is public, indexable, and optimised for search engines and AI assistants.
Start here
Getting Started
- IntroductionOverview of KAIRO — an AI control plane for deployment automation, server orchestration, and infrastructure operations via TESS chat.
- What is KAIRO?KAIRO is your AI control plane for real servers—deployment automation, orchestration, encrypted credentials, and fleet visibility.
- What is TESS?TESS is KAIRO's AI assistant for server chat—streaming answers, live remote commands, deployment workflows, and contextual quick replies.
- Quick StartStep-by-step guide: create a KAIRO account, add your first server, open TESS chat, and run your first deployment.
- GlossaryDefinitions of KAIRO terms: TESS, kairo-agent, deploy profile, token quota, mutation approval, transport, and more.
Account & Access
- Sign UpCreate a new KAIRO account with email and password, accept policies, and access the dashboard.
- Sign InSign in to KAIRO with email/password, Google, or GitHub OAuth. Sessions use secure httpOnly cookies.
- Forgot PasswordRequest a one-time password (OTP) by email to reset your KAIRO account password.
- Reset PasswordSet a new password using email and OTP from the forgot-password flow.
- Accept Team InviteJoin a KAIRO team via invitation link—set password, accept invite, and access shared servers.
- OAuth Sign-InGoogle and GitHub OAuth flows for KAIRO login and GitHub repository connection (separate purposes).
Dashboard
- Dashboard OverviewKAIRO dashboard home at /dashboard — token usage charts, deployment stats, server health, and subscription summary.
- Dashboard NavigationSidebar, mobile bottom nav, and route highlighting for KAIRO dashboard—Servers, TESS Chats, Logs, Settings, and more.
- Token AnalyticsUnderstand KAIRO token usage charts on the dashboard—monthly filters, per-server breakdown, and billing cycle alignment.
Servers
- Fleet OverviewManage your server fleet at /dashboard/servers—connection status, agent health, and quick actions.
- Add SSH ServerAdd a server via SSH—host, port, username, password or private key (.pem, .ppk supported).
- Add Agent ServerPair kairo-agent via 6-character code—outbound HTTPS/WSS only, no inbound ports required.
- Verify ReadinessRun connectivity and deploy-readiness checks on SSH or agent servers before production chat.
- Edit & Delete ServersUpdate server metadata and credentials or remove a server from your KAIRO fleet.
- Server CredentialsManage encrypted SSH credentials and GitHub deploy keys stored per server in KAIRO.
TESS Chat
- TESS Chats HubPick a server to open TESS chat at /chats—per-server token spend and fleet totals.
- Per-Server ChatCore TESS experience at /dashboard/servers/[id]/chat—isolated context, insights panel, and Socket.io streaming.
- Model SelectorChoose enabled LLM models from GET /chat/models—plan assignments and provider routing apply.
- Composer & SendingChat input behaviour—Enter to send, Shift+Enter for newline, disabled state during streaming.
- Thinking & StreamingInline reasoning during active turns—ChatThinkingBlock separates thinking from final answers.
- Quick RepliesBackend-driven suggestion chips under assistant messages—click to auto-send contextual replies.
- Mutation ApprovalApprove Yes or Read-only before TESS runs install/write commands—persist alwaysApprove per server.
- Live TerminalStream remote command stdout/stderr in-chat via commandLive chunks and ChatLiveTerminal.
- Server Insights — HealthHealth tab: connectivity, GitHub, deploy-ready checks, live CPU/RAM/disk polling ~10s.
- Server Insights — Git ReposGit repos tab: integrations, auto-deploy toggles, deploy profile editor, manual redeploy.
- Deploy via ChatEnd-to-end deployment through TESS—clone, analyse, runtime pick, install approval, verify live.
GitHub Integration
- Connect GitHubLink GitHub account via OAuth popup in Settings for repo access and deployments.
- Deploy KeysSSH deploy keys for git clone on servers—auto-generated or GitHub App github.deploy_key.install on agents.
- Auto-DeployGit push triggers deploy via GitHub App webhook or legacy per-repo hooks.
- Deploy ProfileConfigure deployPath, pullCommands, preDeployCommands, restartCommands, pm2AppName for git_integrations.
Deployments & Logs
Objectives
Billing & Usage
- Token UsageMonitor KAIRO token consumption at /usage—quota, bonus tokens, and billing cycle reset.
- Plans & SubscriptionSubscribe to Starter, Pro, or Teams—INR pricing via Stripe or Cashfree (BILLING_PROVIDER).
- Top-Up TokensPurchase bonus tokens when on active plan—₹100–₹10,000 at 10 tokens per rupee.
- Checkout FlowStripe/Cashfree checkout return pages at /billing/success and /billing/cancel.
Settings
- Account SettingsProfile, avatar, phone, password at /settings?tab=account.
- Team SettingsInvite members, revoke invites, remove members—owner/admin at /settings?tab=team.
- Billing SettingsManage subscription, portal, cancel, top-up at /settings?tab=billing.
- GitHub SettingsConnect GitHub and browse accessible repos at /settings?tab=github.
- NotificationsNotification preferences at /settings?tab=notifications.
- AppearanceTheme and display preferences at /settings?tab=appearance.
kairo-agent
- kairo-agent OverviewOutbound-only Go agent for hosts—pairing, systemd, NoNewPrivileges execution model.
- Pairing Flow6-character code pairing—POST /agent/pairing/start and dashboard entry.
- Install InstructionsPer-arch amd64/arm64 install commands with sudo for initial host setup.
- Register PageApprove pairing at /register—link agent to server with preview of host/OS/arch.
