System protection guide

Session Helper Guide

kodachi-session-helper is the user-session daemon behind Kodachi emergency keyboard shortcuts. It combines X11 grabs, hardware-event corroboration, hold-to-trigger timing, and local token authorization before routing an armed shortcut to the configured emergency action.

3 parser commands · user-session daemon · X11 plus evdev verification

Emergency shortcuts Anti-spoofing Hold to trigger Dry-run testing

01 Exact CLI reference Generated commands, options, examples, and hashes. 02 Protection overview Return to the local protection and isolation map. 03 Explore commands Open this binary in the searchable command library.

Emergency actions can destroy data

The daemon can route an armed shortcut to dashboard destruction, LUKS wipe, a combined action, or delayed lockdown. Review ~/.config/kodachi/session-helper.json before starting or reloading it. Use dry_run: true while testing. Do not test an armed destructive plan on a machine that contains data you need.

Guide versus CLI reference

This guide explains trust boundaries, safe operating order, and troubleshooting. The generated CLI reference remains the canonical source for exact flags, parser syntax, examples, build metadata, and hashes.

What the Session Helper Protects

A desktop emergency shortcut is useful only if synthetic input cannot trigger it accidentally or maliciously. The session helper checks the same shortcut through separate input paths and requires a sustained hold before it authorizes an action.

Layer	Role	Failure signal
X11 key grab	Registers the configured global shortcut and detects collisions.	The status response reports failed grabs.
evdev corroboration	Checks raw hardware events so XTEST-only input does not satisfy the trigger.	The status response reports evdev state and runtime warnings.
Hold detector	Requires the configured sustained press and rejects auto-repeat as a shortcut trigger.	The action remains unarmed until the full hold completes.
Session token	Uses a local 256-bit token when handing an approved action to `health-control`.	The action fails closed if authorization cannot be established.
Delayed lockdown	Provides a configured countdown and cancellation path before the selected action.	The status response exposes the active countdown state.

Safe Operating Order

Inspect the configuration. Confirm every enabled shortcut, action plan, hold duration, lockdown delay, and LUKS device target.
Enable dry-run for testing. Keep dry_run: true until the intended key combination, corroboration state, and countdown behavior are proven.
Run as the desktop user. The daemon is designed for a regular X11 session and must not be started as root.
Check the live state. Query status before and after a reload. Resolve grab failures and runtime warnings before arming a real action.
Arm only after verification. Disable dry-run only when recovery media, backups, device paths, and the intended action plan have been independently checked.

# Read-only runtime inspection
kodachi-session-helper status --json

# Reload only after reviewing the configuration file
kodachi-session-helper reload

For the daemon command and all supported options, use the exact daemon reference.

Command Intent Map

Command	Operational purpose	Documentation
`status`	Read the running daemon state over its local Unix socket, including armed shortcuts, grab failures, evdev state, countdown state, and warnings.	Exact CLI reference
`reload`	Request an atomic configuration reload and key-grab registration refresh without restarting the session.	Exact CLI reference
`daemon`	Run the foreground session daemon after its safety checks. Starting it can arm configured emergency actions.	Exact CLI reference

Environment Requirements

A Linux desktop session using X11 with a valid DISPLAY.
The daemon must run as the regular desktop user, not root.
Access to raw input devices is needed when evdev corroboration is required.
health-control must be available for emergency-action routing.
Virtual machines may report a relaxed input-verification mode; treat that status warning as a weaker trust boundary, not as normal hardware assurance.

Troubleshooting

Symptom	Check	Safe response
Status cannot connect	Confirm the user-session service is running and that the socket belongs to the current desktop user.	Do not start a second daemon blindly. Inspect the service and process state first.
Shortcut grab failed	Look for a desktop or window-manager shortcut using the same key combination.	Choose a non-reserved supported key, keep dry-run enabled, then reload.
evdev unavailable	Check input-group membership and device permissions.	Restore hardware corroboration instead of permanently weakening the policy.
Reload reports warnings	Compare the new shortcut list, action plans, device paths, and delays with the previous configuration.	Keep dry-run enabled until status is clean and the intended mapping is verified.
Wayland session detected	The helper requires X11 key grabs.	Use a supported X11 session; do not bypass the preflight check.

Session Helper CLI Reference, exact generated syntax, flags, examples, build metadata, and hashes.
Health Control Guide, the downstream emergency-action engine.
Permission Guard Guide, local permission monitoring and remediation.
File Verification, browser-side verification against published hashes.