Secret references for developer workflows

Commit references. Resolve secrets at runtime.

Cuitty Safe replaces raw secrets in env files, package scripts, CI/CD, generated config, Code apps, and Registry jobs with stable plaintext references such as account/safe/secret. The actual value stays in a local vault, inline encrypted envelope, Cuitty Persist profile, or 1Password.

Get Started Reference Model →
safe run plan values redacted
.env 
DATABASE_URL=cuitty-safe:acme/dev/database-url
GITHUB_TOKEN=acme/ci/github-token
STRIPE_SECRET=csafe:v1:aes-256-gcm:kid_localdev:nonce:ciphertext
local active
1Password needs-auth
Persist alpha 
$ cuitty-safe run --env-file .env -- bun run dev
resolved 2 refs, injected 2 env vars, printed 0 values

Commit references

Replace raw env values with stable refs like cuitty-safe:acme/dev/database-url.

Resolve at the boundary

Use cuitty-safe run, the SDK, or CI integration to inject values only into the child process that needs them.

Keep values out of systems

Logs, docs, traces, URLs, audits, Code, Registry, and Site only see references and metadata.

Reference model

One path shape across every vault and runtime.

Every Safe reference normalizes to account/safe/secret. The first segment is the account namespace, the second is the Safe name, and the remaining path is the logical key. Provider-specific names such as 1Password vaults and fields stay in connector metadata.

Input Meaning
acme/dev/database-url Bare path when Safe is the active resolver.
cuitty-safe:acme/ci/github-token Explicit scheme for mixed env files and CI.
csafe:v1:aes-256-gcm:... Inline authenticated ciphertext, not a pointer.
Storage modes

Choose the source of truth per Safe.

Default

Local Safe vault

Encrypted records live on the developer machine, key material stays in the OS credential store when available, and reads emit metadata-only audit events.

Portable

Inline encrypted text

Authenticated ciphertext can live beside config for local fixtures or portable handoffs. Keys stay outside the file, and envelopes are versioned.

Alpha

Persist adapter

Safe records can route through Cuitty Persist with E2EE, manual sync first, and explicit alpha acknowledgement for remote targets.

External vault

1Password pass-through

Keep 1Password as the source of truth while Cuitty Safe stores only the stable Cuitty reference and connector mapping metadata.

Persist adapter caveat: alpha until Persist E2EE profile runtime reaches GA security review, recovery testing, and multi-device revocation testing.

Runtime integrations

Resolve at the exact place the secret is needed.

  • Cuitty Code can resolve app manifests, CI runner env, webhook signing refs, mirror credentials, and scan remediations.
  • Cuitty Registry can resolve publish tokens, OCI credentials, artifact storage DSNs, signing keys, and provenance keys at job boundaries.
  • The desktop app manages local vault lock state, connector setup, reveal countdowns, and metadata audit review without showing values by default.
package.json 
{
  "scripts": {
    "dev": "cuitty-safe run --env-file .env -- vite",
    "registry:publish": "cuitty-safe run --scope acme/registry -- bun publish"
  },
  "cuittySafe": {
    "env": {
      "DATABASE_URL": "acme/dev/database-url",
      "GITHUB_TOKEN": "acme/ci/github-token"
    }
  }
}

Start with the local vault. Add connectors when the workflow needs them.

The Safe docs cover reference syntax, storage modes, 1Password mapping, Persist alpha guardrails, CI/CD usage, the SDK split, desktop behavior, and security rules.

Quickstart → Storage modes → Security model →