Teampass: Self-Hosted Team Password Management

Teampass for shared credentials and access evidence

Teampass addresses a problem that appears when several people need access to the same credentials but spreadsheets, chat messages, and manually shared documents do not provide a controlled permission model. The README describes Teampass as an open-source credential vault that runs on your own server. It is aimed at individuals and homelab users, teams and small businesses, and enterprise or regulated organizations. Those audiences differ in their operational needs: a homelab operator may want a self-owned vault, a team needs controlled sharing and an access history, and a regulated organization may need recertification campaigns, compliance reports, and evidence export.

The README specifically says that Teampass records who accessed what and when. It also presents Secure Send for clients and contractors, a browser extension for daily autofill, and import support for Bitwarden, LastPass, 1Password, and KeePassXC. Those features place Teampass between a personal password manager and a simple shared credentials document. It is not merely a local password database intended to be copied between users. Its distinguishing design concern is controlled access to stored items through folders and roles.

The self-hosted model also changes the responsibility boundary. The README does not require an account with a hosted service, but it does require infrastructure and administration. The application is PHP with MySQL, and the repository includes Docker-related files and a published Docker Hub image. Operators therefore need to decide whether centralized access control is worth the server, database, key, and upgrade work that comes with running the service themselves.

Teampass encryption and permission architecture

The documented security model encrypts secrets with AES-256-GCM using random nonces and per-secret salts. Each secret is protected by a 256-bit object key. The README states that the private key used to unlock the object keys is derived from the user's password with PBKDF2-SHA256 at 600,000 iterations. This gives the project a layered credential model rather than storing plaintext passwords directly in the application database.

Access control is based on folders and roles. The README describes per-user key distribution in which each user holds an RSA-wrapped copy of each object key. The stated consequence is that removing an account revokes access instead of merely hiding the interface. That is an important distinction for a shared vault. A permission screen can prevent a user from seeing an item, whereas key distribution and revocation affect whether the user can decrypt it.

The README also documents lazy migration for encryption format upgrades. According to the project, format changes happen when data is accessed, so they do not require a planned maintenance window. This reduces operational scheduling, but it does not remove the need to understand migration behavior before upgrading a deployment. The README does not document a rollback procedure, so an operator should confirm recovery expectations before applying an upgrade.

For identity management, the project lists MFA, LDAP/AD with nested groups, and OAuth2 SSO. LDAP/AD and OAuth2 SSO are meaningful alternatives within Teampass. LDAP/AD integrates with an existing directory and nested groups, while OAuth2 delegates authentication to an OAuth2 provider. The choice depends on the organization's identity system rather than on the credential vault itself.

Installing Teampass and making the first vault entry

The README links to the official documentation, discussions, and Docker Hub, but its installation section does not include a complete installation command, environment-variable list, database initialization sequence, or first-login procedure. Because those details are not documented there, inventing a command would risk producing an incorrect deployment.

The repository does show the container's declared runtime foundation. Its Dockerfile is based on `php:8.3-fpm-alpine3.24` and declares a Teampass version build argument. This confirms that the Docker build uses PHP-FPM on Alpine, but it is not an end-to-end installation guide. The README also identifies the public Docker Hub project as the image location. Start with the documentation linked from the README and verify the required MySQL, PHP, web-server, storage, and environment settings there before building or launching a service.

For a first real use, the documented workflow is to create a vault on the server, authenticate the administrator, create the folder structure that matches the team's credential groups, assign roles and rights, and then add an item. The README's screenshots show item lists, item details, folder trees, roles, role rights, and role assignment. After the access policy is in place, import an existing export from Bitwarden, LastPass, 1Password, or KeePassXC if migration is required. The README does not specify the exact menu labels, import format settings, or default administrator credentials, so those must be taken from the linked documentation rather than guessed.

Teampass Docker packaging and dependency constraints

The repository includes a `Dockerfile`, a `docker/` directory, `teampass-docker-start.sh`, and a `DOCKER-HUB-README.md`. The Dockerfile states that PHP dependencies are shipped in `app/vendor/` with a production autoloader already generated. It also says that the image deliberately avoids running `composer install` during the build because doing so changed Composer's generated files and caused the file integrity check to report modifications.

That detail has an operational consequence. A custom image change that regenerates dependency files may interact with Teampass's integrity check, even if the change is intended to be routine. The Dockerfile contains build arguments and environment metadata, including `TEAMPASS_VERSION`, but the Dockerfile does not expose a complete `docker run` invocation or all required application variables. A deployment should therefore use the published image documentation rather than treating the Dockerfile as a ready-made command reference.

The repository also contains `composer.json`, `composer.lock`, `composer.phar`, PHPStan configuration, PHPUnit configuration, tests, and JavaScript package files. This indicates a conventional PHP application with separate application and front-end tooling. The README's PHP badge specifies PHP 8.2+, while the Dockerfile uses a PHP 8.3 FPM Alpine base. That difference may be relevant when reproducing a non-Docker installation, because the repository layout alone does not establish the complete system requirements for every deployment mode.

Teampass audit, identity, and maintenance boundaries

The audit and compliance features are aimed at organizations that need evidence about access, not just storage. The README lists a full audit trail, access recertification campaigns with immutable decisions, compliance reports, evidence export, data classification, and ownership. It also names a security policy, GitHub Security Advisories, CVE identifiers, and a security-hardening guide. Those resources indicate a documented route for reporting and reviewing security issues, but the README does not describe a backup schedule, database recovery drill, or upgrade rollback procedure.

The last repository push was on 2026-10-16, and the release list includes 3.2.3.0 on 2026-10-12, 3.2.2.8 on 2026-10-07, and 3.2.2.7 on 2026-10-04. The repository is not archived. This release and push history gives the project a recent maintenance signal, but it does not establish compatibility, upgrade risk, or the amount of work required to move a specific installation between versions. Those points require checking the documentation and release notes for the version in use.

The operational burden is higher than for a hosted password service because the operator owns the server, database, encryption material, access configuration, and update process. The README's security claims should be treated as project documentation, not as a substitute for reviewing `SECURITY.md`, the hardening guide, and the advisories before exposing a deployment to users. The GPL-3.0 license also matters for distribution and modification decisions, although `LICENSE.md` is the authority for obligations.

Why Teampass may not fit every password workflow

Teampass is the wrong choice when the requirement is a purely local personal vault with no shared administration. Its folder permissions, roles, keys, audit trail, and server deployment are meaningful for teams, but they add infrastructure and policy decisions to a workflow that could remain local. The README's import support for KeePassXC is useful for migration, but it does not make Teampass a file-based KeePassXC vault. The application is described as a PHP/MySQL service operated on a server.

A second limitation is the depth of operations documentation in the README. It names Docker Hub, documentation, security hardening, and advisories, but it does not provide a complete install command, required environment variables, backup procedure, or rollback instructions. An organization cannot safely infer those details from the repository entry list. The README also does not document browser support, database versions, deployment topology, or the exact behavior of every MFA and OAuth2 provider.

For identity integration, LDAP/AD and OAuth2 SSO should be compared against the organization's existing directory and authentication requirements. LDAP/AD is the documented option when nested directory groups matter. OAuth2 SSO is the documented option when the organization already uses an OAuth2 identity provider. Neither feature removes the need to define which vault folders and roles should exist, and neither should be assumed to be interchangeable without checking the documentation for the intended deployment.

Editorial conclusion

Adopt Teampass when the requirement is to operate a shared credential vault inside your own infrastructure and the team needs centralized permissions and access history. Do not choose it when nobody will maintain the PHP/MySQL deployment or manage its keys and upgrades. Before adoption, verify the security-hardening requirements, the identity integration path, and the exact backup and recovery procedure in the Teampass documentation.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. nilsteampassnet/TeamPass on GitHub
3. Project website
4. README
5. Releases