Getting started

Install the varsafe CLI, sign in, store a secret and run your app with it, with no .env file on disk. About five minutes.

When you finish, your app’s read is in the audit log. From there the same setup scales out: invite your team with a role each, give your pipeline a token of its own, and connect your coding agent on a grant you approve.

Prerequisites

From zero to injected secrets

curl -fsSL https://varsafe.dev/install.sh | bash

varsafe --version

export PATH="$HOME/.varsafe/bin:$PATH"

apk add --no-cache libstdc++ libgcc

apk add --no-cache openssh-keygen

varsafe login

varsafe use

varsafe set DATABASE_URL

printf %s 'postgres://app:app@localhost:5432/app' | varsafe set DATABASE_URL --stdin

varsafe set TLS_PRIVATE_KEY --from-file ./server.key

varsafe set API_KEY --from-env BUILD_API_KEY

varsafe list               # keys only, values masked
varsafe get DATABASE_URL   # prints the value; the read is recorded

varsafe run -- sh -c 'echo "DATABASE_URL is ${DATABASE_URL:+set}"'

varsafe run -- npm run dev

Recap

Everything else is a variation on these. When in doubt, varsafe status shows which credential, project and environment the next command will use.

When a tool insists on a file

Most tools read their configuration from the environment, so varsafe run -- <tool> covers them. For one that will only read a file, write it to RAM rather than to disk:

varsafe export --plain --tmpfs -o app.env

--tmpfs puts the file in /dev/shm/ on Linux, readable by you only, and --plain is what lets the tool read it. Delete it when the tool is done. JSON, YAML and Docker formats are always plaintext; exporting lists them.

Without --plain, a .env export is encrypted, value by value, to its environment. That file is safe to commit or hand over, but it is not for a tool to read: varsafe run --env-file .env -- <command> opens it, for anyone allowed to read the environment. See encrypted .env files.

The same flow, scripted

These scripts run in our test suite, so they stay correct. They sign in the way automation does: VARSAFE_API_TOKEN holds an API token, so no varsafe login step is needed. VARSAFE_PROJECT is the script’s own variable, passed to -p; the CLI reads no project variable.

# docs-test: local-stack
# Store a secret and read it back.
set -euo pipefail

# No `varsafe login` here: VARSAFE_API_TOKEN is already in the environment and the
# CLI picks it up automatically. That is the only auth path that works on a
# headless runner, where `login` has no keychain to persist to.

# Set your default project and environment once
varsafe use -p "$VARSAFE_PROJECT" -e development

# Store a secret. The value comes in on stdin — passing it as an argument is
# refused, because arguments leak via shell history and `ps`.
printf %s 'postgres://app:app@localhost:5432/app' | varsafe set DATABASE_URL --stdin

# List keys (values stay hidden by default)
varsafe list

# Read a single value (pipe-friendly)
varsafe get DATABASE_URL > /dev/null

echo "OK:quickstart"

# docs-test: local-stack
# Inject secrets into a child process as environment variables — no file
# is ever written to disk.
set -euo pipefail

# VARSAFE_API_TOKEN in the environment authenticates every command below; `varsafe
# login` is neither needed nor possible on a headless runner (no keychain).
varsafe use -p "$VARSAFE_PROJECT" -e development

printf %s 'vsafe_example_run_inject_value' | varsafe set API_KEY --stdin

# The child process sees API_KEY; your shell never does.
varsafe run -- sh -c 'test -n "$API_KEY"'

# Only inject secrets matching a pattern
varsafe run --include 'API_*' -- sh -c 'test -n "$API_KEY"'

# --include can be repeated, and the patterns are unioned. This is the one check that
# exercises the real flag parsing rather than an already-joined string: repeats used to
# keep only the last pattern, so OTHER_TOKEN would have arrived empty here.
printf %s 'vsafe_example_run_inject_other' | varsafe set OTHER_TOKEN --stdin
varsafe run --include 'API_*' --include 'OTHER_*' -- \
  sh -c 'test -n "$API_KEY" && test -n "$OTHER_TOKEN"'

# `list` must agree with what `run` injects, so its own repeated flag is checked too.
test "$(varsafe list --include 'API_*' --include 'OTHER_*' --json | grep -c '"key"')" = 2

echo "OK:run-inject"

Your workspace

The dashboard shows every project and environment side by side, with the audit trail of who read or changed what:

You start with one project and three environments. Add a project per application or repository, and an environment for each extra stage, such as QA or a demo.

The slug is what you pass to -e. It is set when the environment is created and never changes: renaming an environment changes only the name people see.

Protected means only owners and admins can change its secrets; developers and operators can read them, viewers cannot. Production starts protected, and you can protect any environment in its settings. In the CLI, varsafe set and varsafe unset on a protected environment also ask you to type its slug to confirm, or take -y in automation.

A few things are quicker in the dashboard:

• Moving an existing project in. varsafe import .env brings a whole .env file in, after showing you its plan; the Add secrets card on the Secrets page takes a pasted or dropped file too. Move an existing .env into varsafe covers both, and cleaning up afterwards.
• Undoing a change. Each environment keeps its last 10 saved versions, and its history can be rolled back to before any of those changes, with a preview first.
• Comparing environments. See which keys staging has that production is missing before you release.

Bring your team

Invite teammates from the Teams page with Invite member, and give each a role: admin, developer, operator, viewer or billing. (Every team has exactly one owner, at first the person who created it; ownership can be transferred.) A developer can change development and staging but only read production; a viewer never sees production at all. The roles reference has the full matrix.

When someone leaves, removing them revokes their CLI logins, their agent grants and the API tokens they created, in one step. Onboard and offboard walks through both sides, including your teammate’s first day.

Run it in CI

A pipeline gets its own API token rather than someone’s login, so it reaches only what its job needs and shows up under its own name in the audit log.

1. In the dashboard, open API tokens and click Create API Token.
2. Name it after the pipeline, limit it to the projects and environments the job uses, and leave it read-only unless the job writes secrets. Every new token expires: up to 90 days on the Developer plan, up to 365 on Team.
3. Copy the vs_at_... token (it is shown only once) into your CI provider’s secret store.

Then install the CLI in the job and run your deploy through it. The CLI reads the token from VARSAFE_API_TOKEN, so there is no login step:

# Inject secrets into a GitHub Actions job with an API token.
# VARSAFE_API_TOKEN is a repository secret; VARSAFE_PROJECT_ID a repository variable.
name: deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install varsafe
        run: |
          curl -fsSL https://varsafe.dev/install.sh | bash
          echo "$HOME/.varsafe/bin" >> "$GITHUB_PATH"
      - name: Deploy with secrets
        env:
          VARSAFE_API_TOKEN: ${{ secrets.VARSAFE_API_TOKEN }}
        # No login step: every command reads VARSAFE_API_TOKEN from the job environment.
        # Passing a token inline (`--token "$VARSAFE_API_TOKEN"`) is refused — argv leaks
        # to shell history and process listings.
        run: |
          varsafe run -i "${{ vars.VARSAFE_PROJECT_ID }}" -e production -- npm run deploy

varsafe run keeps the token itself out of your deploy script’s environment, so the script gets the secrets and not the credential that fetched them. CI/CD pipelines covers GitLab CI, tokens per pipeline and failing fast on a revoked token.

Connect your coding agent

Agents such as Claude Code, Cursor, Codex and VS Code connect over MCP. You approve a grant on a consent screen: which team, which access level, and optionally which projects and environments. Values stay out of reach unless you approve a level that includes them, and an agent can never do more than your own role allows: every secret operation is checked against your current role, and recorded in the audit log. Connect an agent has the setup for each client.

An agent that runs shell commands can also use the CLI, with the login on that machine and what you approved for that login, which the agent grant does not narrow. varsafe run hands the values to the command it starts, not to the agent. Agent safety explains how to keep both narrow.

Next steps

Pick the one that matches what you are doing next:

• Local development: switch environments, share the project choice with a .varsafe file, work across repositories
• Move an existing .env into varsafe: import what you have, then delete the plaintext file
• Onboard and offboard: invite a teammate and get them to their first varsafe run
• CI/CD pipelines: a scoped token per pipeline, in GitHub Actions or GitLab CI
• AI agents (MCP) and Agent safety: connect Claude Code, Cursor, Codex or VS Code on a narrow grant
• Core concepts and the Security model: how it works, and what we do not claim