Unraid runs from RAM. Only the flash drive (/boot) and the array or pools under
/mnt survive a reboot, and /mnt is only there while the array is started. The
plugin therefore has two storage modes and switches between them as the array starts
and stops.
| What | Where | Survives a reboot |
|---|---|---|
| Claude Code binary (cached) | /boot/config/plugins/claude-code-unraid/bin/ (current and previous version, about 280 MB each) |
yes |
| Plugin settings | /boot/config/plugins/claude-code-unraid/claude-code-unraid.cfg |
yes |
| Your policy drop-ins | /boot/config/plugins/claude-code-unraid/policy.d/ |
yes |
| Emergency token (optional) | /boot/config/plugins/claude-code-unraid/emergency-token |
yes |
| Login, settings, memory, transcripts, project trust, MCP config | <data dir>/config/ (this is CLAUDE_CONFIG_DIR) |
yes, once the array is started |
Workspaces (claude-unraid work <name>) |
<data dir>/work/<name>/ |
yes |
| Session registry | <data dir>/sessions.json |
yes |
| Runtime state, locks, fallback config | /run/claude-code-unraid/ |
no |
| Plugin logs | /var/log/claude-code-unraid/ |
no |
The data directory defaults to <appdata>/claude-code-unraid, where <appdata> is the
default appdata path from Settings > Docker (usually /mnt/user/appdata). When that
share is set to live on a single pool, the plugin uses the direct pool path (for example
/mnt/cache/appdata/claude-code-unraid) instead of the /mnt/user FUSE path, which is
faster and keeps the mover out of the way. You can set any path under an existing share
or pool directory in the plugin settings. The plugin never creates a share: the parent of
the data directory must already exist.
Transcripts can contain anything the agent read or wrote on your server. Keep the data directory on a share that only you can access.
Active after the array has started and the data directory is usable. Claude Code uses
<data dir>/config as its configuration directory, so logging in with /login once is
enough: the login, trust decisions for your workspaces and all conversations persist
across reboots.
Active from boot until the array starts, after the array stops, and whenever the data
directory is not usable. Claude Code uses a configuration directory in RAM
(/tmp/claude-code-unraid/fallback-config). This is what lets you use Claude Code to
diagnose a server whose array will not start, which a Docker container could not do.
Everything you do in fallback mode is lost when the mode switches or the server reboots: the login, the conversation, any files you create under the fallback workspace. If you logged in during fallback mode and want to keep it, the plugin tells you how when the array starts; it never merges the two configurations on its own.
Logging in needs a browser round trip. To skip it while the array is down, you can store a long-lived token on the flash drive:
claude setup-token # prints a token; copy it
claude-unraid token set --stdin # paste it; the input is hiddenor pipe it in from a password manager: my-pw-manager show claude-token | claude-unraid token set.
The launcher passes the token to Claude Code through the environment
(CLAUDE_CODE_OAUTH_TOKEN), only in fallback mode, and never on a command line.
claude-unraid token status and token clear manage it; nothing ever prints it.
Trade-off: the token grants access to your Claude account. The flash drive is a FAT
filesystem (no file permissions) and can be exported over SMB as the flash share. If
it is exported, anyone who can read that share can read the token. claude-unraid doctor
and the plugin page warn about this; the fix is Main > Boot Device > Flash > SMB
Security Settings > Export: No. If you do not need Claude Code while the array is down,
do not store a token.
- Boot: the plugin reinstalls from the flash cache (no network needed), restores the
managed policy, and enters fallback mode.
claudeworks, in RAM. - The array starts:
disks_mountedfires, the data directory is validated, the mode switches to pool, and supervised sessions that were live at shutdown are resumed in their workspaces. - The array stops: supervised sessions are stopped first (bounded by 10 s), then the
mode switches back to fallback. Plain
claudesessions started by hand in a terminal are not stopped, but they are reported in the syslog with their PIDs because their working directory is about to disappear.
claude runs Claude Code in a private mount namespace where /boot is remounted
read-only. The agent can read the flash drive (plugin configs, go file, syslinux.cfg),
and a plain write to it fails in the kernel. One way around exists, because the session
is still root in the host's PID namespace: /proc/<pid>/root/boot of a host process is
the writable host view. The guard asks before that path is used and logs it, but it
matches text (docs/SECURITY.md, "The read-only flash drive and its limit"). To allow
writes for one session:
claude --boot-rwThis works only when "Allow writable /boot sessions" is enabled in the plugin settings,
prints a warning and is logged. If the read-only remount fails for any reason, claude
refuses to start instead of silently running with a writable flash drive.
Known limitation: mounts the agent performs inside its session (for example mounting a
disk under /mnt/disks) stay inside the session's namespace. Run such commands from a
normal shell.