---
title: Secrets | Runware Docs
url: https://runware.ai/docs/serverless/secrets
description: Store credentials once in an environment, attach them to the apps that need them, and read them as environment variables at runtime.
relatedDocuments:
  - https://runware.ai/docs/serverless/environment-variables
  - https://runware.ai/docs/serverless/deploying
  - https://runware.ai/docs/serverless/writing-a-model
---
## Introduction

A secret is **stored once in an environment and attached to the apps that need it**. The value stays out of your source, your image, and the definition you deploy.

A name belongs to one [environment](https://runware.ai/docs/serverless/environments), so the same name in another is a different secret with its own value. **One call copies a secret into other environments**, value included, so the same credential reaches `staging` without being sent again.

At runtime it arrives as **an environment variable**, so your code reads it the way it reads any other.

```python
import os

@serve
class FluxDev:
    def load(self) -> None:
        token = os.environ["HF_TOKEN"]
```

## Two steps, deliberately

Creating a secret and using it are separate operations, because **one secret usually serves several apps**.

It is also why **naming a secret on the deploy that creates an app refuses the whole create** when the environment has no active secret of that name, with one [`secret-not-found`](https://runware.ai/docs/serverless/errors#secret-not-found) entry per attachment that missed. Create the secret first, then attach it.

```bash
runware serverless secrets set HF_TOKEN
runware serverless secrets attach my-app HF_TOKEN
```

The first stores it against your organization. The second records that **this app may read it** and, on the next rollout, delivers it.

Detaching is the same in reverse, and it removes the app's access without touching the secret or any other app using it. **Deleting the secret itself is refused while any app still attaches it**, so detach every holder first.

## The name it lands under

An attachment resolves to **the environment variable name the value is injected as**. By default that is the secret's own name, and `envVarName` overrides it when the two should differ.

```json
{
  "secretName": "hf-token-prod",
  "envVarName": "HF_TOKEN"
}
```

That indirection is what lets the same code run against a production and a staging credential: **the app always reads `HF_TOKEN`**, and the attachment decides which stored secret fills it.

> [!WARNING]
> Secrets and plain [environment variables](https://runware.ai/docs/serverless/environment-variables) **share one namespace on the worker**. A resolved secret name that collides with an existing variable is rejected with a `422`, and so is the reverse. There is no last-one-wins, on purpose: a silent override of a credential is not a failure mode worth having.

**Two attachments on the same app cannot resolve to the same name either.** That returns `409`, as does attaching a secret the app already has.

## Copying it into another environment

One call creates a secret in each of `targetEnvironments` with this one's name, type, metadata and value. It copies the secret in `environment`, `production` when omitted, and **the value is copied inside the platform and never returned**.

```bash
curl -X POST https://api.serverless.runware.ai/v1/secrets/HF_TOKEN/copy \
  -H "Authorization: Bearer $RUNWARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "targetEnvironments": ["staging"] }'
```

**Each copy is a separate secret from then on**, so changing or deleting one leaves the original and the other copies as they are. The copy is one write: every target gets the secret, or none does.

A target where the name is already in use returns `409`, **with one entry per taken target** in the order you sent them, so a copy into several reports all of them at once. A `pending_destroy` secret of that name counts as in use. Naming the secret's own environment returns `422`.

**A copy reaches a worker only once you attach it to an app in that environment.**

Creating in several at once works from the other end: a batch item lists its own `environments`, and then every item in that batch lists them.

## Attaching reaches a running worker

This is where secrets differ from most configuration. **Attaching one rolls the app's live deployment in place**, so a worker that is already serving picks up the value from the attach alone.

**Changing the value does the same.** A write re-encrypts it under the same name and rolls every live app that attaches it, which is how a credential is rotated without touching the apps.

> [!NOTE]
> There are two edges. A write that commits while a rollout is **already in progress** waits for that rollout, and the app rolls again about 15 seconds after it finishes, with `secret change accepted: rolls when the rollout in progress finishes` in its events. And an app that is **not live** records the change only, because the next deploy reads the attachment set and the value fresh anyway.
> 
> When the active version cannot be deployed, the roll is retried five times over about 7.5 minutes. After the last one an `error` event says `credential change not applied: the active version could not be deployed`, and the workers keep the value they have until the app is redeployed. An `error` event that says `credential change not applied yet` means a roll failed and could not record its retry. The change is rolled again once the rollout in progress ends.

## What secrets are not for

A secret's `type` is `generic` or `registry`, both stored the same way, and only `generic` attaches. **A `registry` secret cannot be attached to an app**, with [`secret-not-attachable`](https://runware.ai/docs/serverless/errors#secret-not-attachable): a registry login is read when an image is pulled, before a worker exists, so it has no unseal path into a worker's environment. It is stored and validated as a Docker `config.json`, and a private base image is refused with [`base-image-unreadable`](https://runware.ai/docs/serverless/errors#base-image-unreadable).

**Saving a `registry` secret can answer `503`.** Creating, updating or copying one sets up the identity your builds use, and that step can be briefly unavailable, with the detail `Saving a registry secret is temporarily unavailable`. The same request succeeds on a retry.

**Cloud credentials usually do not need to be secrets either.** For AWS, Google Cloud or a service of your own that trusts OpenID Connect, an [OIDC connector](https://runware.ai/docs/serverless/oidc-connectors) gives each worker a short-lived token instead of a key you store and rotate.

**Secrets are for sensitive values.** Anything else belongs in an [environment variable](https://runware.ai/docs/serverless/environment-variables), which is simpler and visible when you are debugging.

## Keeping the value out of your shell

`--value` accepts the secret on the command line, and **you should assume anything passed that way is recorded**. It appears in the process list while the command runs and in your shell history afterwards. **`--value-file` reads it from a file instead, and `--value-file -` from standard input.**

```bash
runware serverless secrets set HF_TOKEN --value-file ./token.txt

printf '%s' "$HF_TOKEN" | runware serverless secrets set HF_TOKEN --value-file -
```

Reading the value from a file avoids both. **`.env` files and anything you keep the value in are never uploaded with your source**, so one sitting in your project directory does not travel to the build.