Password Pusher: self-hosted one-time secret links with an audit trail

The problem Password Pusher solves, and who it is actually for

Passing a credential to a colleague is the weak point in most access workflows. Chat, email and ticket comments keep the secret in a searchable archive long after the person has used it. Password Pusher takes the opposite position: the secret exists as a link, the link has a view count and a clock, and once either runs out the data is gone. The README describes the app as a way to "push a password, note, file, or URL" and states that sensitive data is removed entirely once expired.

The audience is narrower than the marketing suggests. Managed service providers appear in the repository topics, and the audit log feature makes sense in that setting: an MSP handing a local admin password to a client technician wants a record of who viewed it and when. The same applies to platform teams that already run their own infrastructure. If your organisation has no place to run a container and no domain to point at it, the hosted service at pwpush.com is the path the README points to instead. Password Pusher is not a password manager. It does not store credentials for reuse, it does not fill login forms, and the README never claims otherwise. Treating it as one will leave you without an inventory of your accounts.

How a push is created, stored and destroyed

The mechanism is a Ruby web application backed by a database, or by nothing at all if you choose the ephemeral image. When you create a push, the app stores the payload encrypted and generates a URL that carries the retrieval path. The recipient opens that URL, optionally enters a passphrase the sender set, and reads the secret. Each view is counted. When the count or the expiry time is reached, the record is deleted rather than flagged, which is why the README describes expiry as deletion and not as hiding.

Encryption at rest is configured through PWPUSH_MASTER_KEY. The Compose file is explicit that if the key is omitted, a default encryption key is used, and that production deployments should generate their own. There is also a rotation path: old keys go into PWPUSH_MASTER_KEY_PREVIOUS as a comma-separated list so existing pushes can still be decrypted. That is a sensible design, and it also means key management is your responsibility. Lose the key and the stored pushes are unreadable; the project cannot recover them for you.

Two deployment shapes exist in the repository. The standard image persists to a database, which is what you want if the audit log matters. The ephemeral image runs stateless, which suits a quick internal instance where nothing needs to survive a restart. The README lists both, and the choice changes what your backup story looks like. Audit logging is presented as tracking what was shared and who viewed it, with logins optional. Without logins enabled, the audit trail records events on links, not identities.

Installing with docker compose and pushing your first secret

The repository ships a docker-compose.yml whose header comment is the install guide. The most important step, in the project's own words, is setting TLS_DOMAIN so the app provisions and renews HTTPS certificates through Let's Encrypt. You point your domain's DNS at the host first, then set the value, then start the stack. The Compose file also notes that configuration can be set directly in the environment block or kept in an external .env file by enabling env_file.

Start by editing the TLS_DOMAIN line in docker-compose.yml to match the hostname you control:

x-env: &x-env
  environment:
    TLS_DOMAIN: "pwpush.example.com"
    PWPUSH_MASTER_KEY: ""

Then bring the stack up. The header comment gives this as the start command, and the app should become reachable at the domain you set once certificates are issued:

docker compose up -d

To stop the instance, the same file documents the reverse:

docker compose down

Once the page loads, create a push in the web UI: choose the type, paste the secret, set a view limit or an expiry, and optionally add a passphrase. You receive a link to send through whatever channel you already use. The recipient sees a delivery page the README describes as unbranded, with no logos or unrelated links. For scripted use, the project documents a JSON API under /api/v2 with create, retrieve, audit, active and expired endpoints, and the older /p, /f and /r routes remain available for backwards compatibility. An official CLI lives in a separate repository, pglombardo/pwpush-cli, and the docs site lists third-party tools.

Where Password Pusher is the wrong tool

The deletion model is the feature and the hazard. Because expired pushes are removed rather than archived, an expired link is not recoverable, and the README does not document any restore path for a single push. If your process needs the secret to remain retrievable for a compliance hold, this design works against you.

There is also a real gap in what the README covers. It documents the environment variables for TLS, the master key and SMTP, and it links to a configuration page on docs.pwpush.com, but the README itself does not walk through backup and restore of the backing database, nor does it describe what happens to in-flight links during an upgrade. The v2.0 upgrade guide exists in the repository as UPGRADE-2.0.md, which tells you a major version did change configuration, and that is a signal to read the migration notes before pulling a new tag rather than after.

Finally, consider the trust boundary. Self-hosting means the secrets sit on your infrastructure, encrypted with a key you manage. That is better than a chat log, but it is still a server you have to patch, and the app is a public-facing web service. If nobody on your team owns that host, the hosted service is the more honest choice.

Password Pusher compared with an encrypted pastebin

The closest alternative category is the encrypted pastebin, and the difference is in what the link enforces. A pastebin generally gives you a URL and, at best, an expiry timer. Password Pusher adds a view counter as a first-class control, so a link can be valid for exactly one read regardless of how much time passes. It also adds a passphrase layer, an audit log, and an API with endpoints for listing active and expired pushes, which a pastebin typically does not expose.

The trade-off runs the other way too. A pastebin is usually a single binary or a small container with no database, no SMTP configuration and no encryption key to manage. Password Pusher is a full Rails application with a Gemfile, a Yarn build for its Bootstrap themes, and a database in the persistent configuration. If you want the smallest possible surface for occasionally sharing a snippet, the pastebin wins on operational cost. If you need to answer the question of who opened a credential and when, Password Pusher is built around that question and the pastebin is not.

Maintenance, licensing and what an upgrade costs

The repository is not archived, and the last push was on 2026-09-10, so this is a project that is receiving changes now. Recent releases are small and specific: v2.11.6 on 2026-09-04 is described as dependency and security updates, v2.11.5 added pagination metadata headers to API list endpoints, and v2.11.4 fixed Devise validation errors after Turbo auth form submissions. That pattern suggests steady maintenance rather than a rewrite in progress, and it also means upgrades are frequent enough that you should pin a tag rather than track master.

Licensing is Apache-2.0, taken from the LICENSE file at the repository root. That permits commercial self-hosting and modification, and it does not come with warranty or support obligations from the author. The README is candid that a paid Self-Hosted Pro edition exists alongside the open source code, and that Pro features are periodically migrated into the OSS repository. If you build a workflow on a Pro-only capability, read the editions page on docs.pwpush.com before you commit, because the migration timing is not something the README states. None of this is legal advice; if your organisation has licence review, the Apache-2.0 text is the document to hand over.

The upgrade cost is mostly configuration drift. A major version already required a migration guide, and the Compose file centralises settings in one environment block, so the practical work is diffing your env vars against Configuration.md in the repository before each bump.

Editorial conclusion

Adopt Password Pusher if you already run Docker and need an auditable, self-destructing link for credentials instead of pasting them into chat. Skip it if you want a password vault, or if you cannot terminate TLS on a domain you control, since the Compose quick start is built around TLS_DOMAIN and Let's Encrypt. Before rolling it out, verify two things yourself: that PWPUSH_MASTER_KEY is set to a key you generated rather than the documented default, and that your backup captures the database, because the README says expired pushes are deleted entirely.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. pglombardo/PasswordPusher on GitHub
3. Project website
4. README
5. Releases