Quickstart

This guide gets a working bot replying to you in about 15 minutes. It uses Telegram because it needs only one token. You need Node.js 24.15 or later and Docker (Podman and nerdctl also work; see OCI sandbox). At the end, links point to the other platforms and to running mikan under PM2.

Prerequisites

• Node.js >=24.15.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

   Picking Slack, mikan can create the Slack app for you from a Slack configuration token; see Slack Bot minimal setup guide. Three questions — chat adapter (with its tokens), LLM provider (with its API key), and sandbox image — produce ~/.mikan/settings.json, ~/.mikan/mikan.env (0600), and ~/.mikan/ecosystem.config.cjs. Pick the recommended image. 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 does not write any office policy: visibility follows the platform conversation type. Telegram private chats are private offices, and the Docker sandbox keeps each office’s files to itself.

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 in the foreground; it pulls the sandbox image on start:

   mikan --sandbox=oci

   The image is about 900 MB, so the first start takes a few minutes. The working directory defaults to ~/.mikan/workspace and is created automatically; pass a path after the flags 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.

Keep it running

To keep mikan up after you close the terminal, follow Deployment: pm2 start ~/.mikan/ecosystem.config.cjs runs the same command under PM2.

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=oci:...; see OCI 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.