docs
Documentation
Everything you need to install, configure, and operate Ghost Shell — from the first recording to a fleet-wide audit posture.
Getting started
- IntroductionGhost Shell records every shell session on a Linux host, encrypts it at rest, and lets root replay, search, and live-tail from a central store.
- InstallationInstall Ghost Shell from a .deb or .rpm package, a static binary, or source - and see exactly what the package puts on disk.
- Quick startRecord your first shell session with ghostshell rec, list it with ls, and replay it with play - all in under two minutes.
Guides
- Audit modeHow the central root-only store works - the daemon, /var/lib/ghostshell layout, per-user listings, the tree view, and fail-open ingest.
- ReplayReplay any recording in the full-screen player - seek, pause, speed from 1/64x to 64x, jump-to-time, scroll view, and click-to-seek.
- SearchGrep across every recording on the host with ghostshell search, filtered by user and natural-language --from and --to dates.
- Live tailWatch an in-progress shell session in real time with ghostshell tail -f, or print the last N lines of any recorded session.
- Process tree and analyzeView a session as a structured process tree with exit codes and timings, then analyze it - optionally with a fully local Ollama AI summary.
- ExportDecrypt a central recording to a plaintext asciinema v2 cast with ghostshell export, ready for asciinema play or any other tool.
- Auto-record on loginRecord every interactive login automatically with the optional profile.d hook - fail-open, nested-shell aware, one file to remove.
- SSH recordingOpt in to recording non-interactive SSH commands with the sshd ForceCommand wrapper - validated, reversible, and fail-open.
- Ansible trackingRecord Ansible playbook runs on the controller with a callback plugin - plays, tasks, per-host status and output, stored encrypted.
- Shell completionEnable bash tab-completion for ghostshell subcommands, flags, local sessions, and - as root - users and central session IDs.
- Backup and pruneKeep the central store healthy - run configured backups with ghostshell backup and delete old recordings interactively with prune.
Reference
- CommandsFull ghostshell command reference - personal commands, root-only audit commands, and the flags for rec and play.
- ConfigurationEvery ghostshell config key with defaults and env overrides, plus environment variables, the filesystem layout, and daemon management.
- File formatRecordings are asciinema v2 casts - JSON lines, UTF-8. Central copies are wrapped in TTEC, Ghost Shell's framed AES-256-GCM encryption.
- TroubleshootingFixes for common Ghost Shell issues - config not found, recording hangs, missing sessions, replay artifacts, and stale man pages.
Security
- Security modelWhat Ghost Shell protects and what it does not - trust boundary, encryption, key immutability, fail-open semantics, and the integrity caveat.
- Threat model FAQDirect answers about Ghost Shell's trust boundary - who can read recordings, what a hostile user can do, and what happens when things fail.
Project
- FAQCommon questions about Ghost Shell - platforms, shells, SSH, asciinema compatibility, overhead, and how it compares to what you use today.
- ContributingHow to report bugs, submit pull requests, run the checks CI enforces, and build Ghost Shell packages from source.
- LicenseGhost Shell is licensed under the GNU General Public License v2.0. What that means for using, modifying, and redistributing it.