Configuration

First-time setup

mikan requires a global settings file before normal startup. Create it once, review it, then start mikan with a workspace:

mikan --onboard
mikan --sandbox=host /path/to/workspace

The default state directory is ~/.mikan. Use the same --state-dir for onboarding and normal startup when you choose another location:

mikan --onboard --state-dir=/secure/mikan-state
mikan --state-dir=/secure/mikan-state /path/to/workspace

mikan creates a missing state directory with mode 0700. An existing directory must be owned by the current user and must not be world-writable. For sandboxed modes, keep it outside the workspace so tools cannot reach credentials or administrator settings.

Settings locations

Scope	Path	Purpose
Global	<state-dir>/settings.json	Required defaults for every conversation
Conversation	<state-dir>/conversations/<conversationId>/settings.json	Partial overrides for one conversation

Conversation settings are host-authoritative. Older <workspace>/<conversationId>/settings.json files are migrated on first access and are not read again from the sandbox-visible workspace.

Generated settings

mikan --onboard creates:

{
  "llm": {
    "provider": "anthropic",
    "model": "claude-sonnet-4-6",
    "thinkingLevel": "off",
    "autoReply": {
      "provider": "anthropic",
      "model": "claude-haiku-4-5"
    }
  },
  "slack": {
    "replyMode": "top-level"
  },
  "sandbox": {
    "cpus": "0.5",
    "memory": "1g",
    "boost": {
      "cpus": "2",
      "memory": "4g"
    },
    "image": {
      "workspaceMount": "private"
    },
    "defaultSharedVault": ""
  }
}

Settings fields

The values below are generated by onboarding. llm.provider, llm.model, and llm.thinkingLevel are required in the resolved global configuration; the other fields may be omitted.

Field	Onboarding value	Description
llm.provider	anthropic	Main AI provider
llm.model	claude-sonnet-4-6	Main model name
llm.thinkingLevel	off	off, minimal, low, medium, high, xhigh, or max
llm.autoReply.provider	anthropic	Optional model provider used to evaluate auto-reply rules
llm.autoReply.model	claude-haiku-4-5	Optional model used to evaluate auto-reply rules
sentry.dsn	unset	Sentry DSN; sensitive prompt and tool content is redacted
sandbox.cpus	0.5	CPU limit for mikan-managed image/Gondolin runtimes; Gondolin rounds fractional values up to whole vCPUs
sandbox.memory	1g	Memory limit for mikan-managed image/Gondolin runtimes
sandbox.boost.cpus	2	Temporary CPU limit applied by /pi-sandbox boost
sandbox.boost.memory	4g	Temporary memory limit applied by /pi-sandbox boost
sandbox.image.workspaceMount	private	For image/Gondolin sandboxes, private exposes shared support files plus the current conversation; full exposes the complete workspace
sandbox.defaultSharedVault	empty	Shared vault copied into eligible membership-trust image/Cloudflare conversations
slack.replyMode	top-level	Slack response mode: top-level or thread

/pi-model writes a partial conversation override. /pi-sandbox private|full updates the conversation’s workspace mount mode. Auto-reply enablement and rule text are managed by /pi-auto-reply and the conversation’s auto-reply marker file, not by the JSON settings fields.

Platform credentials

At least one complete platform credential set is required for normal bot mode:

Platform	Required environment variables	Optional variables
Slack	SLACK_APP_TOKEN, SLACK_BOT_TOKEN	—
Telegram	TELEGRAM_BOT_TOKEN	—
Discord	DISCORD_BOT_TOKEN	—
GitHub	GITHUB_APP_ID, GITHUB_INSTALLATION_ID, and GITHUB_APP_PRIVATE_KEY or GITHUB_APP_PRIVATE_KEY_PATH	GITHUB_REPOS, GITHUB_POLL_INTERVAL

See Platform adapters for platform-specific setup and permissions.

CLI reference

Command or option	Purpose
mikan --onboard [--state-dir=<dir>]	Create the required global settings file
mikan [--state-dir=<dir>] [--sandbox=<mode>] [working-directory]	Start configured platform bots; the working directory defaults to <state-dir>/workspace
--sandbox=host | container:<name> | image:<image> | gondolin:default | firecracker:... | cloudflare:<id>	Select tool execution mode; default is host
mikan env	Show the full environment-variable inventory and what is currently set
mikan --download <channel-id>	Download Slack channel history; requires SLACK_BOT_TOKEN
mikan --version	Print the installed version
mikan --help	Show CLI usage and the platform-token summary
mikan ext ...	Manage harness extensions; run mikan ext for subcommands

Environment variable aliases

Environment variables read through mikan’s configuration helper also accept a MIKAN_ prefix. For example, MIKAN_SLACK_APP_TOKEN and MIKAN_LINK_URL are fallbacks for SLACK_APP_TOKEN and LINK_URL; the unprefixed value takes precedence. SENTRY_DSN is the exception: configure it directly or set sentry.dsn in settings.json.

The daemon’s full environment interface is declared as a manifest in the source tree; mikan env prints the annotated inventory grouped by platform and feature, with the current status of each variable, so you can audit a deployment without reading code.

mikan writes logs to stdout/stderr. Use PM2, systemd, Docker, or your hosting platform to route and retain them.