> ## Documentation Index
> Fetch the complete documentation index at: https://rakumux.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> config.json, environment variables, and the files in ~/.rakumux.

## `config.json`

Rakumux keeps its settings in `~/.rakumux/config.json`. Settings changed in the UI are saved there;
a few exist only in the file.

```json theme={null}
{
  "anthropic_api_key": "sk-ant-…",
  "sessions": {
    "rakumux_key": "ctrl+\\",
    "cycle_keys": ["alt+up", "alt+down"],
    "cycle_keys_in_session": false,
    "icons": "plain"
  }
}
```

| Key | Default | Meaning |
| - | - | - |
| `anthropic_api_key`, `openai_api_key` | none | Keys for [AI naming](https://rakumux.com/docs/agents/ai-naming.md) |
| `ai_primary_provider` | Anthropic | `"openai"` to use OpenAI when both keys are set |
| `openai_model` | `gpt-4o-mini` | The OpenAI model for naming |
| `sessions.rakumux_key` | `"ctrl+\\"` | The Rakumux key |
| `sessions.cycle_keys` | `["alt+up", "alt+down"]` | Keys that move to the previous and next session |
| `sessions.cycle_keys_in_session` | `false` | Let the cycle keys work inside sessions too (Settings → **Option+↑/↓ in sessions**) |
| `sessions.icons` | `"plain"` | Marks for folders and branches: `plain`, `emoji` or `nerd` (Settings → **Icons**) |
| `sessions.ai_summary` | `{"every_messages": 5, "recent_messages": 10}` | [AI session titles](https://rakumux.com/docs/account/ai-titles.md): a chat's one automatic title once its agent has written `every_messages` messages (or finished sooner), from your prompt and its newest `recent_messages` |
| `sessions.welcome_seen` | `false` | Set by the welcome tour's **Don't show this on startup** box |

Rakumux also stores the list order you set (`sessions.session_order`, `sessions.section_order`), the
list width you dragged, and whether it already offered phone access. Edit those through the UI.

## Environment variables

| Variable | Meaning |
| - | - |
| `RAKUMUX_HOME` | Use another data directory instead of `~/.rakumux`: a separate registry, socket and therefore a separate server |
| `ANTHROPIC_API_KEY`, `OPENAI_API_KEY` | AI naming keys, when `config.json` has none |
| `RAKUMUX_PTYD_BIN` | The server binary to start |
| `RAKUMUX_API_BIN` | The `rakumux-api` binary that `rakumux-mcp`, `rakumux remote` and the UI start |
| `RAKUMUX_PTYD_LOG` | The server's log level |
| `RAKUMUX_API_LOG` | `debug` logs every API request (never tokens) |
| `CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `XDG_DATA_HOME` | Where Rakumux looks for agents' conversations to resume them |

### Inside every session

Rakumux sets these in every session's environment:

| Variable | Meaning |
| - | - |
| `RAKUMUX_SESSION_ID`, `RAKUMUX_SESSION_TOKEN` | This session's identity, used by `rakumux session`, the MCP server and the hooks |
| `RAKUMUX_SOCKET` | The server's socket |
| `RAKUMUX_BIN` | The `rakumux` launcher, for agents and hooks |
| `TERM=xterm-256color`, `COLORTERM=truecolor` | Terminal type and colour support |

Sessions the server revives by itself (after a crash or reboot) get the server's environment: the
one the client that started it had.

## Files

```text theme={null}
~/.rakumux/
  rakumux.sqlite3            the session registry and audit log (server only)
  sessions/<id>/             each session's saved scrollback and metadata
  history/<id>.log           command history, used for AI naming
  config.json                settings (above)
  running.json               the sessions running now, revived after a crash or reboot
  remote.json                phone access: on/off, port and token (mode 0600)
  api.json                   the running HTTP API's address and token (mode 0600)
  logs/ptyd.log              the server log (rakumux daemon logs)
  logs/api.log               the log of a background rakumux-api
  logs/status-service.log    the log of the account service (static failure codes only)
  sensagent/                 the account service: your sign-in (credentials/, mode 0600) and
                             AI session titles with their sharing consent (status/)
  run/service.json           how clients find and authenticate to the server (mode 0600)
```

The server's socket is `/tmp/rakumux-<uid>/ptyd-<hash>.sock`, private to your user.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.