Configuration & Files

Kosh has no config flags, no config DSL and no daemon. Its entire persistent state is two things: a small JSON config file and one encrypted SQLite file per profile.

---

On-disk layout

Everything lives under ~/.kosh:

• Directory~/.kosh/

  • config.json which profile is active
  • Directoryprofiles/

    • default.db vault + credentials, master password A
    • work.db vault + credentials, master password B
    • personal.db vault + credentials, master password C

On Windows, ~ resolves to %USERPROFILE%, so the path is C:\Users\<you>\.kosh.

Permissions

Path	Mode	Notes
~/.kosh/	0700	Owner only
~/.kosh/profiles/	0700	Owner only
~/.kosh/config.json	0600	Owner read/write

Modes are applied on creation. They are advisory on Windows, where NTFS ACLs govern access instead.

---

config.json

The only user-facing configuration Kosh keeps is which profile is active:

{ "active_profile": "default" }

• Written by kosh use and kosh profile create.
• Created automatically with {"active_profile":"default"} the first time Kosh runs if it does not exist.
• The value is a profile name, which is also the filename stem under profiles/ — work means ~/.kosh/profiles/work.db. Names are cleaned up on creation and capped at 252 characters, so the filename always fits the 255-character limit once .db is added; see Naming profiles.

You can edit it by hand, but there is no reason to: kosh use does the same thing and validates that the profile exists.

---

Profile vault files

Each profiles/<name>.db is a self-contained encrypted SQLite database holding:

• the vault row — Argon2id salt, Curve25519 public key, and the vault’s private key encrypted under your master password;
• the credentials — each with its own ephemeral public key, nonce and ciphertext;
• a schema_migrations table tracking which schema migrations have been applied.

The database is opened with PRAGMA secure_delete=ON, so deleted rows are overwritten in place rather than merely unlinked.

Profiles share nothing. Each has its own salt, its own keypair and its own master password — see Profiles and Encryption Architecture.

Backing up

Copy the file. A profile vault is a single file with no sidecar journals to worry about once Kosh has exited:

cp ~/.kosh/profiles/work.db /path/to/backup/work.db

Restoring is the reverse. The backup is fully encrypted — its safety rests entirely on your master password, which is not stored in it.

Copying a vault does not copy access

A restored vault still needs the master password it was created with. Kosh cannot recover or reset it.

---

Environment variables

Variable	Values	Effect
KOSH_DEBUG	1, t, T, true, TRUE, True	Enables structured debug logging to stderr

Any value Go’s strconv.ParseBool accepts as true works. An unset variable, an unparseable value, or a falsy value all leave logging off.

KOSH_DEBUG=1 kosh list          # bash / zsh

$env:KOSH_DEBUG=1; kosh list    # PowerShell

See Troubleshooting.

Kosh reads HOME (or USERPROFILE on Windows) to locate ~/.kosh. It reads no other environment variables and honours no config-path override.

---

What Kosh never does

• No network requests. There is no telemetry, no sync, no update check. The binary contains no HTTP client for its own use.
• No writes outside ~/.kosh. Nothing is placed in /tmp, XDG_CONFIG_HOME, or the working directory.
• No secrets in argv. Every secret is collected through an interactive prompt, so nothing sensitive reaches your shell history or the process table.
• No secrets on stdout. Retrieved secrets go to the clipboard only.
• No CGO. The SQLite driver is pure Go, so the binary is statically linked and dependency-free.

---

Uninstalling

Remove the binary, then the data directory:

rm -rf ~/.kosh

This destroys every profile

Deleting ~/.kosh removes every vault and every credential in them, permanently. Back up ~/.kosh/profiles/ first if there is any chance you want the data back.