From e768fa448ba77a395996beaefbe74142c6ec377b Mon Sep 17 00:00:00 2001 From: Alex Clarke Date: Wed, 3 Jun 2026 09:01:06 -0600 Subject: [PATCH] docs: Added documentation for the improved vault implementation --- Getting-Started.md | 5 +- Sharing-Configurations.md | 7 +- Vault.md | 139 ++++++++++++++++++++++++++++++-------- 3 files changed, 119 insertions(+), 32 deletions(-) diff --git a/Getting-Started.md b/Getting-Started.md index 71060ec..6d3967b 100644 --- a/Getting-Started.md +++ b/Getting-Started.md @@ -4,8 +4,9 @@ After installation, you can generate the configuration files and directories by coyote --info ``` -Then, you need to set up the Coyote vault by creating a vault password file. Coyote will do this for you automatically and -guide you through the process when you first attempt to access the vault. So, to get started, you can run: +Then, you need to set up the Coyote vault. On your first run, Coyote walks you through choosing a secrets provider +(Local, AWS Secrets Manager, GCP Secret Manager, Azure Key Vault, gopass, or 1Password) and configuring it. See the +[vault documentation](Vault) for the full list of providers and configuration details. To get started, you can run: ```sh coyote --list-secrets diff --git a/Sharing-Configurations.md b/Sharing-Configurations.md index 63515ed..9a6c075 100644 --- a/Sharing-Configurations.md +++ b/Sharing-Configurations.md @@ -197,7 +197,8 @@ MCP server entries (and other config files) can reference vault secrets with `{{ install completes, Coyote scans the resulting `mcp.json` for placeholders that are not yet in your vault and either: - **In a TTY:** prompts you, one secret at a time, whether to add it to the vault now. On the first "Yes", Coyote - initializes the vault password file (if needed). On "No", the secret is deferred and reported at the end. + initializes the vault (if needed; for the Local provider, this just means creating the password file). On "No", the + secret is deferred and reported at the end. - **In a non-TTY environment:** skips prompts entirely; lists every missing secret in a final reminder block, with the commands you can run later (`coyote --add-secret ` or `.vault add `). @@ -249,8 +250,8 @@ asset type plus a `README` describing the customization workflow. The following are **intentionally** outside the install-remote feature's scope: -- **`config.yaml`** (the global Coyote config). It holds user-specific things like editor preference, vault password file - path, client API keys, OAuth tokens, and similar. Merging a shared `config.yaml` would risk breaking auth or routing +- **`config.yaml`** (the global Coyote config). It holds user-specific things like editor preference, secrets provider + configuration, client API keys, OAuth tokens, and similar. Merging a shared `config.yaml` would risk breaking auth or routing traffic somewhere unexpected. Settings that genuinely benefit from sharing (like default models) already belong inside individual agents' or roles' configs. - **Sessions, RAGs, agent runtime data.** These accumulate as you use Coyote and aren't shareable in a meaningful way. diff --git a/Vault.md b/Vault.md index 460768a..216cef1 100644 --- a/Vault.md +++ b/Vault.md @@ -1,15 +1,17 @@ The Coyote vault lets users store sensitive secrets and credentials securely so that there's no plaintext secrets -anywhere in your configurations. +anywhere in your configurations. -It's based on the [G-Man library](https://github.com/Dark-Alex-17/gman) (which also comes in a binary format) which -functions as a universal secret management tool. +It's built on the [G-Man library](https://github.com/Dark-Alex-17/gman), which supports multiple secrets providers: +a local encrypted file, AWS Secrets Manager, Google Cloud Secret Manager, Azure Key Vault, gopass, and 1Password. You +pick the one that fits your workflow and Coyote handles the rest. ![Vault Demo](./images/vault/vault-demo.gif) --- # Usage -The Coyote vault can be used in one of two ways: via the CLI or via the REPL for interactive usage. +The Coyote vault can be used in one of two ways: via the CLI or via the REPL for interactive usage. The same commands +work regardless of which provider you've configured. ## CLI Usage The vault is utilized from the CLI with the following flags: @@ -33,6 +35,94 @@ The vault can be accessed from within the Coyote REPL using the `.vault` command The manipulation of your vault is guided in the same way as the CLI usage, ensuring ease of use. +# Supported Providers +Coyote supports six secrets providers via [G-Man](https://github.com/Dark-Alex-17/gman). The default is **Local** (an encrypted file on this machine), but you +can switch to any of the others. + +| Provider | Storage | What it needs | +|-----------------------|---------------------------------------------------------------|---------------------------------------------------------------| +| `local` (default) | Encrypted file at `vault.yml` in your Coyote config directory | A password file you create on first run | +| `aws_secrets_manager` | AWS Secrets Manager | An authenticated AWS CLI (`aws sso login` or `aws configure`) | +| `gcp_secret_manager` | Google Cloud Secret Manager | `gcloud auth application-default login` | +| `azure_key_vault` | Azure Key Vault | `az login` | +| `gopass` | The `gopass` password manager | The `gopass` CLI installed and initialized | +| `one_password` | 1Password | The `op` CLI installed and signed in (`op signin`) | + +If you're not logged into the relevant CLI when Coyote needs to read a secret, you'll get an auth error with the +canonical login command. Coyote does not try to log you in automatically. + +# Configuration +There are two ways to configure your secrets provider in `config.yaml`: + +## Shorthand: `vault_password_file` +If all you want is the default Local provider, just set the path to a password file: + +```yaml +vault_password_file: ~/.coyote_password +``` + +This is shorthand for "use the Local provider with this password file". It's the simplest setup if you don't +want to use a dedicated secrets provider external to Coyote. + +## Explicit: `secrets_provider` +For any non-Local provider (or if you want to be explicit about your Local setup), use the `secrets_provider` block: + +```yaml +# Local +secrets_provider: + type: local + password_file: ~/.coyote_password + +# AWS Secrets Manager +secrets_provider: + type: aws_secrets_manager + aws_profile: default + aws_region: us-east-1 + +# Google Cloud Secret Manager +secrets_provider: + type: gcp_secret_manager + gcp_project_id: my-project-id + +# Azure Key Vault +secrets_provider: + type: azure_key_vault + vault_name: my-vault-name + +# gopass +secrets_provider: + type: gopass + store: my-store # Optional; omit to use the default store + +# 1Password +secrets_provider: + type: one_password + vault: Production # Optional; omit to use the default vault + account: my.1password.com # Optional; omit to use the default account +``` + +When `secrets_provider` is set, the legacy `vault_password_file` field is ignored. + +> ⚠️ **Important:** The `secrets_provider` block itself cannot use `{{SECRET_NAME}}` interpolation. Coyote needs to +> initialize the vault *before* it can resolve any secrets, so the provider's own configuration must be literal values. +> All *other* fields in your config (API keys, MCP server env vars, agent variables, etc.) support `{{SECRET_NAME}}` +> references as normal. + +# First-Run Setup +The first time you start Coyote without a config file, a wizard walks you through picking a secrets provider: + +1. Choose a provider from the menu (Local, AWS, GCP, Azure, gopass, 1Password). +2. Coyote prompts you for the provider-specific config (AWS profile/region, GCP project ID, Azure vault name, etc.). +3. For non-Local providers, Coyote performs a **round-trip validation**: it writes a probe secret to the backend, reads + it back, then deletes it. If your credentials don't have the right permissions, or if you're not logged in, Coyote + bails out *before* you fill out the rest of the wizard, with a hint pointing to the correct login command. +4. For the Local provider, Coyote prompts you to create a password file. + +Once the provider is set up, the wizard continues with your LLM/API provider selection and writes your `config.yaml`. + +If you set up Coyote with one provider and later want to switch, just edit your `config.yaml` to change (or add) the +`secrets_provider` block. + # Motivation Coyote is intended to be highly configurable and adaptable to many different use cases. This means that users of Coyote should be able to share configurations for agents, tools, roles, etc. with other users or even entire teams. @@ -40,29 +130,24 @@ should be able to share configurations for agents, tools, roles, etc. with other My objective is to encourage this, and to make it so that users can easily version their configurations using version control. Good VCS hygiene dictates that one *never* commits secrets or sensitive information to a repository. -Since a number of files and configurations in Coyote may contain sensitive information, the vault exists to solve this problem. +Since a number of files and configurations in Coyote may contain sensitive information, the vault exists to solve this +problem. How you share secrets across a team depends on your provider: -Users can either share the vault password with a team, making it so a single configuration can be pulled from VCS and used -by said team. Alternatively, each user can maintain their own vault password and expect other users to replace secret values -with their user-specific secrets. +- **Local:** Either share the vault password with the team (one config + one shared password file) or have each user + maintain their own password and substitute their own secret values. +- **AWS / GCP / Azure / gopass / 1Password:** Each team member uses their own credentials against the shared backend. + The vault becomes a natural single source of truth. Rotating a secret in one place propagates to everyone using + that config. -# How it works -When you first start Coyote, if you don't already have a vault password file, it will prompt you to create one. This file -houses the password that is used to encrypt and decrypt secrets within Coyote. This file exists so that you are not prompted -for a password every time Coyote attempts to decrypt a secret. - -When you encrypt a secret, it uses the local provider for `gman` to securely store those secrets in the Coyote vault file. -This file is typically located at your Coyote configuration directory under `vault.yml`. If you open this file, you'll see a -bunch of gibberish. This is because all secrets are encrypted using the password you provided, meaning only you can decrypt them. - -Secrets are specified in Coyote configurations using the same variable templating as the [Jinja templating engine](https://jinja.palletsprojects.com/en/stable/): +# Referencing Secrets +Secrets are referenced in Coyote configurations using the same variable templating as the [Jinja templating engine](https://jinja.palletsprojects.com/en/stable/): ``` {{some_variable}} ``` -So whenever you want Coyote to use a secret from the vault, you simply specify the secret name in this format in the applicable -file. +So whenever you want Coyote to use a secret from the vault, you simply specify the secret name in this format in the +applicable file. The same syntax works regardless of which provider stores the secret. **Example:** Suppose my vault has a secret called `GITHUB_TOKEN` in it, and I want to use that in the MCP configuration. Then, I simply replace @@ -93,16 +178,17 @@ the expected value in my `mcp.json` with the templated secret: } ``` -At runtime, Coyote will detect the templated secret and replace it with the decrypted value from the vault before executing. +At runtime, Coyote will detect the templated secret and replace it with the decrypted value from the vault before +executing. # Supported Files At the time of writing, the following files support Coyote secret injection: -| File Type | Description | Limitations | -|-------------------------|-----------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------| -| `config.yaml` | The main Coyote configuration file | Cannot use secret injection on the `vault_password_file` field | -| `functions/mcp.json` | The MCP server configuration file | | -| `/tools.` | Tool files for agents | Specific configuration and only supported for Agents, not all global tools ([see below](#environment-variable-secret-injection-in-agents)) | +| File Type | Description | Limitations | +|-------------------------|------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------| +| `config.yaml` | The main Coyote configuration file | Cannot use secret injection on the `vault_password_file` field or anywhere inside the `secrets_provider` block | +| `functions/mcp.json` | The MCP server configuration file | | +| `/tools.` | Tool files for agents | Specific configuration and only supported for Agents, not all global tools ([see below](#environment-variable-secret-injection-in-agents)) | Note that all paths are relative to the Coyote configuration directory. The directory varies by system, so you can find yours by @@ -146,4 +232,3 @@ follows: ``` For more information about variable usage within agents, refer to the [Variables section](Agents#user-defined-variables) of the [Agents documentation](Agents) -