Q&A

What is a .monkeys file?

A .monkeys file is a project's list of the environment variables it needs, kept next to the code and committed with it. It holds the keys, never the secrets: .env.example with the secrets left out, and the values that were never secret written in beside their keys.

Is .monkeys a file extension?

No. The whole name is .monkeys, the way .env is: nothing comes before the dot. A project has one, at the root of the git checkout.

Where does monkeys keep a secret?

In the vault the operating system already runs: the keychain on macOS, the Secret Service on Linux, which is GNOME Keyring or KWallet. It keeps no file of its own, so there is no database to back up or leak, and the desktop's own tools list and delete what it stores.

Can a coding agent read my secrets?

No command prints a stored secret, and monkeys run replaces one with [redacted KEY] when the command it started prints it back. An agent can give a command the secrets it needs without the secret entering the conversation, which is what the skill teaches it to do.

How do I move a project off .env?

monkeys eat reads the .env files it finds, puts the secrets in your vault, writes the keys into .monkeys, and deletes the files it read. Name the keys that were never secret with --public and it writes those as values instead of asking about each one.

Does this work with...?

Yes. Anything that reads process.env gets what run hands it, and a .env file is only one way to fill that environment, never a channel of its own. Every loader that reads one reads the environment as well.

monkeys run bun run dev
monkeys run npm run build

The environment wins over the file, so a .env left behind cannot shadow what run handed over. Prefix rules are untouched: only the names a framework exports, VITE_ or PUBLIC_ or NEXT_PUBLIC_, reach the browser, wherever the value came from.

For a tool that reads no environment at all, poo writes the .env it wants.

How do I use this with Docker?

A container inherits nothing from the host, so name the variable and Docker takes it from the environment run made. A -e with no =value after it means exactly that.

monkeys run OPENROUTER_API_KEY docker run -e OPENROUTER_API_KEY myimage
monkeys run docker compose up

In compose.yaml a bare name under environment: does the same:

services:
  api:
    environment:
      - OPENROUTER_API_KEY
      - STRIPE_SECRET_KEY

Output that comes back through the container is still redacted, since monkeys is in front of the docker command. A build takes a BuildKit secret instead, which never lands in a layer:

monkeys run OPENROUTER_API_KEY \
  docker build --secret id=openrouter,env=OPENROUTER_API_KEY .

What if a tool insists on a .env file?

monkeys poo writes one carrying the same keys .monkeys lists, with nothing after them, so the file satisfies whatever wanted it while run keeps handing over the values. It lands in /tmp unless --path says otherwise.

monkeys poo --path .

How do I give a teammate the secrets?

monkeys pack writes every profile as one encrypted file and puts its passphrase on your clipboard. They run monkeys unpack, which asks for the passphrase, puts the secrets in their own vault, writes the project's .monkeys, and deletes the file.

What happens if I lose the machine?

The secrets are gone with the vault, since nothing else holds them. Remember them again from wherever they came from, or unpack a bundle a teammate still has.

Does monkeys work on Windows?

Monkeys hate windows. There is no native build: it speaks to the macOS keychain and the Secret Service, and Windows runs neither. The Linux build runs under WSL, which needs a Secret Service in that session the way any Linux machine without a desktop does: gnome-keyring or KWallet, running and unlocked.

How is this different from direnv?

direnv loads a file into your shell when you enter a directory, so the secrets live in a file and then in every process that shell starts. monkeys keeps them in the vault and hands them to one command, and the file it commits holds keys only.

How is this different from 1Password CLI, Doppler or Infisical?

Those are services: an account, a server, a subscription, and a company that can see what you store. monkeys is one binary that uses the vault already on the machine, with nothing to sign into and nothing to host. What it gives up is what a service is for, such as audit logs and taking access away from someone centrally.

Is monkeys free?

MIT, with no account and no server. The source is the whole of it.