# Environment variables and secrets

Environment variables and secrets let you provide configuration values and credentials to your Nuvolos [applications](/features/nuvolos-basic-concepts/applications.md) without embedding them in code or storing them on disk.

* **Encrypted at rest, available at runtime** — secrets and environment variables are stored encrypted and only made available inside a running application. Once the application stops, they are no longer accessible in plain text.
* **Prefer secrets over the HOME folder** — while the HOME area is also encrypted at rest, it is local to a single instance and carries some risk of unintended exposure (e.g. through distribution or shared mode). Nuvolos secrets avoid this risk entirely.
* **Three scope levels** — secrets can be configured at the **personal (account)**, **space**, and **organisation** level. If the same secret name exists at multiple levels, the most specific scope wins: personal overrides space, space overrides organisation.
* **Permissions** — any user can set personal secrets. Space administrators can set space-level secrets. Organisation managers can set organisation-level secrets.

{% hint style="info" %}
Use secrets and environment variables to store sensitive information such as database credentials, API tokens, and access keys. Storing such information on the file system is a security risk and may lead to inadvertent sharing.
{% endhint %}

## Environment variables

Nuvolos supports setting custom environment variables for your applications at the account level.

**To configure environment variables:**

1. Click the **Account & Settings** menu in the top right corner.
2. Click **User Settings** in the dropdown.
3. Click on the **VARIABLES** tab.
4. Add, edit, or remove variables as needed:
   1. **+ ADD NEW VARIABLE** lets you add new variables.
   2. For existing variables, the **Actions** menu has copy name, copy value, edit and delete as options.

## Secrets

Secrets can be configured at three levels: account, space, and organisation. They are all treated the same way inside applications — the only difference is who can manage them.

{% hint style="info" %}
Secrets can be edited, deleted and only their name may be copied. Since they are encrypted at rest, the Nuvolos UI is not able to retrieve the secret value.
{% endhint %}

### Account secrets

All Nuvolos users can set personal secrets. These are available to all your applications but only for your account — other users in the same organisation or space cannot see them.

**To configure account secrets:**

1. Click the **Account & Settings** menu in the top right corner.
2. Click **User Settings** in the dropdown.
3. Click on the **SECRETS** tab.
4. Click **+ ADD NEW SECRET**, provide a name and value, and save.

A good use case for account secrets is personal access tokens for third-party vendors (e.g. Hugging Face, OpenAI).

### Space secrets

Nuvolos supports setting custom secrets for spaces, that are available for all members in the space who are viewers in at least one instance of the particular space. This action requires you to be a **Space Administrator**.

1. Navigate to the space.
2. On the sidebar click the Cogwheel icon and select **Project Configuration**
3. Pick the **SECRETS** tab.
4. Click **+ ADD NEW SECRET**, provide a name and value, and save.

A good use case for space-level secrets is shared connection credentials for a third-party resource (e.g. a database server hostname, port, or certificate). For credentials that differ per user (e.g. personal passwords), prefer account-level secrets for better security and auditing.

### Organisation secrets

Organisation-level secrets are available to all members of the organisation.

As an **Organisation Manager**, you can configure organisation secrets from the organisation dashboard.

1. Navigate to the organisation you want the secret to be set up in.
2. In the top right corner of the dashboard, click the **Cogwheel icon**.
3. Click **Organization settings**.
4. Navigate to the **SECRETS** tab.
5. Click **+ ADD NEW SECRET**, provide a name and value, and save.

Please take the [override policy](#override-policy) into account when dealing with organisation secrets.

### Override policy

When the same secret name is defined at multiple levels, the most specific scope wins:

**Account secret > Space secret > Organisation secret**

For example, if an organisation manager sets an organisation secret called `ACCESS_KEY` and you also have an account secret with the same name, your applications will use the account-level value.

{% hint style="info" %}
To avoid accidentally overriding organisation or space secrets, check the existing secret names in your space's **SECRETS** tab before creating account secrets.
{% endhint %}

## Usage

Both environment variables and secrets are available inside running applications, but they differ in how they are exposed:

* **Environment variables:**
  * Available as standard environment variables in the application process.
  * Values can be viewed from the web UI.
  * Subprocesses may or may not inherit them when spawned.
* **Secrets:**
  * Available as environment variables in the application process.
  * Also written as files under the `/secrets` folder (filename = secret name, content = secret value).
  * Values cannot be viewed from the web UI.
  * Because they are stored at a fixed location, any spawned subprocess can read them from `/secrets`.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.nuvolos.com/features/environment-variables-and-secrets.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.