Skip to content

Getting Started

Jump to bottom
Daniel Ellison edited this page Sep 3, 2026 · 1 revision

Getting Started

You've installed Kai and run the configuration wizard. What happens next depends on the client mode you chose: the Workshop browser client, Telegram, or both (see client modes).

If Kai exits immediately at startup, check the Troubleshooting page.

Your first conversation in the Workshop

  1. Open http://127.0.0.1:8080/workshop/ in a browser on the machine running Kai. A fresh workshop-only install prints your first enrollment token during setup; otherwise issue one with the workshop CLI.
  2. Name your device, paste the token, and click Open Workshop.
  3. Open your direct channel with Kai in the sidebar and send a message; anything you'd ask a coding agent. The reply streams in live, and the run inspector in the right pane shows the tool calls as they happen.

From there, Workshop Collaboration Basics covers the rest of the client.

Your first conversation on Telegram

If your install enables the Telegram adapter:

  1. Open Telegram and find your bot (search for the name you gave it in BotFather)
  2. Tap Start or send /start - Kai replies "Kai is ready. Send me a message."
  3. Type a message. Kai forwards it to the agent with full tool access.

You'll see a typing indicator while the agent works, then the response streams in with live message edits every 2 seconds.

By default Kai uses long polling for Telegram updates - no tunnel or public URL needed. If you've set TELEGRAM_WEBHOOK_URL in .env, Telegram pushes updates over a webhook instead. See Exposing Kai to the Internet for webhook setup.

Try the basics

Ask a question:

What's the weather like in San Francisco?

The agent has web search access and will look it up.

Send a file: Drop a Python script, JSON file, or image into the chat. Kai passes it to the agent with full context.

Send a voice note: If you enabled VOICE_ENABLED=true, send a Telegram voice message. Kai transcribes it locally, echoes the transcription, then responds.

Explore commands (Telegram)

These slash commands belong to the Telegram surface; in the Workshop, the equivalent controls live in Settings and the channel context pane. Type /help to see all available commands. Some highlights:

  • /models - tap to pick from the models your backend offers
  • /stats - see your current session info and cost
  • /new - clear the conversation and start fresh
  • /stop - interrupt the agent mid-response if it's going off track

Set up workspaces

If you set WORKSPACE_BASE in .env (e.g., /home/you/projects), you can point Kai at any project:

/workspace myproject     → switches to ~/projects/myproject
/workspace home          → back to the default workspace
/workspace new experiment → creates ~/projects/experiment with git init
/workspaces              → interactive picker of recent workspaces

For existing projects outside WORKSPACE_BASE, add them to ALLOWED_WORKSPACES:

ALLOWED_WORKSPACES=/home/you/other-project,/home/you/legacy-app

These appear as pinned entries in /workspaces and are reachable by name (e.g., /workspace other-project).

When Kai switches workspaces, it restarts the agent session with the new project's context while preserving your identity and personal memory from the home workspace.

For per-workspace model, timeout, environment variables, and system prompts, see Workspaces - Per-workspace configuration.

Schedule a reminder

Ask naturally:

Remind me to check the CI pipeline at 3pm

Kai creates the job via its scheduling API. Check active jobs with /jobs (or /job) and cancel with /job cancel <id>.

What's happening under the hood

When you send a message, whichever surface it comes from:

  1. The surface authenticates you: your enrolled browser session in the Workshop, or your Telegram user ID against users.yaml
  2. Kai records the message canonically and prepares an agent run, injecting your identity, memory, and recent history into the session
  3. The agent runs as a persistent subprocess of the backend the admin configured
  4. Kai records the reply, then delivers it: streamed live to the browser, or as edited Telegram messages
  5. The conversation and session state persist in the canonical database

The agent runs with full tool access - shell commands, file operations, web search, code editing - all on your local machine. See System Architecture for the full picture.

Next steps

Clone this wiki locally