> For the complete documentation index, see [llms.txt](https://docs.nuvolos.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nuvolos.com/reference/configuration/environment-variables-and-secrets.md).

# Environment variables and secrets

Environment variables and secrets let you provide configuration values and credentials to your Nuvolos [applications](/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.

**Configure environment variables**

1. Click **Account & Settings** in the top right corner.
2. Click **User Settings**.
3. Open the **VARIABLES** tab.
4. Add, edit, or remove variables: **+ ADD NEW VARIABLE**, or use the Actions menu (copy name, copy value, edit, delete) on existing variables.

## 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 and at what scope.

Secrets are encrypted at rest. Once a secret value is set, the Nuvolos UI cannot retrieve it - only the name can be copied. Secrets can be edited or deleted.

### 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 inside Applications

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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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/reference/configuration/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.