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. Provide the LLM API key. mikan resolves the key for a provider from the <PROVIDER>_API_KEY environment variable, so for the default anthropic provider:

   export ANTHROPIC_API_KEY="sk-ant-..."

   Keys can also be stored in ~/.mikan/auth.json; the environment variable is the simplest way to start.

3. Create the global settings file:

   mikan --onboard

   This writes ~/.mikan/settings.json with anthropic as the default provider. Review it if you want a different model; see Configuration for every field.

   The settings default to an isolated door policy, which only the managed Docker sandbox can satisfy — with it, host mode refuses to run. This guide runs without Docker, 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 satisfies the isolated policy as-is.

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

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

5. 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.

6. 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 the default isolated 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.