================================================================================
napp-it cs -- Claude Setup for Linux (English)
AI-assisted development with direct filesystem access,
native SSH, and ZFS-based backup
File: csweb-gui/data/howto.ai/setup_claude_linux.info
Companion to: setup_claude_en.info
================================================================================
================================================================================
Preword
================================================================================
napp-it is a copy and run user extendable web management suite to manage single
servers or whole servergroups. It consists of the frontend webserver (pure Perl)
and backend services for remote control via encrypted socket connections. There
are no requirements/modifications outside the napp-it cs folder /opt/csweb-gui.
This guide mirrors setup_claude_en.info (Windows) for a Linux host running its
own full csweb-gui install (webserver.pl + admin.pl + all menus) -- e.g. a
Proxmox/Linux or FreeBSD/Illumos member operated in FRONTEND mode (see
behaviours.info gotcha #17: every cluster member ships a full install and can
run standalone in frontend mode, or be driven remotely in backend mode by
another member's admin.pl via server.pl's socket protocol).
================================================================================
OVERVIEW
================================================================================
This setup gives Claude full access to the napp-it cs project (/opt/csweb-gui)
on THIS Linux host, without any ZIP upload/download cycle -- Claude reads and
edits files directly on disk. Native OpenSSH replaces the PuTTY suite used on
Windows; version control can use rsync or, since the host is already ZFS-based,
zfs send/receive instead of robocopy+SMB.
Components:
1. Claude Desktop (Linux) or Claude Code -- AI client with MCP extensions
2. MCP Filesystem Extension -- direct read/write access to /opt
3. MCP Desktop Commander -- Linux shell, processes, search
4. Native OpenSSH (ssh/scp/rsync) -- remote access to member servers
5. rsync or zfs send/receive -- backup and versioning
================================================================================
1. PREREQUISITES
================================================================================
- Linux host (any distro with a recent Perl -- Debian/Proxmox, OmniOS/
Illumos, FreeBSD, etc.)
- napp-it cs installed at /opt/csweb-gui
- System Perl (or the bundled one) with the standard CPAN modules already
used by csweb-gui (see guideline.info -- perl -c must pass before any
build, same rule as on Windows)
- Node.js + npx available (for the MCP servers, same requirement as
Windows)
- A ZFS-capable target for backups (can be the same host's own pool, or
a remote NAS reachable via ssh/rsync)
- Internet access for the Claude client download
================================================================================
2. INSTALL THE CLAUDE CLIENT
================================================================================
Option A -- Claude Desktop for Linux:
Download from https://claude.ai/download, install per distro package
format (.deb/.rpm/AppImage depending on availability), sign in.
Option B -- Claude Code (recommended for a headless/server-focused Linux
host with no desktop environment):
npm install -g @anthropic-ai/claude-code
claude-code # or: claude, depending on current package name
Sign in with your claude.ai account when prompted.
(Recommended: Claude Pro/Max for the larger context window needed for
intensive multi-file sessions like this one.)
================================================================================
3. SET UP MCP FILESYSTEM EXTENSION
================================================================================
3.1 Config file location (differs from Windows' %APPDATA%)
Claude Desktop: ~/.config/Claude/claude_desktop_config.json
Claude Code: project-level .mcp.json, or the global config per
`claude mcp` docs -- check current CLI help, this
has moved between versions.
3.2 Configure allowed directories
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/opt"
]
}
}
}
This grants Claude access to /opt/ and all subdirectories.
NOTE: if SSH private keys live under /opt/ssh/ (mirroring the Windows
layout) or ~/.ssh/, Claude only reads them for command construction
(passed to ssh -i) and never writes to them.
3.3 Restart the client after editing the config file.
3.4 Test access
In chat: "List the files in /opt" -- Claude should list the folders
directly, no upload needed.
================================================================================
4. SET UP MCP DESKTOP COMMANDER (Linux shell)
================================================================================
Same package as Windows, works identically on Linux -- gives Claude a
persistent shell (bash), can start/monitor processes, search files.
4.1 Installation
{
"mcpServers": {
"desktop-commander": {
"command": "npx",
"args": ["-y", "@wonderwhy-er/desktop-commander"]
}
}
}
4.2 Restrict allowed directories (optional)
Set allowedDirectories to ["/opt"] in Desktop Commander settings for
tighter scope, same as the Windows setup.
4.3 Typical use
Claude can directly:
- Run perl -c syntax checks
- Run rsync / zfs send-receive for backups
- Call ssh / scp directly (no plink/pscp wrapper needed)
- Start/stop/restart processes (server.pl, webserver.pl via
systemctl or ksmbd.control-style service tools)
- tail -f logs
================================================================================
5. SSH ACCESS TO OTHER MEMBERS -- NATIVE OpenSSH (simpler than Windows)
================================================================================
Windows needs the PuTTY suite (plink.exe/pscp.exe) plus a key FORMAT
conversion step (puttygen.exe, .ppk). Linux skips all of that -- the
system's own ssh/scp/rsync work directly with standard OpenSSH keys.
5.1 Generate a key (if one doesn't already exist)
ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519 -N ""
(or reuse an existing key -- no conversion needed, unlike Windows'
id_rsa.ppk which requires puttygen to convert from OpenSSH format)
5.2 Deploy the public key to target hosts
ssh-copy-id -i ~/.ssh/id_ed25519.pub root@TARGET_HOST
(does the mkdir ~/.ssh + append to authorized_keys + chmod 600 dance
automatically -- on Windows this is a manual multi-step per the
Windows setup guide section 5.3)
5.3 Test the connection
ssh -i ~/.ssh/id_ed25519 root@TARGET_HOST hostname
First connection: accept the host key fingerprint prompt once (stored
in ~/.ssh/known_hosts). Add -o StrictHostKeyChecking=accept-new for a
non-interactive first-touch if scripting this.
5.4 Batch/non-interactive equivalent of plink's -batch
ssh -o BatchMode=yes -i ~/.ssh/id_ed25519 root@TARGET_HOST "command"
5.5 File transfer -- scp or rsync instead of pscp.exe
Pull a file:
scp -i ~/.ssh/id_ed25519 root@TARGET_HOST:/opt/csweb-gui/tmp/error.log /tmp/error_target.log
Push a file (deploying a fix -- same pattern used from a Windows
controller via pscp to push .pl fixes to Linux/Samba members):
scp -i ~/.ssh/id_ed25519 \
/opt/csweb-gui/data/menues/_lib/windows/sharelib.pl \
root@TARGET_HOST:/opt/csweb-gui/data/menues/_lib/windows/sharelib.pl
rsync (better for multi-file syncs, preserves permissions/timestamps,
supports --dry-run):
rsync -av -e "ssh -i ~/.ssh/id_ed25519" \
/opt/csweb-gui/data/ root@TARGET_HOST:/opt/csweb-gui/data/
================================================================================
6. BACKUP / VERSIONING -- rsync or zfs send/receive instead of robocopy+SMB
================================================================================
The Windows setup mirrors C:\opt to an SMB share on a separate OmniOS NAS
via robocopy, because Windows itself has no native ZFS snapshot access.
A Linux host running csweb-gui is very likely ALREADY on ZFS (Proxmox,
Illumos, FreeBSD) -- prefer working with that directly instead of
reintroducing an SMB round-trip.
6.1 If /opt (or its parent) is itself a ZFS dataset
Snapshot before a change round, same spirit as sync_version.bat:
zfs snapshot POOL/opt@$(date +%Y.%m.%d_%H.%M)
Optionally replicate off-host:
zfs send POOL/opt@SNAPNAME | ssh root@NAS_HOST zfs receive -F backup/opt
This is a closer match to how the project already thinks about
recovery (see guideline.info's snapshot-based undo strategy) than a
file-copy mirror.
6.2 If /opt is plain filesystem (not ZFS) on this host
rsync to a remote target, mirroring robocopy's /MIR semantics:
rsync -av --delete \
--exclude 'tmp/' --exclude 'ssh/' \
/opt/csweb-gui/ root@NAS_HOST:/backup/opt/csweb-gui/
(matches sync_version.bat's own exclusion of tmp\ and ssh\)
6.3 Recovery
ZFS: browse /POOL/opt/.zfs/snapshot/SNAPNAME/... directly, cp out the
needed file, then perl -c it before trusting it.
rsync target: same idea via the mirrored copy on NAS_HOST.
================================================================================
7. CLAUDE -- GENERAL INSTRUCTIONS (equivalent of the Windows System Prompt)
================================================================================
Recommended text (adapt paths to this host):
-----------------------------------------------------------------------
napp-it cs project is at /opt/csweb-gui.
At session start read the guideline: csweb-gui/data/howto.ai/guideline.info
and all *.info files in that folder and in _my/howto.ai/.
Before larger changes: snapshot/backup per section 6 of
setup_claude_linux.info and confirm it succeeded.
This host can run in frontend mode (own webserver.pl serves the GUI
directly) or backend mode (controlled remotely by another member's
admin.pl) -- confirm which applies before assuming a fix here is the
one actually in effect for what the person sees in their browser
(see behaviours.info gotcha #17).
-----------------------------------------------------------------------
================================================================================
8. TYPICAL WORKFLOW (daily use)
================================================================================
1. Start Claude (Desktop or Code) on this host
2. Confirm at session start:
- Project /opt/csweb-gui read
- guideline.info and all *.info files read
- Last backup/snapshot recency checked
- admin.pl / server.pl version strings shown
3. Describe the task
4. For larger changes: snapshot/backup first (section 6)
5. Claude edits files directly (no ZIP upload needed)
6. Reload the browser page -> changes visible immediately
(only if THIS host's own webserver.pl is what's being browsed --
see behaviours.info gotcha #17 on frontend vs backend mode)
7. For server.pl changes: restart the backend service on this host
(systemctl restart/reload, per how this host's server.pl is run)
================================================================================
9. REMOTE ACCESS TO OTHER MEMBER SERVERS (logs, diagnostics, deploying fixes)
================================================================================
Read logs:
ssh -i ~/.ssh/id_ed25519 root@MEMBER_IP "tail -50 /opt/csweb-gui/tmp/error.log"
ZFS status:
ssh -i ~/.ssh/id_ed25519 root@MEMBER_IP "zpool status"
Fetch a file from a member:
scp -i ~/.ssh/id_ed25519 root@MEMBER_IP:/opt/csweb-gui/tmp/error.log /tmp/error_member.log
Push a file to a member (ad-hoc fix deployment -- prefer the built-in
About > Frontend Update feature for routine updates, see behaviours.info
gotcha #17; this is the fast fallback for live iteration within a
session):
scp -i ~/.ssh/id_ed25519 \
/opt/csweb-gui/data/cs_server/server.pl \
root@MEMBER_IP:/opt/csweb-gui/data/cs_server/server.pl
================================================================================
10. TROUBLESHOOTING
================================================================================
Claude cannot see files in /opt
-> Filesystem MCP not installed or wrong path in config
-> Check ~/.config/Claude/claude_desktop_config.json (or Claude Code's
current config location), restart the client
ssh asks for a password
-> Public key not deployed: re-run ssh-copy-id
-> Wrong key file: check with ssh -v for which identity was tried
-> Host key changed (e.g. re-imaged member): remove the stale entry
from ~/.ssh/known_hosts, reconnect once interactively to re-accept
ssh hangs waiting for a prompt in a scripted/batch context
-> Add -o BatchMode=yes so it fails fast instead of hanging on a
password prompt (equivalent of plink's -batch)
rsync/scp "Permission denied"
-> Check remote directory ownership/permissions, and that the SSH
user (root, typically, matching the rest of this project's
convention) actually owns /opt/csweb-gui on the target
Claude edits the wrong files
-> Always check: Claude reads _my/howto.ai/ last (overrides standard --
ONLY use _my/ for genuinely individual/private user files, e.g.
ones containing a specific person's real IPs/network layout;
general, reusable guidance like this file belongs in
data/howto.ai/ per guideline.info convention, not _my/)
-> Ask in chat: "Which file did you just edit?"
Unsure whether this host is in frontend or backend mode right now
-> ps aux | grep webserver.pl -- if running and the person's browser
points at THIS host's own IP, it's frontend mode for them right
now, regardless of what mode it's used in at other times
(see behaviours.info gotcha #17)
================================================================================
. 
.