Binary reference

kodachi-session-helper

Global emergency keyboard shortcut daemon for Kodachi OS

Version10.0.3Size2.4MBAuthorWarith Al MaawaliLicenseProprietaryWebsitehttps://digi77.com

File Information

Property	Value
Binary Name	kodachi-session-helper
Version	10.0.3
Build Date	Not disclosed
Rust Version	1.82.0
File Size	2.4MB
Author	Warith Al Maawali
License	Proprietary
Category	Kodachi Binary
Description	Global emergency keyboard shortcut daemon for Kodachi OS
Git Commit	unknown
Metadata Generated	2026-09-29T22:00:20Z
Binary Timestamp	Unknown
JSON Data	View Raw JSON

SHA256 Checksum

d2514e9b345e09b769e2a14ec929d4c3395f059b39fcc7d08f23cb33cb763317

Features

#	Feature
1	X11 key grab registration with collision detection
2	Raw /dev/input hardware corroboration (anti-XTEST)
3	Hold-to-trigger with auto-repeat rejection (1500ms default)
4	Local session token authentication (no network required)
5	Delayed lockdown with cancel capability
6	Unix socket for dashboard status queries
7	Atomic config reload via SIGHUP
8	LUKS device wipe + dashboard nuke combined actions
9	X11 disconnect detection with auto-reconnect
10	Memory protection via mlock and PR_SET_DUMPABLE

Security Features

Feature	Description
Authentication	Local 256-bit session token (no network dependency)
Encryption	SHA-256 token digest; memory locked and zeroized on exit
Input Validation	All configuration validated; key grabs verified against collisions
Rate Limiting	Hold-to-trigger with cooldown prevents accidental re-trigger

System Requirements

Requirement	Value
OS	Linux (Kodachi OS / Debian-based with X11)
Privileges	User session (non-root); 'input' group for evdev
Dependencies	X11 display server, health-control binary, /dev/input access (input group)

Global Options

Flag	Description
`-h, --help`	Print help information
`-v, --version`	Print version information
`-n, --info`	Display detailed information
`-e, --examples`	Show usage examples
`--json`	Output in JSON format
`--json-pretty`	Pretty-print JSON output
`--json-human`	Enhanced JSON output (like jq)
`--verbose`	Enable verbose output
`--quiet`	Suppress non-essential output

Commands

Daemon Control

`daemon`

Start the emergency shortcut daemon (foreground, runs until signalled)

Usage:

kodachi-session-helper daemon [OPTIONS]

Options:

-h, --help: Print help information
-v, --version: Print version information
-n, --info: Display detailed information
-e, --examples: Show usage examples
--json: Output in JSON format
--json-pretty: Pretty-print JSON output
--json-human: Enhanced JSON output (like jq)
--verbose: Enable verbose output
--quiet: Suppress non-essential output

Examples:

kodachi-session-helper daemon

kodachi-session-helper daemon --json

`status`

Query the running daemon over its Unix socket

Usage:

kodachi-session-helper status [OPTIONS]

Options:

-h, --help: Print help information
-v, --version: Print version information
-n, --info: Display detailed information
-e, --examples: Show usage examples
--json: Output in JSON format
--json-pretty: Pretty-print JSON output
--json-human: Enhanced JSON output (like jq)
--verbose: Enable verbose output
--quiet: Suppress non-essential output

Examples:

kodachi-session-helper status

kodachi-session-helper status --json

`reload`

Send SIGHUP to the running daemon to reload its configuration

Usage:

kodachi-session-helper reload [OPTIONS]

Options:

-h, --help: Print help information
-v, --version: Print version information
-n, --info: Display detailed information
-e, --examples: Show usage examples
--json: Output in JSON format
--json-pretty: Pretty-print JSON output
--json-human: Enhanced JSON output (like jq)
--verbose: Enable verbose output
--quiet: Suppress non-essential output

Examples:

kodachi-session-helper reload

kodachi-session-helper reload --json

Operational Scenarios

Scenario-oriented workflows generated from the binary's built-in -e --json examples.

Scenario 1: Quick Start

Start the emergency shortcut daemon in your desktop session, then confirm the shortcuts armed.

Step 1: Start the emergency shortcut daemon in the foreground

kodachi-session-helper daemon

Expected Output: Preflight checks pass, the X11 key grabs register, the status socket opens, and the daemon enters its event loop

Note

Run it as your desktop user, NOT as root (root exits with code 3). It needs an X11 session (a Wayland session exits with code 5) and membership of the 'input' group for raw /dev/input corroboration.

Step 2: Confirm the daemon is up and see which shortcuts are armed

kodachi-session-helper status

Expected Output: Running state, PID, armed shortcut list, evdev state and any lockdown countdown

Note

Exits non-zero when no daemon is running, so a script can use it as a liveness probe.

Step 3: The same check, machine readable (this is what the dashboard calls)

kodachi-session-helper status --json

Expected Output: JSON envelope with the running flag, the armed shortcuts and the daemon capabilities

Scenario 2: Running the Daemon

What the daemon needs from the session, what it opens, and how it behaves when one is already running.

Step 1: Start the daemon with machine-readable output

kodachi-session-helper daemon --json

Expected Output: JSON envelope. If a daemon is already running it reports already_running with that daemon's PID and socket path instead of starting a second one

Note

The daemon is single-instance: it detects a live socket and refuses to duplicate itself.

Step 2: Start the daemon from an autostart script or user unit that does not inherit DISPLAY

DISPLAY=:0 kodachi-session-helper daemon

Expected Output: Daemon connects to the named X11 display and registers its grabs there

Note

DISPLAY defaults to :0. XDG_RUNTIME_DIR decides where the socket, the config file and the session-token digest are written; when it is unset or not writable the daemon falls back to <execution folder>/tmp.

Scenario 3: Status and Socket

Status is served over a Unix domain socket at $XDG_RUNTIME_DIR/kodachi-session-helper.sock (fallback: <execution folder>/tmp/kodachi-session-helper.sock). No network is involved.

Step 1: Indented status JSON, easier to read by eye than the compact form

kodachi-session-helper status --json --json-pretty

Expected Output: Pretty-printed status envelope with one field per line

Step 2: Use the exit code to alert when the emergency shortcuts are not armed

kodachi-session-helper status || echo 'session helper is DOWN'

Expected Output: Either the status report, or the fallback message when the daemon is not running

Note

status exits 1 when the socket is absent, which is the state in which the panic shortcuts do nothing.

Scenario 4: Signals and Lifecycle

There is no 'stop' subcommand: the daemon's lifecycle is driven by signals. SIGHUP reloads the configuration, SIGTERM shuts it down cleanly.

Step 1: Re-read the configuration and re-register the key grabs without restarting

kodachi-session-helper reload

Expected Output: SIGHUP sent to daemon (PID <N>)

Note

Exits 1 when the daemon is not running. The configuration file lives at $XDG_RUNTIME_DIR/kodachi-session-helper.json.

Step 2: The same reload, machine readable, for the dashboard

kodachi-session-helper reload --json

Expected Output: JSON envelope carrying success:true and the message "SIGHUP sent to daemon (PID <N>)"

Step 3: Reload by signalling the process directly, when the helper is not on PATH

kill -HUP $(pgrep -x kodachi-session-helper)

Expected Output: Daemon re-reads its configuration and re-registers the key grabs

Note

Same effect as 'reload'. Prefer 'reload': it takes the daemon PID from the session-token digest file rather than matching on the process name.

Step 4: Stop the daemon cleanly

kill -TERM $(pgrep -x kodachi-session-helper)

Expected Output: Daemon releases its X11 key grabs, zeroizes the session token in memory and exits

Note

This DISARMS the emergency shortcuts. Until the daemon is started again, the panic key combinations do nothing.

Scenario 5: Program Information

The standard Kodachi meta-flags. Each of them also works after a subcommand.

Step 1: List the daemon's features, security properties and system requirements

kodachi-session-helper -n

Expected Output: Feature list (key grabs, evdev corroboration, hold-to-trigger, session token, lockdown), plus the X11 and input-group requirements

Step 2: Version as JSON for a build or health check

kodachi-session-helper --version --json

Expected Output: JSON version envelope with the version, build date and git commit

Step 3: Help for one subcommand, including the SIGHUP and SIGTERM contract

kodachi-session-helper daemon -h

Expected Output: Help for the daemon subcommand only, not the top-level listing

Note

Per-subcommand -h and -e work for daemon, status and reload.

Environment Variables

Variable	Description	Default	Values
`DISPLAY`	X11 display to connect to	:0	:0, :1, etc.
`XDG_RUNTIME_DIR`	Runtime directory for the status socket, the config file and the session-token digest. Falls back to <execution folder>/tmp when it is unset or not writable	/run/user/<uid>	Directory path

Exit Codes

Code	Description
0	Success
1	General error (includes: daemon not running for status/reload)
2	Invalid arguments
3	Permission denied (running as root)
4	X11 not available
5	Wayland session (unsupported)