Skip to content New Self-host your password sync in 15 minutes Read more Menu Download OpenVireo

Most teams keep their deployment secrets in three places at once: a password manager for people, CI secrets for pipelines, and a .env file someone copied around in 2023. OpenVireo lets scripts and CI read the same vault people use, with a CLI called ov. Change a password in the vault, and the next deploy picks it up.

Service accounts: access without anyone’s password

Scripts shouldn’t sign in as you. An OpenVireo service account belongs to an organization, gets access to specific vaults (read only, or read and write), and signs in with a token that starts with ov_sa_.

An owner or admin creates one in the desktop app, in the organization window, and picks its vaults. The token is shown once: store it as a CI secret or on the server. A service account can have several tokens, each with its own name and expiry, so you can replace one without breaking the others.

Like every OpenVireo client, ov downloads the vault and decrypts it locally. The service account’s keys are sealed to it the same way a person’s are; our servers still only see encrypted files.

Install

ov is a single binary for Linux, macOS and Windows, with nothing else to install. Every release has a SHA256SUMS file signed with the OpenVireo release key; macOS builds are notarized, and Windows builds are signed. On Linux:

1v=0.11.0 p=linux-x64      # or linux-arm64, darwin-arm64, darwin-x64
2for f in "ov-$v-$p.tar.gz" SHA256SUMS SHA256SUMS.asc; do
3  curl -fLO "https://github.com/OpenVireo/openvireo-sdk/releases/download/v$v/$f"
4done
5gpg --verify SHA256SUMS.asc SHA256SUMS
6sha256sum --ignore-missing -c SHA256SUMS
7tar -xzf "ov-$v-$p.tar.gz" && sudo install "ov-$v-$p/ov" /usr/local/bin/

Referring to a secret

Every secret has an address:

1ov://<vault>/<group>/<entry>/<field>

For example, ov://Team%20Infra/Deploy/Database/password is the password of the Database entry in the Deploy group of the Team Infra vault. Spaces are percent-encoded. Fields are the usual ones (username, password, url, notes) or any custom field, like api_key.

Read one secret

1export OPENVIREO_SERVICE_ACCOUNT_TOKEN=ov_sa_…
2ov read ov://Team%20Infra/GitHub/password

Fill in a config file

ov inject replaces references in a template. Use {{ … }} when other text follows the reference:

1echo 'dsn: postgres://app:{{ ov://Team%20Infra/Deploy/Database/password }}@db/app' | ov inject
2ov inject -i config.yml.tpl -o config.yml       # the output file is created with mode 0600

Run a command with secrets in its environment

This is the one most people end up using. Write a .env template with references instead of values, and commit it:

1# .env.tpl
2DB_USER=ov://Team%20Infra/Deploy/Database/username
3DB_PASSWORD=ov://Team%20Infra/Deploy/Database/password

Then:

1ov run --env-file .env.tpl -- ./migrate.sh

ov run resolves the references, starts the command with them in its environment, and masks every secret in its output. If the script prints $DB_PASSWORD, the log shows <concealed by openvireo>. Masking works even when a value is split across two writes, and for each line of a multi-line secret like a private key. The command never sees your service account token, and ov run exits with the command’s own exit code.

Rotate a password

1ov rotate ov://Team%20Infra/Deploy/Database/password --generate --length 40

The old value goes into the entry’s history, so you can always get it back. If someone edits the same vault at the same time, the change is merged, not overwritten. A service account with read-only access is refused before anything is uploaded.

In GitHub Actions

There’s an action that does the same thing for a workflow:

1- name: Load secrets
2  uses: openvireo/openvireo-sdk/packages/[email protected]
3  with:
4    service-account-token: ${{ secrets.OPENVIREO_SERVICE_ACCOUNT_TOKEN }}
5  env:
6    DB_PASSWORD: ov://Team%20Infra/Deploy/Database/password
7    DATABASE_URL: postgres://app:{{ ov://Team%20Infra/Deploy/Database/password }}@db/app
8
9- run: ./deploy.sh      # $DB_PASSWORD and $DATABASE_URL are set; printing them shows ***

Every resolved value is masked in the logs before anything is exported, and the step fails if any reference can’t be resolved, so a job never runs with a missing secret.

Signed in as yourself

For your own scripts on your own computer, you can use ov with your account instead of a service account:

1ov login --email [email protected]
2ov read ov://Private/Bank/password
3ov share ov://Private/Wi-Fi --expires 1d       # a share link, from the terminal

It asks for your master password each time, and never stores it. For anything that runs unattended, use a service account.

Plans

Service accounts belong to organizations. The free organization plan includes one, Families one, Teams ten, and Business unlimited. See pricing.

Everything else, including ov connect (a local REST server for Kubernetes and other tools) and the SDK for your own code, is in the SDK docs.

Feedback

Please report any bugs you encounter at our GitHub issue tracker. See our contact page for further options.