Skip to content

Managing Secrets

Jump to bottom Edit New page
Ashley Davis edited this page Jun 14, 2026 · 15 revisions

Photosphere stores sensitive credentials in a secrets vault. By default the vault uses the OS keychain, macOS Keychain, Windows Credential Vault, or the Linux Secret Service (GNOME Keyring / KWallet), so secret values are protected by the operating system's own credential store rather than plain files on disk.

Secrets are used to store S3 credentials, encryption key pairs, and API keys. They can be linked to database entries so that credentials are resolved automatically when a database is opened.

Secret Types

Type Description Fields
S3 credentials Credentials for S3-compatible object storage Region, Access Key ID, Secret Access Key, Endpoint (optional)
Encryption key RSA key pair for encrypting and decrypting databases Private key PEM
API key API keys for external services (e.g. geocoding) API key value
Plain An arbitrary plaintext value Value

Each secret is identified by its name.

Vault Types

Photosphere supports two vault backends, selected with the PHOTOSPHERE_VAULT_TYPE environment variable.

Value Description
keychain Default. Stores secrets in the OS keychain.
plaintext Stores secrets as JSON files under ~/.config/photosphere/vault/. Useful for testing or environments where a keychain daemon is not available. 
# Force plaintext vault (e.g. in a script or CI environment)
export PHOTOSPHERE_VAULT_TYPE=plaintext

Keychain backend

Each platform uses a different tool to talk to the OS keychain:

Platform Tool Notes
macOS /usr/bin/security Built into every macOS installation. No extra setup required.
Linux secret-tool Talks to any Secret Service API daemon (GNOME Keyring, KWallet, etc.). Install with sudo apt install libsecret-tools on Debian/Ubuntu.
Windows PowerShell + Windows.Security.Credentials.PasswordVault Built into Windows 8 and later. Requires PowerShell on PATH.

If the required tool is missing, Photosphere will print an actionable error message and exit rather than failing silently.

Identifying Photosphere entries in the OS keychain UI

All secrets are stored with the service name photosphere and with the secret name prefixed by psi- (e.g. psi-s3test01). This prefix makes Photosphere entries easy to identify when browsing the OS keychain directly (Keychain Access on macOS, Credential Manager on Windows, or the GNOME Keyring viewer on Linux).

Plaintext backend

When PHOTOSPHERE_VAULT_TYPE=plaintext, secrets are stored as JSON files:

~/.config/photosphere/vault/

Each secret is stored as a JSON file named after the (percent-encoded) secret name with a .json extension. For example, a secret named production-key is stored as production-key.json. File permissions are set to 0600 (owner read/write only) and the directory to 0700 (owner only).

The secrets directory can be overridden with the PHOTOSPHERE_VAULT_DIR environment variable.

Desktop App

Open the secrets management page from the left sidebar by clicking Manage Secrets.

Secret List

The page displays all secrets, grouped by type. For each secret you can see its name and type. Secret values are not shown in the list.

Adding a Secret

Click Add Secret and choose the secret type. Fill in the fields:

  • S3 credentials: name, region, access key ID, secret access key, and optional endpoint URL (for non-AWS S3-compatible services like DigitalOcean Spaces or MinIO).
  • Encryption key: name, then paste or import a PEM-encoded private key. You can also generate a new RSA-4096 key pair directly. Only the private key PEM is persisted (as a raw string, not JSON-wrapped); the public key is derived from it whenever needed.
  • API key: name and the API key value.

Secrets can also be created inline when adding or editing a database entry, choose + Create new in the secret picker without leaving the database form.

Editing a Secret

Click the edit icon to update any field of a secret. The name and values can be changed; the type cannot be changed after creation.

Deleting a Secret

Click the delete icon to remove a secret. If any database entries reference the secret, a warning is shown listing the affected databases so you can update them first.

CLI

The psi secrets command group provides secret management from the command line.

List Secrets

psi secrets list

Displays all secrets with their name and type. Values are masked.

Add a Secret

psi secrets add

Interactive prompts for name, type, and value.

Secret names must be unique. If you try to add a secret with a name that is already in use, the command will error and no secret will be added.

When a secret name is not found (for example, when passing --encryption-key my-photos to psi dbs add and no secret with that name exists), the CLI displays fuzzy-matched suggestions, e.g. Did you mean: my-photo, my-photos-old?, to help correct typos.

View a Secret

psi secrets view                              # select from list
psi secrets view --name production-key

Shows the full value of a secret (with a confirmation prompt, since this displays sensitive data).

Edit a Secret

psi secrets edit                                              # select from list
psi secrets edit --name production-key
psi secrets edit --name production-key --yes --new-name production-key-2
psi secrets edit --name production-key --yes --value new-value

Prompts for a new name (pre-filled with the current name) and a new value (leave blank to keep the current one). Either or both can be changed. You can also supply the new value from a file with --value-file <path>.

Remove a Secret

psi secrets remove                              # select from list
psi secrets remove --name production-key

Removes the secret after confirmation. To remove every secret in the vault, use psi secrets clear.

Import an Encryption Key

psi secrets import
psi secrets import --yes --private-key /path/to/production-key.key

Reads a private-key PEM file and stores it as an encryption-key secret. The secret name is the filename with any .key suffix stripped (so production-key.key becomes a secret named production-key). Only the raw private PEM is stored; the public key is derived from it whenever needed.

Shared Secrets and Database Linking

Secrets linked to database entries are stored under a vault key name that you choose when you create the secret. The user-typed name is used directly as the vault key, no auto-generated IDs.

The desktop app and the CLI psi dbs add command both let you pick existing secrets or create new ones inline during database registration. When creating inline from psi dbs add / psi dbs edit, the secret name is inferred from the database name and secret type:

Secret type Inferred name
S3 credentials <dbname>:s3
Encryption key <dbname>:encryption
Geocoding API key <dbname>:geocoding

You are only prompted for an alternative name if the inferred name is already taken in the vault.

When a database entry has a linked secret (e.g. encryptionKey: "my-photos:encryption"), opening that database looks up my-photos:encryption in the vault and uses the credentials automatically, no -k flag needed.

Default S3 Fallback

When an S3 path is accessed and no database entry with linked credentials is found, psi looks for a vault secret named default:s3. This secret is created automatically the first time you go through the lazy interactive S3 setup prompt. It appears in psi secrets list and can be edited or removed like any other secret.

If AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables are set, the default:s3 vault secret is not consulted, the AWS SDK uses the environment variables directly.

Sharing

You can share individual secrets to another device over the LAN. This is useful for transferring credentials without manually copying vault files.

  • Desktop: Click Share on a secret to send it, or Receive Secret to receive one from another device.
  • CLI: Use psi secrets send and psi secrets receive.

See Sharing-Credentials for full details on how LAN sharing works and its security architecture.

Related Pages

Add a custom footer
Add a custom sidebar

Clone this wiki locally