--- title: Secrets description: How API keys and passwords reach your app without being written into code or passing through an AI model. --- # Secrets Your app probably needs keys: `OPENAI_API_KEY`, `STRIPE_SECRET_KEY`, a Supabase service-role key. On Kaviris they are **secrets**: values your app gets as environment variables, and that nothing in Kaviris shows again. Not to you, not to your agent, not to us. ## The rules - **Never in the code.** A key written into a file is refused ([secret_in_source](../refusals/secret_in_source.md)), and a key in a file the browser downloads always is ([secret_in_client_bundle](../refusals/secret_in_client_bundle.md)). - **Declared in the contract.** Each secret has a slot, by name, in the app's [contract](contract.md) (`secretSlots`). A value for a name that isn't declared is refused, with the patch that declares it. - **Set by reference.** The value goes from your `.env` file or your environment straight to Kaviris. It never passes through the AI model. - **Write-only.** You can see which secrets are set, when and by whom, but never their values. Your app reads them as ordinary environment variables: `process.env.OPENAI_API_KEY` in Node, `os.environ["OPENAI_API_KEY"]` in Python. When a secret changes, the app restarts with the new value. ## By reference (the default) or by value There are two ways to hand Kaviris a secret: - **By reference** (the default, and the one to use): you name where the value is (a `.env` file or an environment variable), and a small command on your machine sends it straight to Kaviris. The AI model never sees it. - **By value**: the agent passes the value itself. It then travels through your AI provider. Use this only when the agent cannot run commands. Your agent sets secrets up entirely on its own, either way; no extra step in the portal. ## Setting a secret with your agent > Set OPENAI_API_KEY from my .env. The agent calls `set_secret` **without the value**. Kaviris answers with a one-time URL, valid for 10 minutes, and a command. The agent runs the command in your terminal; it reads the value from `.env` (or from your environment) and sends it to that URL. The model only ever sees the command, never the key. If your agent cannot run commands, it can pass the value directly (by value). The value then travels through your AI provider, so use this only when there is no other way. ## Setting a secret with the CLI ```sh kaviris secrets set OPENAI_API_KEY # from $OPENAI_API_KEY, else from .env kaviris secrets set OPENAI_API_KEY --from-env MY_OPENAI_KEY kaviris secrets set OPENAI_API_KEY --from-dotenv .env.production pass show openai | kaviris secrets set OPENAI_API_KEY --stdin kaviris secrets import .env # every key in the file kaviris secrets list ``` The CLI never takes the value as an argument (it would end up in your shell history and in your agent's context) and never prints it. Add `--declare` to add the slot to the contract and approve it in the same step. ## Limits - Names look like environment variables: capital letters, digits and `_`, not starting with a digit, at most 128 characters. - Some names belong to Kaviris: `DATABASE_URL`, `PGHOST`, `PGUSER`, `PGPASSWORD`, `PGDATABASE` (your database connection, filled in for you), and anything starting with `KAVIRIS_`, `UNNAMED_` or `KUBERNETES_`. - At most 16 KB per value and 50 secrets per app. ## Publishable keys are not secrets Some keys are meant to be public: Supabase's anon key and its newer `sb_publishable_…` keys, and Stripe's publishable keys (`pk_…`). They may sit in browser code. Kaviris adds a note ([publishable_key](../refusals/publishable_key.md)) to remind you that, with Supabase, row-level security must be on for every table. ## If a key was in your code Moving it to a secret is not enough on its own: anyone who saw the code or the build may have it. **Rotate the key** with the provider (create a new one, delete the old one), then set the new one as a secret.