DOCSEARCHbyAlgolia
Submit Docs

Keystone Documentation

website·Indexed 31 days ago

https://keystone.sh

A secret management tool for developers to sync secrets and files across environments and team members. Includes comprehensive CLI documentation for the 'ks' command, covering secret management (ks secret), organization handling (ks orga), CI service configuration (ks ci), and backup/restore operations.

Tokens
15.5K
Snippets
115
Records
148
Agent score
50%

What's inside Keystone

  1. Overview of Keystone secret synchronization

    Keystone is an open-source (MIT Licensed) tool designed to sync environment variables and secret files across team members, environments, and codebase versions directly from the terminal. It provides end-to-end encryption powered by Themis and uses ephemeral storage. To ensure programs are not missing required secrets, Keystone tracks secret keys (but not values) via Version Control Systems (VCS).

  2. Overview of Keystone.sh secret management

    Keystone.sh is an open-source, terminal-based tool designed to share and synchronize sensitive data such as certificates, credentials, and environment variables across development teams and environments (local, CI/CD, and production). It aims to eliminate the manual sharing of .env files and ensure that the secrets required for a specific codebase version/commit are always in sync.

  3. Self-host Keystone

    Self-hosting Keystone is free. For assistance with Keystone setup that may benefit the community, users are encouraged to open a GitHub issue.

  4. Use the ks CLI for secret management

    The ks command-line interface provides a safe system for developers to store, share, and use secrets. The general command syntax is: ks <command> [sub-command] [inputs]... [flags].

  5. Understand Keystone's security architecture

    Keystone is built on three core security principles:

    1. Complete Transparency: The entire codebase is open-source (MIT license) and auditable on GitHub to allow third-party monitoring and vulnerability discovery.
    2. Zero-Knowledge: Keystone does not have access to the data shared by users. It uses the Themis library (Secure Message cryptosystem in Encryption mode) client-side within the CLI to ensure integrity, authenticity, and confidentiality. Only the intended recipient can decrypt messages.
    3. Ephemeral Storage: To minimize the attack surface, messages are stored in Redis (separate from the Postgres application database) and are deleted either immediately after the recipient fetches them or after a default time-to-live (TTL) of 7 days.

  6. Understand Keystone project environments

    Keystone projects utilize three distinct environments to manage secrets and files across different stages of deployment. Each environment contains the same set of secrets and files, but the values or content differ based on the environment's purpose:

    • dev: The default local development environment.
    • staging: Used for testing and pre-production setups.
    • prod: The production environment.

  7. Automate secret backups using Keystone CLI hooks

    Keystone is not a backup service; secrets are deleted after they are fetched or after the default 7-day time-to-live expires. To automate backups, you can register an executable hook that runs every time secrets are fetched by the Keystone CLI. The executable receives the project UUID and the path to the .keystone folder as parameters.
    # Add a hook
ks hook add <path-to-your-executable>

# List active hooks
ks hook

# Remove a hook
ks hook rm

  8. Initialize a Keystone project

    To use Keystone with an existing project, run ks init followed by your project name. This process creates two items:

    1. keystone.yaml: Contains project metadata, secrets, and file references. This file should be tracked by your version control system (VCS).
    2. .keystone: A cache folder. This folder should be ignored by your VCS (e.g., added to .gitignore).
    cd /path/to/your/project
ks init my-awesome-project

# Example VCS steps
git add keystone.yaml
echo ".keystone" >> .gitignore

  9. Manage project members and roles

    Only users with the roles developer (invite), devops, or admin can add/remove members or change roles. A user cannot modify a member who has a higher rank than their own. Use the following CLI commands to manage membership:
    # Add a new member
ks member add

# Remove a member
ks member rm

# Change a member's role
ks member set-role

  10. Configure ks completions for Fish

    To load ks completions for the current session, pipe the output to source. For permanent installation, save the output to the fish completions configuration directory.
    # Current session only
ks completion fish | source

# Permanent setup
ks completion fish > ~/.config/fish/completions/ks.fish

  11. Configure ks completions for PowerShell

    To load ks completions for the current session, use Invoke-Expression. For permanent setup, save the output to a .ps1 file and source that file from your PowerShell profile.
    # Current session only
ks completion powershell | Out-String | Invoke-Expression

# Permanent setup
ks completion powershell > ks.ps1
# Then add 'source ks.ps1' (or equivalent) to your PowerShell profile

  12. Install Keystone CLI on MacOS

    Keystone is distributed via Homebrew. You must first add the Keystone tap before installing the stable version or a specific version.
    # Add the Keystone tap
brew tap wearedevx/keystone

# Install the latest stable version
brew install wearedevx/keystone/keystone

# Alternatively, install a specific version
brew install wearedevx/keystone/[email protected]