Secrets

Secrets belong to a specific deployment version. Magmell stores their values encrypted and delivers them only for an invocation of that deployment.

Set secrets

Address a deployment by ID when you already have it:

magmell secrets set 73aef731-3fd3-4fc1-a8cb-dadf00ddc1a0 \
  OPENAI_API_KEY=sk-... \
  SEARCH_API_KEY=...

You can also address the latest active version by handler name:

magmell secrets set research-agent OPENAI_API_KEY=sk-...

Setting secrets replaces the deployment’s complete secret set. Include every key that the deployment should retain.

Shell history

Writing a secret directly on a command line may store it in shell history. Prefer an appropriate secret-injection mechanism in CI and avoid sharing terminal output containing values.

Read a secret in a handler

import siloga_agent


def handle(input: dict) -> dict:
    key = siloga_agent.secret("OPENAI_API_KEY")
    if key is None:
        raise RuntimeError("OPENAI_API_KEY is not configured")
    return complete(key=key, prompt=input["prompt"])

siloga_agent.secret() returns the string value or None when no value exists.

For a TypeScript handler:

import { secret } from '@siloga/magmell-agent'

export async function handle(input: { prompt: string }) {
  const key = secret('OPENAI_API_KEY')
  if (key === undefined) throw new Error('OPENAI_API_KEY is not configured')
  return await complete({ key, prompt: input.prompt })
}

secret() returns the string value or undefined. It is available only inside the active invocation context; never cache it in module scope.

List configured names

Magmell never returns secret values after they are stored. You can list only their names:

magmell secrets list research-agent

OPENAI_API_KEY
SEARCH_API_KEY

Secrets and versions

Each version has its own encrypted set. Deploying research-agent@2 does not copy the secrets from version 1. Configure the new version before directing production runs to it.

The SDK can select the exact version:

await magmell.putSecretsByName(
  'research-agent',
  { OPENAI_API_KEY: process.env.OPENAI_API_KEY! },
  { version: '2' },
)

Safe handling rules

• Never commit values to a handler file or requirements list.
• Never place secrets in run input; input is retained with the run.
• Never return a secret from the handler.
• Never attach secrets to logs, metrics, spans, or events.
• Rotate a value by replacing the deployment’s secret set before the next run.

Secret names must contain only letters, numbers, and underscores and must start with a letter or underscore. A deployment can hold up to 50 secrets; each value can be up to 8 KiB.