SOPS for coding agents

A coding agent working with encrypted configuration in a repository can use SOPS to encrypt or decrypt files from the command line. SOPS, short for Secrets OPerationS, supports YAML, JSON, ENV, INI, and binary files. For structured files, it encrypts values while leaving keys and file structure readable, so reviewers can still see what changed. The agent can use SOPS to create and check an encrypted development fixture, a file used for testing, while keeping real secret values out of its prompt.

SOPS does not decide who should receive a secret. The person or script running it needs access to a decryption key or to a key-management service, which stores and controls encryption keys. The example below uses a local age key. age is a simple tool for encrypting files, and SOPS can use its keys. It uses only local files and does not contact a cloud service.

Install SOPS

The official installation page points to binaries and packages of the latest stable release on the GitHub releases page. It also explains how to build SOPS from source. Download the release for your system and put it on your PATH. Then check that it runs:

sops --version

The local example also uses age-keygen, which creates an age key pair. Install age using its official instructions before running the example. The SOPS age page links to the age project.

SOPS also supports key providers such as cloud KMS services and PGP. To use one of these providers, configure its credentials and permissions. For cloud KMS, SOPS makes requests to that provider; the local age example avoids those network calls. The SOPS documentation describes supported key services and configuration options.

Encrypt a local fixture

Write a disposable YAML file containing a fake value, then generate a local age key:

cat > plaintext.yaml <<'EOF'
service:
  api_token: example-only-not-a-real-secret
EOF

age-keygen -o age.key

The age key file contains the private key used for decryption. Keep it out of version control. Derive the public recipient from the key file, then ask SOPS to encrypt the fixture:

recipient=$(age-keygen -y age.key)

sops encrypt \
  --age "$recipient" \
  --input-type yaml \
  --output-type yaml \
  plaintext.yaml

This command sends encrypted YAML to standard output, the normal output stream for a command. The values are encrypted, while keys such as service and api_token remain visible. To save the ciphertext as a file, run the same command with output redirection:

sops encrypt \
  --age "$recipient" \
  --input-type yaml \
  --output-type yaml \
  plaintext.yaml > dev.enc.yaml

The first command previews the encrypted content in the terminal; the second writes it to dev.enc.yaml. Both commands use age with local files. SOPS does not upload the fixture or key.

Decrypt without exposing real secrets

Point SOPS to the local key file, then decrypt the fixture:

export SOPS_AGE_KEY_FILE=age.key
sops decrypt dev.enc.yaml

SOPS sends the decrypted YAML to standard output. For this example, that output contains only the fake token. With real credentials, the same command would print secret values, so an agent’s shell output could expose them in its transcript or logs. Do not ask an agent to print real secrets. If a task needs a secret to run a command, configure access outside the prompt and keep the secret-bearing output out of the agent’s context.

A realistic prompt for the fixture task is: “Create a local SOPS-encrypted YAML fixture using the fake value in plaintext.yaml. Verify that SOPS can decrypt it locally, but do not use or print any real credentials. Report which files you created.” The agent can follow the local example and report the filenames without receiving a real secret.

Know what SOPS leaves visible

SOPS protects file values, but it leaves structured keys and layout readable. SOPS does not control access to the key. Anyone with the relevant private key or provider permissions can decrypt the file. Before you commit an encrypted file, check that its visible keys and metadata do not reveal information that should remain private.

The SOPS documentation covers its supported formats and command options. For coding-agent tasks, encrypt files with SOPS. Give the agent only the key access the task requires. Keep decrypted values out of output the agent can see.