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), and a key in a file the browser downloads always is (secret_in_client_bundle).
- Declared in the contract. Each secret has a slot, by name, in the
app's contract (
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
.envfile 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
.envfile 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
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 withKAVIRIS_,UNNAMED_orKUBERNETES_. - 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) 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.