Skip to Content
How-to guidesConnect a vault

Connect a vault

Connect the vault your team already uses, pick the entries your agents need, and choose for each one whether it is a secret or config. A secret becomes an HTTP secret: the agent only ever sees a placeholder, and the real value is swapped in on the way out, for the hosts you allow. Config is a plain setting, such as a host name, a port or a log level, that your space gets as an environment variable.

You can connect AWS Parameter Store, AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault (KV v2), and 1Password.

Before you start

  • You need permission to create connections. For a team or organization connection, you also need to lead that team or be an org admin.
  • Values update when you resync. Marshal does not watch the vault for changes.

Steps

  1. In the left rail, open Connections.
  2. On the Cloud Vault Secrets card, click Connect.
  3. In the Connect a vault dialog, choose your vault type.
  4. Choose how Marshal signs in, then fill in the sign-in fields. Pick the matching section below.
  5. Enter a Connection name. If an Owner field is shown, leave it on you unless the connection is for a team or the whole organization.
  6. Click Discover secrets. Marshal lists what it found. It never reads a value at this step.
  7. Tick the entries to import. For each one, check the Env var name and pick its Kind, Secret or Config. Marshal preselects the kind from what your vault says about the entry, and you can change it.
  8. For each secret, enter the Allowed host(s), for example https://api.example.com/**. A pattern without a path, such as https://api.example.com, matches only the root URL. Add /** to cover every path. Config entries need no hosts.
  9. Click Confirm & import.

Secret or config

  • Secret: the space holds a placeholder. Marshal swaps in the real value only on requests to the hosts you allow.
  • Config: the space gets the value as plain text in the environment variable. Use it for settings that are not sensitive.

The preselected kind follows your vault. In 1Password, concealed fields and masked Environment variables start as Secret and everything else starts as Config. In Parameter Store, SecureString parameters start as Secret, and String and StringList start as Config. Entries from Secrets Manager, GCP Secret Manager and HashiCorp Vault start as Secret.

If you set an entry that your vault marks as secret to Config, Marshal shows a warning before you import, because its value becomes plain text in the space. The choice is recorded in the audit log by name, never by value.

Config values are stored encrypted, like secrets. Only people who can manage the connection can see them in Marshal, and they never appear in logs or audit events. A person you share the connection with gets the config values inside the spaces they start.

A config value can be up to 16 KiB and must be plain text on one line. All config values together can be up to 256 KiB in one space. Names that Marshal or the space itself uses, such as PATH, HOME, HTTPS_PROXY and NODE_OPTIONS, cannot be used for config, and Marshal tells you when you pick one. A config entry and another entry of the same owner cannot share a name.

AWS Parameter Store and AWS Secrets Manager

Choose Use existing AWS connection, Cross-account role (AssumeRole), Static access keys, or IAM role via IRSA. Then enter the Path prefix (Parameter Store) or Name prefix (Secrets Manager) that holds your secrets.

1Password

1Password connects with a service account token. Create the service account in 1Password first:

  • Give it read access to the one vault Marshal should use.
  • Set an expiry date on the token.
  • Use a service account just for Marshal, so its requests stay separate from your other tools.

Then in the dialog:

  1. Choose 1Password, then Service account token.
  2. Paste the token in Service account token and click Load vaults.
  3. Pick the vault in Vault.
  4. Optional: narrow the list with Tag (optional) or Title prefix (optional). When you set both, an item must match both. For a large vault, a tag or prefix keeps the list short.
  5. Click Discover secrets.

Every field of the matching items is listed. Concealed fields, such as passwords and API keys, start as Secret. Other fields, such as usernames and URLs, start as Config.

1Password Environments

A connection can also read 1Password Environments. Give the service account access to the Environment in 1Password, then enter the Environment’s ID in Environment IDs (optional) when you connect. Separate several IDs with commas or new lines. A connection reads up to 5 Environments.

Each variable appears with the path env/<Environment ID>/<variable name>. Masked variables start as Secret and the others start as Config. To add or remove an Environment later, open the connection with Manage, find Environments, and use Add Environment or Remove. Remove the imported entries of an Environment before you remove the Environment itself.

If your network limits outbound traffic, allow HTTPS from Marshal to *.1password.com, *.1password.ca, and *.1password.eu. The sign-in address is my.1password.com, my.1password.ca, or my.1password.eu, depending on your account region.

1Password limits how many reads a service account can make. Each discovery reads the items that match your tag and prefix, so a tag or prefix also saves reads. Personal and Families accounts allow 1,000 reads per day. The Teams plan allows 5,000 and the Business plan allows 50,000.

What you should see

  • The imported secrets appear in your HTTP secrets list, each marked as coming from the connection.
  • The connection appears under Vault Connections.
  • Marshal never shows a value or the sign-in token after you save.

Keep values current

After you change a value in your vault, open the connection with Manage and click Resync. Marshal updates the imported values, for secrets and config, and lists anything new or removed in the vault. It never adds or deletes an entry on its own. A changed config value reaches the spaces you start next.

If the type of an entry changes in your vault, for example a concealed field becomes plain text, Marshal keeps the kind you chose and shows type changed on the entry. Check its kind and save it to clear the flag. To switch an entry between Secret and Config, change Kind in the manage view and save. A secret needs at least one allowed host.

If 1Password reports that the token has expired or was revoked, create a new token and connect again with it.

Next

Create a space from a manifest, then open its Secrets tab to use your imported secrets.

Add an HTTP secretConnect Slack