Skip to content
Field Manual

Documentation

Everything you need to deploy IronDome. From first install to daily ops — full command reference, auth modes, vault structure, and troubleshooting protocols.

Quick Start Commands Auth Modes Platforms Config Vault Files Live Demo Source Code Troubleshooting
01 / Quick Start

Three Commands to Operational

01

Install

$ pip install IronDome

Requires Python 3.8–3.13. That's it. No other dependencies required for core functionality.

02

Create Your Bunker

$ irondome create bunker

Follow the prompts to configure your vault:

  • > Set your master password
  • > Choose auth mode (biometric, bio+password, password only)
  • > Generate recovery code (SAVE THIS!)
03

Start Using

$ irondome open airspace # Authenticate $ bunker create # Add a password $ bunker open # View passwords $ bunker fortify # Backup your vault

Session persists for 30 minutes. Re-authenticate anytime with irondome open airspace.

02 / Command Reference

Full CLI Reference

System

irondome

Command
Description
irondome create bunker
First-time vault setup — generates keys, configures auth, saves recovery code
irondome open airspace
Authenticate and start a 30-minute session
irondome close airspace
Lock everything immediately — terminates session
irondome status
Display vault health, session state, and configuration info
Vault

bunker

Command
Alias
Description
bunker create
bunker -c
Add a new password entry to the vault
bunker open
bunker -o
List all stored password entries
bunker open [name]
bunker -o [name]
Search for entries matching the given name
bunker fortify
—
Create an encrypted backup of the vault
bunker settings
—
Open preferences — passwords length, timeouts, symbols
bunker
—
Launch interactive 9-option menu
03 / Authentication

Auth Modes

Choose your authentication posture during setup. You can change it later via bunker settings.

Biometric Only
Mode 1
  • > Cryptographically random vault key stored in OS keychain
  • > macOS Keychain / Windows Credential Manager / Linux libsecret
  • > Biometric authentication unlocks the keychain entry
  • > Fastest login experience — no password to type

Recovery requires the 24-character recovery code. Store it offline.

Recommended
Bio + Password
Mode 2
  • > Biometric is a GATE — you must pass it first
  • > Password still derives the key via PBKDF2
  • > Two fully independent factors required
  • > Most secure configuration available

Compromise of either factor alone is insufficient to unlock.

Password Only
Mode 3
  • > Traditional approach — master password derives all keys
  • > Key derivation via PBKDF2 with stored salt
  • > Works everywhere — no hardware requirements
  • > Good fallback when biometric hardware unavailable

Security depends entirely on master password strength.

04 / Platform Support

Compatibility Matrix

Biometric Integration

Platform
Technology
Package
macOS
Touch ID
pyobjc-framework-LocalAuthentication
Windows
Windows Hello
Built-in (subprocess)
Linux
fprintd
Built-in (subprocess)

Python Version Support

3.8
3.9
3.10
3.11
3.12
3.13 latest

All versions tested against the full feature set. Python 3.13 is the actively maintained target.

05 / Configuration

settings.json Reference

Stored at ~/.password_manager/settings.json. Edit directly or use bunker settings.

{ "default_password_length": 16, "include_symbols": true, "clipboard_timeout": 30, "session_timeout": 1800, "backup_on_change": false }
default_password_length integer default: 16

Length of generated passwords. Recommended: 16–32 characters.

include_symbols boolean default: true

Include special characters (!@#$...) in generated passwords.

clipboard_timeout integer default: 30

Seconds before the clipboard is automatically cleared after copy.

session_timeout integer default: 1800

Session expiry in seconds. Default 1800 = 30 minutes.

backup_on_change boolean default: false

Auto-create encrypted backup whenever vault contents change.

06 / Vault Files

Vault File Structure

All IronDome data lives under ~/.password_manager/. Never delete files manually.

~/.password_manager/ ├── password_manager.log ├── settings.json ├── backups/ │ └── .passwords_backup_*.enc └── secrets/ ├── .passwords.enc ├── salt.bin ├── .master_user.enc ├── .master_hash.enc ├── .login_attempts.dat └── .airspace.session
password_manager.log Append-only audit log of all vault operations.
settings.json User preferences — password length, timeouts, backup behavior.
backups/ Directory for encrypted backup files created by bunker fortify.
.passwords_backup_*.enc AES-128-CBC encrypted snapshots of the vault. Filename includes timestamp.
.passwords.enc Primary encrypted password store. Never edit directly.
salt.bin PBKDF2 salt. Unique per installation. Do not delete.
.master_user.enc Encrypted vault owner credential record.
.master_hash.enc Encrypted master password hash used for verification.
.login_attempts.dat Rate-limiting data — counts failed authentication attempts.
.airspace.session Active session token. Auto-deleted on session expiry.
Live Demo Available

Try It in Google Colab

No installation required. Run a fully interactive IronDome session directly in your browser. Authentication, vault creation, and command demos — all live.

Open in Colab

Google account required — free tier supported

08 / Source

Full Source Code

Complete IronDome implementation — browse the code directly.

07 / Troubleshooting

Common Issues

! Biometric not detected

Biometric authentication requires platform-specific hardware and software support. Check the following:

  • > macOS: Ensure Touch ID is enrolled in System Settings > Touch ID & Password
  • > Windows: Enable Windows Hello in Settings > Accounts > Sign-in options
  • > Linux: Install and configure fprintd — run sudo fprintd-enroll
  • > macOS only: Install the pyobjc package: pip install pyobjc-framework-LocalAuthentication
  • > Fallback: Switch to Mode 3 (Password Only) via bunker settings
! Session expired / Permission denied

Sessions expire after 30 minutes of inactivity (configurable via session_timeout in settings). Re-authenticate:

$ irondome open airspace

To increase session duration, edit session_timeout to a higher value (in seconds). Maximum recommended: 3600 (1 hour).

! Forgot master password

Zero-knowledge design: there is no server-side recovery.

If you lose your master password AND your recovery code, vault contents are permanently inaccessible. This is by design.

Recovery process using your 24-character recovery code:

  • 1. Locate your 24-character recovery code (stored offline at setup)
  • 2. Run: irondome create bunker and select "Recover from code"
  • 3. Enter your recovery code (XXXX-XXXX-XXXX-XXXX-XXXX-XXXX format)
  • 4. Set a new master password
  • 5. Your vault will be decrypted and re-encrypted with the new credential
? irondome command not found

The pip-installed scripts directory may not be in your PATH. Solutions:

# Verify install location $ python -m pip show IronDome # Run directly via module $ python -m irondome create bunker # Add pip scripts to PATH (macOS/Linux) $ export PATH="$HOME/.local/bin:$PATH"