Skip to main content

Secrets Manager guide

This guide provides an operational summary for Crusoe AI Platform Secrets Manager.

Service overview​

Secrets Manager delivers versioned, encrypted storage for API keys, passwords, and private tokens. Values are encrypted at rest and delivered to workloads via environment variable bindings or runtime SDK calls.

Quick start in five commands​

# 1. Log in to Crusoe AI Platform
platformctl login

# 2. Store a secret value from standard input
printf %s "$OPENAI_API_KEY" | platformctl secrets put openai-api-key

# 3. Verify the secret metadata
platformctl secrets list

# 4. Bind the secret to a workload environment variable
platformctl secrets bindings set my-service OPENAI_API_KEY --secret openai-api-key

# 5. Apply bindings to roll a fresh workload revision
platformctl secrets bindings apply my-service

Core concepts​

  • Secret: A named credential containing immutable versions and workload bindings.
  • Version: A numbered snapshot of a secret value created on each update (put).
  • Binding: A rule mapping a secret to a workload environment variable.
  • Apply: The deployment action that reads bound secrets, logs audit events, and updates workload revisions.
  • Audited Reveal: An administrative break-glass action that retrieves a raw secret value while logging identity, time, and reason to the audit log.

API operations​

Set API credentials in your environment:

export SM="https://api.codyhill.dev"
export PROJ="<your-project-id>"
export TOK="<your-api-key-or-token>"

Store secret value​

curl -sX POST "$SM/v1/projects/$PROJ/secrets" \
  -H "Authorization: Bearer $TOK" \
  -H "Content-Type: application/json" \
  -d '{"name":"openai-api-key","value":"sk-live-123456789"}'

Create workload binding​

curl -sX PUT "$SM/v1/projects/$PROJ/agents/my-service/secret-maps/OPENAI_API_KEY" \
  -H "Authorization: Bearer $TOK" \
  -H "Content-Type: application/json" \
  -d '{"secret_name":"openai-api-key"}'

Apply workload bindings​

curl -sX POST "$SM/v1/projects/$PROJ/agents/my-service/secret-maps:apply" \
  -H "Authorization: Bearer $TOK"

Reveal secret value (Audited)​

curl -sX POST "$SM/v1/projects/$PROJ/secrets/openai-api-key:reveal" \
  -H "Authorization: Bearer $TOK" \
  -H "Content-Type: application/json" \
  -d '{"version":0,"reason":"auditing production key"}'

CLI operations​

# Store secret from stdin or file
platformctl secrets put openai-api-key < /path/to/key
platformctl secrets put tls-chain --value-file ./chain.pem

# Manage secret metadata
platformctl secrets list
platformctl secrets show openai-api-key
platformctl secrets versions openai-api-key

# Manage workload bindings
platformctl secrets bindings set my-service OPENAI_API_KEY --secret openai-api-key
platformctl secrets bindings list --agent my-service
platformctl secrets bindings apply my-service
platformctl secrets bindings delete my-service OPENAI_API_KEY

# Audited reveal and delete
platformctl secrets reveal openai-api-key --reason "key validation"
platformctl secrets delete openai-api-key

Console UI walkthrough​

  1. Open the Crusoe Console and navigate to Security → Secrets.
  2. Click Add a secret, fill in the secret name and the value, and submit with Create secret.
  3. Open the target workload under Compute → Agents or Compute → Functions, and scroll to the Secrets and environment section on its page.
  4. Click Bind a secret, pick your secret, set the environment variable name, and submit with Bind. The binding is recorded at this point and is not yet on the workload.
  5. Click Apply N pending bindings on the banner (or Apply in the section header) and confirm the dialog with Apply to <name>. That confirm is what reads each value, writes it onto the workload and rolls a new revision.

A container service deployed under Compute → Serverless has no binding section in the console — that section is only mounted on the Agents and Functions pages. Bind those with platformctl secrets bindings set or the API, both of which accept a container.

Service quotas & limits​

PropertyDefault Quota
Maximum value size per version64 KiB
Maximum request body size128 KiB
Name constraints1–63 characters of letters, digits, - or _, starting with a letter or digit

There is no limit on the number of secrets in a project: the create path counts nothing before writing, and the project quota covers running instances, CPU, memory and services only. The two size caps above are enforced in code.

Troubleshooting​

SymptomCauseResolution
Workload env var emptyBinding recorded but apply was not executed.Run platformctl secrets bindings apply <workload> or click Apply in the Console.
Cannot delete secretSecret is still actively bound to workloads.Remove bindings with bindings delete before removing the secret.
Reveal request fails with 403User lacks project administrator role.Request administrator role elevation or ask a project admin to execute the reveal.
Secret rotation not reflectedWorkload holds older pinned version or needs revision roll.Ensure binding tracks latest or update pinned version, then run apply.

Security best practices​

  1. Avoid Hardcoded Secrets: Pipe secret values directly into platformctl secrets put via standard input to prevent shell history leaks.
  2. Audit Break-Glass Reveals: Use :reveal sparingly; all value retrievals log the user identity and reason string to the project audit log.
  3. Use Short-Lived Access Tokens: For dynamic workloads, prefer runtime SDK calls (secret()) over permanent environment variables.