Environment variables

Set a variable once and every box of yours has it: in kvbox connect and kvbox exec sessions, and in the app kvbox deploy runs. Mark one --secret and its value is never shown again, by any command.

kvbox env set NODE_ENV production
kvbox env set DATABASE_URL --secret      # asks for the value, hidden: it stays out of your shell history
kvbox env                                # NAME and value, a secret shows as (sealed)
kvbox env rm NODE_ENV

Inside a box:

kvbox exec dev -- printenv DATABASE_URL

Yours or an org'sCopy Anchor Link

A variable belongs to you or to an org, never to one box. kvbox env set ... --org acme sets it for every box of acme; members of the org can set and remove them, anyone who can see the org's boxes can list them. A box gets the list of whoever owns it: your boxes yours, acme's boxes acme's.

When a box gets a changeCopy Anchor Link

A box takes its variables when it starts. kvbox env set changes nothing in a box that is running; stop and start it to pick the change up:

kvbox stop dev && kvbox start dev

A new box gets the current list, and so does a box made from a snapshot or a fork, whatever the list was when the snapshot was taken. Waking a hibernated box is not a start: it carries on with the variables it had.

In your own servicesCopy Anchor Link

The variables are in /etc/kvbox/env, in the form systemd reads. The app kvbox deploy installs already uses it and is restarted when the list changes at boot; its port stays 3000, where the address points, whatever a PORT variable says. For a service of your own, add one line to its unit:

[Service]
EnvironmentFile=-/etc/kvbox/env

A Docker container gets one with -e NAME, which passes the value from your shell.

RulesCopy Anchor Link

• Names are letters, digits and _, not starting with a digit. PATH, HOME, USER, SHELL and anything starting with KVBOX_ are the box's own.
• A value is one line, up to 4 KB, taken exactly as given: quotes, #, $ and spaces included. Encode a multi-line value such as a key file in base64.
• Up to 100 variables per account or org.
• Variables live on kvbox.sh; --local has none.

Where secrets are keptCopy Anchor Link

On kvbox.sh a secret's value is stored encrypted, and no command or API answer returns it. The host that runs your box has the values, since it hands them to the box, and so does the box itself in /etc/kvbox/env: whoever runs the host can read a box's disk anyway. Variables need base image v0.10.0 or later; a box on an older one starts without them (kvbox vm update <box> moves it to the current base).