Secrets

Workspace secrets let preview processes and lifecycle hooks use API keys, tokens, and other sensitive values without storing them in your repository. Your .trevize/settings.json contains only a secret key; Trevize resolves the encrypted value at runtime.

Add a workspace secret

Open Workspace settings → Secrets, select Add secret, and enter:

• Key — the stable name referenced by repository configuration. It must start with a letter and contain only uppercase letters, digits, and underscores.
• Value — the sensitive value injected at runtime.
• Description — optional context for other workspace members.

After a secret is saved, Trevize returns only its key and metadata to the UI; the value remains masked.

Reference a secret in a repository

Add secretEnv to a preview target. Each entry maps the environment variable your application reads to a workspace secret key:

{
  "preview": {
    "targets": {
      "dev": {
        "command": "bun run dev",
        "port": 3000,
        "secretEnv": {
          "OPENAI_API_KEY": "OPENAI_PRODUCTION_KEY"
        }
      }
    }
  }
}

Read the mapping as "<environment variable>": "<workspace secret key>". In this example, the application reads process.env.OPENAI_API_KEY, while Trevize looks up the workspace secret named OPENAI_PRODUCTION_KEY.

Hook entries accept the same secretEnv block, so a setup command can, for example, seed data through an authenticated API:

{
  "hooks": {
    "SandboxReady": [
      {
        "command": "bun run db:seed",
        "secretEnv": { "SEED_API_KEY": "SEED_API_KEY" }
      }
    ]
  }
}

The secret value itself never belongs in .trevize/settings.json.

Manage secrets from the CLI

The CLI accepts values only through a hidden TTY prompt or stdin, so values do not appear in shell history or command arguments. Secret listings and mutation responses contain keys and metadata only:

trevize secrets list --output json
printf '%s\n' "$SERVICE_TOKEN" | trevize secrets set SERVICE_TOKEN --stdin
trevize secrets delete SERVICE_TOKEN --yes --output json

Use --dry-run to validate a key before a write. Deletion requires an interactive confirmation, or the explicit --yes flag in automation. Do not put secret values in repository configuration; map uploaded workspace secrets by name with secretEnv as shown above.

Share secrets or limit them to one process

Target-level secretEnv entries are available to every process in that target. Put secretEnv on an individual process when only that process needs the secret:

{
  "preview": {
    "targets": {
      "dev": {
        "defaultProcess": "web",
        "secretEnv": {
          "SHARED_SERVICE_TOKEN": "SHARED_SERVICE_TOKEN"
        },
        "processes": [
          {
            "name": "web",
            "command": "bun run dev:web",
            "port": 3000
          },
          {
            "name": "api",
            "command": "bun run dev:api",
            "port": 8787,
            "secretEnv": {
              "STRIPE_SECRET_KEY": "STRIPE_PRODUCTION_KEY"
            }
          }
        ]
      }
    }
  }
}

Here, both processes receive SHARED_SERVICE_TOKEN, but only api receives STRIPE_SECRET_KEY.

If the same environment variable appears in more than one place, resolution uses this order, with later values taking precedence:

1. Target-level env
2. Process-level env
3. Target-level secretEnv
4. Process-level secretEnv

This lets a process-specific secret override a shared value deliberately.

Secrets and interpolation

Use secretEnv for secret values. A workspace secret is not available as a ${NAME} placeholder inside env:

{
  "env": {
    "DATABASE_URL": "postgres://user:${DATABASE_PASSWORD}@db.example.com/app"
  }
}

The configuration above does not resolve DATABASE_PASSWORD from workspace secrets. Store the complete sensitive value, such as the complete database URL, as a workspace secret and map it directly instead:

{
  "secretEnv": {
    "DATABASE_URL": "DATABASE_URL"
  }
}

Troubleshooting

If a referenced key does not exist in the workspace, Trevize stops the preview before starting its processes and reports the missing key. Add the secret in workspace settings or correct the right-hand side of the secretEnv mapping.

When a process cannot read a configured value, check that:

• The repository’s workspaceId belongs to the workspace containing the secret.
• The right-hand value matches the workspace secret key exactly.
• secretEnv is attached to the intended target or process.
• The application reads the left-hand environment variable name.