Secrets

View Markdown

A Secret holds named values, such as an API token or a database URL, encrypted with a key that belongs to your org. You create it once and name it in the Jobs and Sandboxes that need it. Nodus never returns a value through the API, the console or the CLI, and it redacts secret values from logs and outputs.

Create a Secret

nodus secret create hf-token --from-literal HF_TOKEN=hf_xxx
nodus secret create app-env --from-env-file .env
nodus secret create registry --type Registry \
  --from-literal server=ghcr.io --from-literal username=ada --from-literal password=ghp_xxx

Key names start with a letter or _, use letters, digits and _, and may not start with NODUS_. A Secret holds up to 64 keys of at most 4 KiB each. nodus get secret hf-token shows the key names and the current version, never the values.

Use it in a Job

List the Secret under secrets to receive every key as an env var and as a read-only file /run/secrets/<secret>/<key>, or pick one key under another name with valueFrom.secretKeyRef:

apiVersion: nodus.dev/v1
kind: Job
metadata:
  name: ex-secrets-env
spec:
  image: nodus/python:3.12
  secrets: [ex-secrets-env]          # every key as an env var and a file under /run/secrets/ex-secrets-env/
  env:
    - name: TOKEN                    # one key under another name
      valueFrom: {secretKeyRef: {name: ex-secrets-env, key: API_TOKEN}}
  command: [python, check.py]

import os

token = os.environ["API_TOKEN"]
with open("/run/secrets/ex-secrets-env/API_TOKEN") as f:
    from_file = f.read()

# Print facts about the value, never the value: Nodus redacts secret values from logs anyway.
print(f"token has {len(token)} characters")
print("file matches" if from_file == token else "file differs")
print("alias matches" if os.environ["TOKEN"] == token else "alias differs")

nodus apply -f job.yaml
nodus logs job/ex-secrets-env

The same secrets and env fields work on Sandboxes, Workspaces, Functions and Agents. In Python:

hf = nodus.Secret.from_name("hf-token")
env = nodus.Secret.from_dotenv(".env")

A command whose literal env value equals one of the Secret values in its project is refused with SecretValueInEnv: reference the Secret instead of pasting its value. The same check applies to commands you start in a running Sandbox, Workspace or Job with nodus exec or the Processes API, which also refuse an env that sets the same name twice. Values shorter than 8 characters, and the server and username of a Registry Secret, are not checked.

A Job receives the Secret versions pinned when you submitted it, and a Sandbox the versions pinned when it started. If a Secret it uses is deleted (even if you create a new one with the same name), or a new value replaced a Job’s pinned version before a retry started, that attempt fails with LaunchFailed. Secret values delivered as env vars may total at most 1 MiB per container, and as files at most 8 MiB.

Change a value

Writing a Secret again creates a new version; writing the same values again changes nothing. A Sandbox pins the newest version each time it starts, so it gets the new value on its next start, while a running Sandbox keeps the version it started with. A Job keeps the versions pinned when you submitted it, so every attempt runs with the same values; a retry that starts after you replace a value fails with LaunchFailed, so submit the Job again to use it. Earlier versions are deleted 7 days after they are replaced.

apiVersion: nodus.dev/v1
kind: Secret
metadata: {name: hf-token}
spec:
  stringData: {HF_TOKEN: hf_new}

nodus apply -f hf-token.yaml

Private registries

A Secret with type: Registry holds server, username and password. Name it under imagePullSecrets to run or build from a private image:

spec:
  image: ghcr.io/acme/trainer:1.4
  imagePullSecrets: [{name: registry}]

Nodus resolves the tag to a digest when you submit, using the Secret, and the machine that runs the work pulls that digest with the same Secret version. The credential is used for the pull alone: it is not an env var or a file in the container. When the work runs on a provider that pulls containers itself, Nodus first copies the image by digest into your org’s space in the Nodus registry, so your registry credential never leaves Nodus.

Limits and errors

Error	Meaning	Fix
`SecretValueInEnv`	An `env` value equals a Secret value	Use `valueFrom.secretKeyRef` or `secrets`
`EncryptionFailed`	The value could not be encrypted	Retry; the Secret keeps its previous version
`ImagePullFailed`	The registry refused the pull Secret	Check `server`, `username` and `password`