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

{
  "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
`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: 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

~/.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.