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:

   npm i -g @geminixiang/mikan

2. Run the interactive setup:

   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 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:

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

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

3. Create a Telegram bot. Message @BotFather, send /newbot, follow the prompts, and copy the token it returns:

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

4. Start mikan:

   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.

Host sandbox runs on your machine

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, 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, Discord adapter, and GitHub adapter.
• Isolation for real use — pull the prebuilt sandbox image and start with --sandbox=image:...; see Image sandbox.
• Credentials for the agent’s tools — /login in a DM opens a vault portal for API keys and OAuth; see Vault.
• Run it as a service — PM2 setup, upgrades, and health checks are covered in Deployment.
• All settings and commands — Configuration and Chat commands.