Skip to content

Latest commit

 

History

History
107 lines (84 loc) · 5.54 KB

storage.md

File metadata and controls

107 lines (84 loc) · 5.54 KB

Storage and persistence

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.

Where things live

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.

Pool mode

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.

Fallback mode

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.

The emergency token

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 hidden

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

What a reboot looks like

  1. Boot: the plugin reinstalls from the flash cache (no network needed), restores the managed policy, and enters fallback mode. claude works, in RAM.
  2. The array starts: disks_mounted fires, the data directory is validated, the mode switches to pool, and supervised sessions that were live at shutdown are resumed in their workspaces.
  3. The array stops: supervised sessions are stopped first (bounded by 10 s), then the mode switches back to fallback. Plain claude sessions 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.

/boot is read-only for the agent

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-rw

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