Secrets Management

Sciorex includes an encrypted local vault for storing API keys, tokens, and credentials. Secrets are never exposed to AI models directly — they are referenced by name and injected at execution time only after explicit user approval.

Overview

The secrets system is built on a single principle: AI models should never see secret values. Instead, models reference secrets by name, and Sciorex handles value injection at the last possible moment.

Property	Detail
Storage	Encrypted local vault on disk, unlocked per session
Encryption	AES-256-GCM with a session-derived key
Scope	Per-project or global, configurable per secret
Backup	Export encrypted vault file for backup (decryption key required to restore)

WARNING

Secrets are stored locally on your machine. Sciorex never transmits secret values to any remote server, including AI provider APIs. If you need to share secrets across machines, use the encrypted export/import workflow.

Collections

Organize related secrets into named collections for easier management.

• Group by service — e.g., "AWS", "GitHub", "Database" collections
• Group by environment — e.g., "Development", "Staging", "Production"
• Bulk operations — grant or revoke AI access to an entire collection at once
• Collection-level metadata — add descriptions and tags to collections for discoverability

Secrets Vault
├── AWS
│   ├── AWS_ACCESS_KEY_ID
│   ├── AWS_SECRET_ACCESS_KEY
│   └── AWS_SESSION_TOKEN
├── GitHub
│   ├── GITHUB_TOKEN
│   └── GITHUB_WEBHOOK_SECRET
└── Database
    ├── DB_HOST
    ├── DB_PASSWORD
    └── DB_CONNECTION_STRING

Security Model

The security model is designed around minimal exposure.

Rule	Enforcement
Secrets NEVER exposed to AI models	Model receives only the secret name, never the value
Environment variable reference only	Tools reference $SECRET_NAME, not the literal value
Value injected at execution time	Injection happens in the process runner, outside the AI context
Session-scoped access	Access grants expire when the chat session ends
Audit trail	Every access request, approval, and release is logged

INFO

Even when an AI agent runs a command that uses a secret (e.g., curl -H "Authorization: Bearer $API_KEY" ...), the model's context only ever contains the placeholder $API_KEY. The actual token is substituted by the process runner at execution time.

User Approval

Every secret access request requires explicit user approval through a modal dialog.

1. The AI agent calls sciorex_get_secret with the secret key
2. Sciorex displays an approval modal showing:
   • Which secret is being requested
   • Which agent is requesting it
3. The user approves or denies
4. If approved, the secret value is returned for the current operation only

WARNING

Approving a secret grants access for the current session only. The agent must request access again in future sessions. There is no "remember this choice" option by design — every access should be a conscious decision.

MCP Tools (sciorex-secrets)

The sciorex-secrets MCP server exposes 4 tools for secret management. These tools are available to AI agents within chat sessions.

sciorex_list_secrets

Browse the vault contents without exposing any values.

Parameter	Type	Description
collection	string?	Optional filter by collection name
search	string?	Optional search by secret name or tag

Returns: Array of secret metadata objects (name, collection, tags, last accessed). Values are never included.

TIP

Agents typically call sciorex_list_secrets first to discover what credentials are available before requesting access to a specific one.

sciorex_get_secret

Retrieve a secret by key. Triggers the user approval modal for access control.

Parameter	Type	Description
key	string	The key/name of the secret to retrieve

Returns: The secret value if approved, or an access-denied error if rejected. The approval modal shows the user which secret is being accessed and by which agent.

sciorex_set_secret

Store a new secret or update an existing one. Requires user confirmation before storage.

Parameter	Type	Description
key	string	A unique key/name for the secret
collection	string?	Optional collection to organize it under
tags	string[]?	Optional tags for searchability

Returns: Confirmation of storage. The actual value is entered by the user through a secure input field — never passed through the AI context.

INFO

The sciorex_set_secret tool does not accept a value parameter. When called, Sciorex opens a secure input dialog where the user types the secret value directly. This ensures the value never passes through the AI model's context.

sciorex_delete_secret

Remove a secret from the vault.

Parameter	Type	Description
key	string	The key/name of the secret to delete

Returns: Confirmation that the secret has been removed.

Secret Access Workflow

The access pattern ensures secrets are only exposed when explicitly approved.

Agent                          Sciorex                         User
  │                               │                              │
  ├─ sciorex_list_secrets ───────►│                              │
  │◄─ [key, collection, tags] ───┤                              │
  │                               │                              │
  ├─ sciorex_get_secret(key) ────►│                              │
  │                               ├─ Show approval modal ──────►│
  │                               │◄─ Approve ──────────────────┤
  │◄─ secret value ──────────────┤                              │
  │                               │                              │
  ├─ [use secret in operation]    │                              │
  │                               │                              │

TIP

Secrets are accessed per-operation. Each call to sciorex_get_secret requires fresh user approval. There is no persistent access grant — every access is a conscious decision.

Related

• MCP Servers — the protocol layer that exposes secrets tools to agents
• Chat Interface — where approval modals appear during conversations
• Settings — configure vault location, encryption, and default collections