Environment Variables

Environment variables are key-value pairs that change how your content behaves at runtime. You set them in the ricochet UI or through the REST API.

During development you may keep secrets in a .Renviron or .env file. These files should not be deployed with your content item, and the ricochet CLI leaves them out of a deployment. Ricochet encrypts environment variables at rest and decrypts them only before it starts a process.

Any change to an environment variable stops all running instances, so future requests use the new value.

Using the UI

Open your content item and select the “Environment Variables” tab. Here you can add or remove environment variables.

The Key is the name of the environment variable. Value is its value.

Press ”+ Add Variable” to save the environment variable.

New processes get the new environment variables.

Using the REST API

No value is ever sent in plain text. You must encrypt both the names and the values before you send them to the API. To do this, fetch the server’s public key, RSA encrypt each name and value with it, and put the results in the JSON body.

# fetch the server's public key
curl -s https://try.ricochet.rs/api/v0/public-key -o ricochet.pub

# encrypt one name or value
encrypt() {
  printf '%s' "$1" | openssl pkeyutl -encrypt -pubin -inkey ricochet.pub \
    -pkeyopt rsa_padding_mode:oaep -pkeyopt rsa_oaep_md:sha256 | openssl base64 -A
}

# add or update ENV_NAME and leave the other variables in place
curl -X PATCH \
  'https://try.ricochet.rs/api/v0/content/01JSZAXZ3TSTAYXP56ARDVFJCJ/env-vars' \
  -H 'Authorization: Key rico_xxxxx' \
  -H 'Content-Type: application/json' \
  -d "{\"$(encrypt ENV_NAME)\": \"$(encrypt ENV_VALUE)\"}"

Every endpoint expects encrypted environment variables.

Method	Path	Effect
`GET`	`/api/v0/content/{id}/env-vars`	List the names
`PATCH`	`/api/v0/content/{id}/env-vars`	Add or update the variables sent and keep the rest
`PUT`	`/api/v0/content/{id}/env-vars`	Replace the whole set and delete anything not sent
`DELETE`	`/api/v0/content/{id}/env-vars/{name}`	Remove one variable

You cannot read the raw values through the API. The GET endpoint returns only the names of the keys.

API reference

Limitations

A name or a value may be at most 190 bytes. This is the most a 2048 bit RSA key carries under OAEP with SHA-256. Longer strings cannot be encrypted at all.

Keys may only consist of ASCII letters, numbers, and underscores.

Accessing environment variables

To read an environment variable in R, use Sys.getenv("KEY_NAME"). In Julia, use the built-in dictionary ENV["KEY_NAME"].