---
title: "Configuration"
description: "Configure startup, global and conversation settings, platform credentials, sandbox limits, and environment variables."
url: "https://geminixiang.github.io/configuration/"
---

# Configuration

## First-time setup

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

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

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

```json
{
  "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](/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.