---
title: "Quickstart"
description: "Go from zero to your first bot reply in about 15 minutes with Telegram and the host sandbox."
url: "https://geminixiang.github.io/quickstart/"
---

# Quickstart

This guide gets a working bot replying to you in about 15 minutes. It uses Telegram because it needs only one token, and the `host` sandbox because it needs no Docker setup. At the end, links point to the other platforms and to proper isolation.

## Prerequisites

- Node.js `>=22.19.0`
- An Anthropic API key (or a key for another supported provider)
- A Telegram account

1. Install mikan:

   ```bash
   npm i -g @geminixiang/mikan
   ```

2. Run the interactive setup:

   ```bash
   mikan onboard
   ```

   Three questions — chat adapter (with its tokens), LLM provider (with its API key), and sandbox mode — produce `~/.mikan/settings.json` and `~/.mikan/mikan.env` (0600). A custom OpenAI-compatible endpoint (vLLM, a proxy) also writes `~/.mikan/models.json`. Non-interactive stdin writes the settings template only. See [Configuration](/configuration/) for every field.

   Keys can equally come from plain environment variables (`<PROVIDER>_API_KEY`, e.g. `ANTHROPIC_API_KEY`); the env file is just a persistent home for them that the pm2 template loads.

   Onboarding leaves the workspace policy unset so platform visibility can decide it. Telegram private chats fail closed to `isolated`, which only the managed Docker sandbox can enforce; this guide uses `host`, so mark the workspace as trusted by merging this into `~/.mikan/settings.json`:

   ```json
   {
     "sandbox": {
       "workspace": { "doorPolicy": "trusted", "layout": "shared-support" }
     }
   }
   ```

   If you start with the managed [image sandbox](/sandbox/image/) instead (`--sandbox=image:…`), skip this edit — it enforces the platform-derived isolated projection as-is.

3. Create a Telegram bot. Message [@BotFather](https://t.me/BotFather), send `/newbot`, follow the prompts, and copy the token it returns:

   ```bash
   export TELEGRAM_BOT_TOKEN="123456:ABC-..."
   ```

4. Start mikan:

   ```bash
   mikan --sandbox=host
   ```

   The working directory defaults to `~/.mikan/workspace` and is created automatically; pass a path (`mikan --sandbox=host ~/mikan-workspace`) to use a different one.

   Inside that workspace, each conversation gets its own **office**: a directory holding that conversation's memory, attachments, session logs, skills, and working area. Office directories are named by office key (`v1-telegram-…`) rather than by the raw chat id, so `mikan office list` is the way to see which office belongs to which conversation.

   If startup fails, run `mikan env`: it prints every variable mikan reads, grouped by platform and feature, with the current status of each. A missing platform token makes mikan exit with a message naming the variables to set; `mikan --help` lists all flags.

5. Open a private chat with your bot on Telegram and send it a message. Private messages trigger the agent directly, so it should reply within a few seconds.

  In `host` mode the agent's commands run directly on your machine with your permissions. It is the
  right mode for a first try on a trusted machine. Before letting other people talk to the bot,
  switch to the managed [image sandbox](/sandbox/image/), which gives each conversation an isolated
  Docker container — and remove the trusted door-policy override so platform-derived workspace
  policy applies again.

## Where to go next

- **Slack, Discord, or GitHub instead of Telegram** — each platform needs its own credentials; see the [Slack minimal setup guide](/slack-bot-minimal-guide/), [Discord adapter](/platform-adapters/discord/), and [GitHub adapter](/platform-adapters/github/).
- **Isolation for real use** — pull the prebuilt sandbox image and start with `--sandbox=image:...`; see [Image sandbox](/sandbox/image/).
- **Credentials for the agent's tools** — `/login` in a DM opens a vault portal for API keys and OAuth; see [Vault](/sandbox/vault/).
- **Run it as a service** — PM2 setup, upgrades, and health checks are covered in [Deployment](/deployment/).
- **All settings and commands** — [Configuration](/configuration/) and [Chat commands](/commands/).