COALBOX Documentation

Introduction

Overview of the Coalbox password manager.

Coalbox

Local-first, open-format password manager. Part of The Cinder Project.

Your vault lives on your machine. No account, no server, no internet required. The .emberkeys format is fully documented and open — you are never locked in.

What is Coalbox?

Coalbox is a password manager that runs entirely on your local machine. It stores your credentials in a single encrypted .emberkeys file that you control. No cloud service, no subscription, no vendor lock-in.

Principles

No trackers. No telemetry. No accounts. No BS. Coalbox never phones home. Ever.
Local-first. Your vault is a single encrypted file you control. Sync it however you want.
Open format. .emberkeys is fully documented. Any tool can read it.
Build from source. Transparency means you verify what you run.

Features

Vault Management

Create, unlock, lock vaults
AES-256-GCM encryption with Argon2id key derivation
Auto-lock after configurable inactivity

Entry Types

Login — username, password, URL, TOTP
Authenticator — standalone 2FA codes, separated from passwords
Secure Note — freeform text
Payment Card — cardholder, number, expiry, CVV, PIN
Identity — name, email, phone, address

Password Generator

Character mode — configurable length, uppercase, lowercase, numbers, symbols
Passphrase mode — EFF large wordlist (7776 words), configurable word count, separator, capitalization

Import / Export

Import from CSV, Bitwarden JSON, KeePass XML, 1Password 1PUX
Export to plaintext JSON
Auto-format detection, duplicate detection

Entry Management

Custom fields (text, hidden, URL, date)
Tags and favourites
Search across all entries
Password history (previous versions retained)

CLI & Scripting

JSON output for all commands (--json)
Quiet mode (--quiet) for minimal output
Field extraction (get --field password)
Entry filtering (list --tag work --type login)
Consistent exit codes (0 success, 1 error)

TOTP & Security

TOTP code generation (RFC 6238, SHA-1/SHA-256)
Breach checking via HaveIBeenPwned (k-anonymity)
Vault audit for compromised passwords

WebUI

beautifully redesigned localhost web interface (axum, vanilla JS, Tailwind CSS, Lucide icons)
Full vault management via browser
Dedicated tab for Authenticator codes
Password generator with live preview
TOTP display with auto-refreshing animated countdown timers
WebSocket real-time state

Quick Start

# Create a vault
coalbox create ~/vault.emberkeys

# Generate a password
coalbox generate -l 32

# Generate a passphrase
coalbox generate --passphrase --words 6

# Import from Bitwarden
coalbox import ~/bitwarden.json -f bitwarden -v ~/vault.emberkeys

# List entries
coalbox list -v ~/vault.emberkeys

# Export vault
coalbox export ~/backup.json -v ~/vault.emberkeys

# Start the WebUI
coalbox-web --vault ~/vault.emberkeys

Requirements

Rust 1.85+ (for building)
No runtime dependencies beyond glibc

Project	Role
cpac	Package trust layer (distributes Coalbox)
ember-browser	Browser with native Coalbox integration

Made By

Developer/Maintainer: Sabeeir Sharrma

Made under The Cinder Project — Burn all the Blind Spots

Installation

How to install Coalbox.

Installation

Coalbox runs on any system with Rust installed. No external dependencies required.

Quick Install (Recommended)

One command to build and install coalbox from source:

curl -sSf https://thecinderproject.qd.je/coalbox/install.sh | bash

This script will:

Detect if Rust is already installed on your system
If not, install Rust temporarily just for building
Clone and build coalbox from source
Install the binary to /usr/local/bin
If Rust was not present before, automatically remove it after installation

No dependencies are left behind. The script is fully transparent — you can review it before running:

curl -sSf https://thecinderproject.qd.je/coalbox/install.sh -o install.sh
less install.sh
bash install.sh

Build from Source

If you prefer to build manually:

git clone https://github.com/SabeeirSharrma/coalbox.git
cd coalbox
cargo build --release

The binary will be at target/release/coalbox.

Optional: Install to PATH

sudo cp target/release/coalbox /usr/local/bin/coalbox

Verify Installation

coalbox --version
# coalbox 0.3.0

Pre-built Binaries

GitHub Releases include pre-built binaries for x86_64 and aarch64 Linux.

These binaries are provided for SHA-256 verification only — do not download or use them directly. Coalbox must be built from source to ensure transparency and reproducibility.

Requirements

Rust 1.85+ (edition 2024)
No runtime dependencies beyond glibc

Platform Support

Platform	Status
x86_64 Linux	Supported
aarch64 Linux	Supported
Other platforms	Build from source

Configuration

Coalbox configuration options.

Configuration

Coalbox uses a TOML configuration file.

Config Location

Standalone: ~/.config/coalbox/coalbox.toml
Ember integration: ember.toml (under [coalbox] section)

Options

[coalbox]
# Path to vault file
vault_path = "~/.local/share/coalbox/vault.emberkeys"

# Auto-lock after N minutes of inactivity (0 = never)
auto_lock_minutes = 5

# Lock when system suspends
lock_on_suspend = true

# Clear clipboard after N seconds
clipboard_clear_seconds = 30

# Enable breach checking (requires internet)
breach_check_enabled = true

# Enable autofill (Ember integration only)
autofill_enabled = true

# Only autofill on HTTPS (Ember integration only)
autofill_https_only = true

# Default password generator length
generator_default_length = 20

# Default: include symbols in generator
generator_default_symbols = true

Defaults

If no config file exists, Coalbox uses these defaults:

Setting	Default
`vault_path`	`~/.local/share/coalbox/vault.emberkeys`
`auto_lock_minutes`	`5`
`lock_on_suspend`	`true`
`clipboard_clear_seconds`	`30`
`breach_check_enabled`	`true`
`autofill_enabled`	`true`
`autofill_https_only`	`true`
`generator_default_length`	`20`
`generator_default_symbols`	`true`

Vault Format

The .emberkeys vault file format specification.

.emberkeys Vault Format

The vault is a single encrypted file with the .emberkeys extension. The format is open, versioned, and fully documented. Third-party implementations are encouraged.

File Structure

[4 bytes]   Magic: 0x454D424B ("EMBK")
[2 bytes]   Format version (currently 0x0001)
[16 bytes]  Argon2id salt
[12 bytes]  AES-256-GCM nonce
[4 bytes]   Encrypted payload length
[N bytes]   Encrypted payload (JSON)
[16 bytes]  AES-256-GCM authentication tag

Total header size: 38 bytes.

Decrypted Payload

The encrypted payload is a JSON object:

{
  "version": 1,
  "created": "2025-01-01T00:00:00Z",
  "modified": "2025-01-01T00:00:00Z",
  "entries": [
    {
      "id": "uuid-v4",
      "entry_type": "login",
      "title": "Example",
      "url": "https://example.com",
      "username": "user@example.com",
      "password": "...",
      "totp_secret": "...",
      "notes": "...",
      "tags": ["work"],
      "favourite": false,
      "custom_fields": [
        {
          "name": "API Key",
          "field_type": "hidden",
          "value": "secret123"
        }
      ],
      "card": null,
      "identity": null,
      "password_history": [
        {
          "password": "old_password",
          "changed_at": "2025-01-01T00:00:00Z"
        }
      ],
      "created": "2025-01-01T00:00:00Z",
      "modified": "2025-01-01T00:00:00Z"
    }
  ]
}

Entry Types

Standard login credentials.

{
  "entry_type": "login",
  "title": "GitHub",
  "url": "https://github.com",
  "username": "user@example.com",
  "password": "secret123",
  "totp_secret": "JBSWY3DPEHPK3PXP"
}

Note

Secure note for freeform text.

{
  "entry_type": "note",
  "title": "WiFi Password",
  "notes": "Network: MyWiFi\nPassword: secret123"
}

Card

Payment card details.

{
  "entry_type": "card",
  "title": "Visa",
  "card": {
    "cardholder": "John Doe",
    "number": "4111111111111111",
    "expiry": "12/25",
    "cvv": "123",
    "pin": "1234"
  }
}

Identity

Personal identity information.

{
  "entry_type": "identity",
  "title": "Personal",
  "identity": {
    "first_name": "John",
    "middle_name": "M",
    "last_name": "Doe",
    "email": "john@example.com",
    "phone": "+1-555-0123",
    "address_line1": "123 Main St",
    "address_line2": "Apt 4",
    "city": "Springfield",
    "state": "IL",
    "postal_code": "62701",
    "country": "US"
  }
}

Authenticator

Standalone 2FA (TOTP) codes.

{
  "entry_type": "authenticator",
  "title": "Google Backup Code",
  "totp_secret": "JBSWY3DPEHPK3PXP"
}

Custom Fields

Entries can have custom fields with these types:

Type	Description
`text`	Plain text
`hidden`	Masked in UI (like passwords)
`url`	URL link
`date`	Date value

Encryption

Cipher: AES-256-GCM (authenticated encryption)
Key derivation: Argon2id (memory: 64MB, iterations: 3, parallelism: 4)
Salt: 16 bytes, randomly generated per vault
Nonce: 12 bytes, randomly generated per save operation
Master password: never stored, never written to disk, zeroed from memory on lock

CLI Reference

Coalbox command-line interface reference.

CLI Reference

Usage

coalbox <COMMAND> [OPTIONS]

Commands

create

Create a new vault.

coalbox create [PATH]

Argument	Default	Description
`PATH`	`~/.local/share/coalbox/vault.emberkeys`	Path for the new vault file

Example:

coalbox create ~/my-vault.emberkeys

get

Get an entry by title or URL.

coalbox get <QUERY> [-v <VAULT>] [-f <FIELD>]

Argument	Description
`QUERY`	Entry title, URL, or search term
`-v, --vault`	Vault file path
`-f, --field`	Extract a single field (title, username, password, url, totp, notes)

Examples:

# Full entry display
coalbox get github -v ~/vault.emberkeys

# Just the password (great for scripting)
coalbox get github -f password

# JSON output for a single field
coalbox get github --field password --json

list

List all entries in the vault.

coalbox list [-v <VAULT>] [-t <TAG>] [-T <TYPE>]

Option	Description
`-v, --vault`	Vault file path
`-t, --tag`	Filter by tag
`-T, --type`	Filter by type (login, note, card, identity, authenticator)

Examples:

# List all entries
coalbox list -v ~/vault.emberkeys

# List only login entries
coalbox list --type login

# List entries with a specific tag
coalbox list --tag work

# JSON output for scripting
coalbox list --json | jq '.[].title'

generate

Generate a password or passphrase.

coalbox generate [OPTIONS]

Character mode (default):

Option	Default	Description
`-l, --length`	`20`	Password length
`--uppercase`	`true`	Include uppercase letters
`--lowercase`	`true`	Include lowercase letters
`--numbers`	`true`	Include numbers
`--symbols`	`true`	Include symbols

Passphrase mode:

Option	Default	Description
`--passphrase`	`false`	Generate passphrase instead of password
`-w, --words`	`6`	Number of words
`-s, --separator`	`" "`	Separator between words
`--capitalize`	`true`	Capitalize first letter of each word
`--number`	`false`	Append a random number

Examples:

# Generate a 32-character password
coalbox generate -l 32

# Generate a 6-word passphrase
coalbox generate --passphrase

# Generate a 4-word passphrase with dashes, no caps
coalbox generate --passphrase -w 4 -s "-" --no-capitalize

# JSON output for scripting
coalbox generate -l 32 --json
# {"password":"aB3$kL9#mN2@pQ5&rS8!"}

coalbox generate --passphrase --json
# {"passphrase":"correct horse battery staple"}

info

Show vault information.

coalbox info [-v <VAULT>]

Option	Description
`-v, --vault`	Vault file path

Example:

coalbox info -v ~/vault.emberkeys

lock

Lock the vault (daemon mode). Not yet implemented.

coalbox lock

totp

Show TOTP code for an entry.

coalbox totp <QUERY> [-v <VAULT>]

Argument	Description
`QUERY`	Entry title, URL, or search term
`-v, --vault`	Vault file path

Example:

coalbox totp github -v ~/vault.emberkeys
# GitHub
#   TOTP: 482903 (12s remaining)

audit

Check all passwords in the vault against HaveIBeenPwned.

coalbox audit [-v <VAULT>]

Option	Description
`-v, --vault`	Vault file path

Example:

coalbox audit -v ~/vault.emberkeys
# Checking passwords against HaveIBeenPwned...
#
# Vault audit complete:
#   Total entries:       15
#   Entries with pass:   8
#
# ✓ No breached passwords found!

check

Check a single password against HaveIBeenPwned.

coalbox check [PASSWORD]

Argument	Description
`PASSWORD`	Password to check (or `-` to read from stdin)

Example:

coalbox check "password123"
# ⚠ Password found in 12345 data breaches!
#   Do not use this password.

import

Import entries from an external file.

coalbox import <FILE> [-f <FORMAT>] [-v <VAULT>]

Argument	Default	Description
`FILE`	—	File to import (required)
`-f, --format`	`auto`	Format: `csv`, `bitwarden`, `keepass`, `1password`, `auto`
`-v, --vault`	default	Vault file path

Supported formats:

Format	Extension	Description
CSV	`.csv`	Flexible column mapping (name/title, user/username/login/email, pass/password/pwd, url/website/site, notes/note/comment)
Bitwarden JSON	`.json`	Full Bitwarden vault export
KeePass XML	`.xml`	KeePass XML export
1Password 1PUX	`.1pux`	1Password export archive

Examples:

# Import from CSV (auto-detect format)
coalbox import ~/export.csv

# Import from Bitwarden JSON
coalbox import ~/bitwarden.json -f bitwarden

# Import into a specific vault
coalbox import ~/keepass.xml -f keepass -v ~/other-vault.emberkeys

export

Export all entries to a plaintext JSON file.

coalbox export <FILE> [-v <VAULT>]

Argument	Description
`FILE`	Output file path
`-v, --vault`	Vault file path

Example:

# Export vault to JSON
coalbox export ~/backup.json

# Export from a specific vault
coalbox export ~/backup.json -v ~/other-vault.emberkeys

Global Options

Option	Description
`--json`	Output in JSON format (all commands)
`-q, --quiet`	Suppress non-essential output
`-h, --help`	Print help
`-V, --version`	Print version

Security

Coalbox security model and design decisions.

Security Model

Coalbox is designed with security as a core principle. This document explains the security model and design decisions.

Encryption

Cipher: AES-256-GCM (authenticated encryption)
Key derivation: Argon2id with tuned parameters:
- Memory: 64MB
- Iterations: 3
- Parallelism: 4
- Output: 32 bytes
Salt: 16 bytes, randomly generated per vault
Nonce: 12 bytes, randomly generated per save operation
Master password: never stored, never written to disk, zeroed from memory on lock

Memory Security

Decrypted vault data is held in memory only while unlocked
Memory is explicitly zeroed on lock using Rust’s zeroize crate
The process does not swap vault data to disk (mlock where supported)

Auto-lock

Vault auto-locks after configurable inactivity:

[coalbox]
auto_lock_minutes = 5    # 0 = never auto-lock
lock_on_suspend = true   # lock when system suspends

Clipboard Security

When a password is copied to clipboard:

Clipboard is cleared automatically after 30 seconds (configurable)
Coalbox does not retain clipboard history

Breach Checking

Checks passwords against the HaveIBeenPwned Pwned Passwords database using the k-anonymity model:

Only the first 5 characters of the SHA-1 hash of the password are sent to the API
The full password never leaves the device
Can be disabled entirely in settings for air-gapped use

What Coalbox Never Does

Never sends vault data, passwords, or master password to any server
Never phones home for analytics, telemetry, or licensing
Never requires an account or registration
Never stores the master password or a derivative of it

Build Verification

Coalbox is open source and distributed via source. The recommended way to install is building from source:

git clone https://github.com/SabeeirSharrma/coalbox.git
cd coalbox
cargo build --release

Pre-built binaries are provided for checksum verification only. See Installation for details.

COALBOX Documentation

Introduction

Coalbox

What is Coalbox?

Principles

Features

Vault Management

Entry Types

Password Generator

Import / Export

Entry Management

CLI & Scripting

TOTP & Security

WebUI

Quick Start

Requirements

Related Projects

Made By

Installation

Installation

Quick Install (Recommended)

Build from Source

Optional: Install to PATH

Verify Installation

Pre-built Binaries

Requirements

Platform Support

Configuration

Configuration

Config Location

Options

Defaults

Vault Format

.emberkeys Vault Format

File Structure

Decrypted Payload

Entry Types

Login

Note

Card

Identity

Authenticator

Custom Fields

Encryption

CLI Reference

CLI Reference

Usage

Commands

create

get

list

generate

info

lock

totp

audit

check

import

export

Global Options

Security

Security Model

Encryption

Memory Security

Auto-lock

Clipboard Security

Breach Checking

What Coalbox Never Does

Build Verification