@package-system

Credentials

credentials[] — how a package declares the secret ids it needs, the encrypted store's four scopes, resolution, and who may set what.

An AI workforce runs on secrets — provider keys, OAuth tokens, integration credentials — and letting them ride in environment variables is the fastest way to lose control of agents. In Neuralis every long-lived secret lives in the encrypted credential store (AES-256-GCM at rest, per scope, in the platform zone). The platform never reads provider secrets from environment variables at runtime, and the generated compose file carries no key entries (a container's environment is readable with docker inspect). .env is reserved for boot-critical settings (configuration).

Declaring a credential id

A package declares the external secrets it needs in credentials[]; each entry becomes a row in the admin Credentials catalog (source package) for an owner to fill. The platform's own LLM, web-tool and infrastructure keys are declared this way too, never hardcoded in the host.

"credentials": [
  { "id": "llm.anthropic", "label": "Anthropic API Key", "category": "llm" },
  { "id": "acme.apiKey", "label": "Acme API Key", "category": "search" }
]

The shape is exactly { id, label, category?, oauth? }. The id must pass the credential-id charset (^[A-Za-z_][A-Za-z0-9_.-]*$, ≤ 128 chars, no slashes or leading dot — it becomes a file-name segment). oauth: true is a display hint: Connect/Disconnect chrome instead of a value field.

  • Declaration is not a grant. A row is catalog metadata with no write authority — a package never stores its own secret — and the value still resolves against the caller's real scope.
  • Declare only ids something actually resolves. A fillable row no code reads is worse than none — the operator believes the key is configured — and no validator can check it.
  • The reserved self-scope namespaces are native-only. Ids in the git (git.<host>.pat, git.<host>.oauth.*), channel and MCP (mcp.<server>.*) classes have host-owned semantics; a non-native manifest that declares one is rejected. Your own namespace is unrestricted at any trust tier.

A source connector or lifecycle module reads a declared secret through the CredentialResolver injected into init(ctx), never config properties (connectors).

Four scopes

The same credential id can hold a separate value at four scopes:

ScopeApplies toTypical use
Platform (global)the whole instanceThe organization's default provider keys
Userone user, everywhereA personal provider key or OAuth login
Projectone project, all its membersA team key billed to that project
Agentone agentA dedicated key for a single high-volume agent

Resolution: most specific wins

When a value is needed — a provider key at stream time, a declared secret at skill activation — the store resolves agent → project → user → global and returns the first value found (a skill activation reads only the tiers its caller could administer, see below). Project is checked before user on purpose: an owner's project key always beats a member's personal key inside that project, and a member's own key is used only when no agent- or project-scope value exists. That ordering makes bring-your-own-key safe alongside central control.

There is no per-credential exception. The ChatGPT/Codex OAuth login lives at the same four scopes and resolves the same way; a personal login is stored by its owner only, through the same credentials.self gate as any member key. A Codex subscription at global scope reaches every project and escapes the spend and use limits (subscription-billed, recorded at $0), so the WRITE governs it: storing anything at global scope requires platform.scope, which carries no default grant. On a self-hosted instance an operator's existing Codex CLI sign-in can be imported from the server's filesystem; that import needs platform.config and is audited (credential.import). No other credential path reads a secret off the host.

The API never returns a stored value: list and read responses carry only { id, source, hasValue }. Writes and deletions invalidate the runtime caches at once, so a rotated key applies to the next request.

A dynamic catalog

The set of ids is not fixed. The catalog is the union of:

  • package-declared ids — every loaded package's credentials[];
  • skill-declared ids — every installed skill's credentials: frontmatter;
  • manual ids — anything an owner adds by hand. A custom LLM endpoint's key (llm.endpoint.<id>) behaves like one: it appears once a value exists, is ordinary bring-your-own-key at any scope (only the caller's own runs use it), and the endpoint's model list is discovered with the platform-global key;
  • per-connection channel secrets — one <baseId>.<connectionId> per live channel connection.

A row carries id, label, category, source (package / skill / manual), declaredBy with each declarer's trust tier, oauth and hasValue for the requested scope — never the value.

Who can set what

Owners supervise all scopes; a member manages only their own.

  • The admin surface — all scopes. The admin Credentials tab (and the manage-credentials skill) writes and deletes at any scope. Reading the catalog requires project.credentials; writing or deleting requires project.credentials.write, which admin holds by default and owner through the '*' wildcard. Only this surface seeds shared keys or sets a value into another user's or an agent's scope.
  • Member self-service — your own user scope. A holder of credentials.self (seeded to admin, manager and member) gets a Credentials card in the chat config panel to store, replace and remove their own keys; with no scope selector, every write lands in the caller's own user scope (your own keys).
  • Connect surfaces — reserved families. Channel secrets (telegram.*, whatsapp.*), git remote tokens (git.<host>.*) and outbound MCP secrets (mcp.<server>.*) are set only on their own cards (channels.connect, git.connect, mcp.connect), which carry per-integration validation; the member card rejects them.

Removing credentials.self from a project's roles disables the set surface there; a key a member already stored keeps resolving (user scope is global to the user) — revoke the value from the admin surface if it must go. Every read, write and deletion is audited, by id, never with the value.

How skills receive credentials

A skill that needs a secret declares it in its frontmatter:

---
name: publish-release
description: Publishes a release through the GitHub API.
credentials:
  - GITHUB_TOKEN
---

At activation the declared ids are resolved through the scope chain and projected into the skill script's child-process environment — only ids that some active skill declared. The chain is cut at the caller's tier ceiling: the caller's own user scope always; agent and project scopes only with project.credentials.write; the global scope only with platform.scope as well. A tier above the ceiling is never read, and its id is reported as plain missing. Every activation that declares credentials writes a skill.credentials_projected audit row with the ids only.

The projection is scoped to the conversation and the principal: an activated skill's credentials stay in that person's later shell commands there (the union of every skill they still have active) until the skill is deactivated or re-activated or the conversation is deleted; someone else who continues it starts with none. Treat activation as granting the credential to your own work, and deactivate a skill when done.

The rest of the script environment is sanitized by a deny-list — defence in depth, not a guarantee: a host variable matching none of its patterns stays visible (skills). Keep secrets in the store.

Use limits — capping how often a credential is used

Every catalog id can carry a use limit: at most N calls per day, week or month (UTC calendar windows) — calls, not dollars, since external APIs report no uniform per-call cost. Rules are platform-wide, set from the admin Credentials tab, matching the exact id. Every resolve counts; past an exhausted window, resolves are refused and audited. Embeddings count per provider HTTP call, a capped index job stops with a resumable error, and semantic search falls back to full-text search with a warning.

  • LLM provider keys are excluded — model spend is governed by the per-project spend limits.
  • Granularity follows the integration — a web search may resolve its key about twice per search, a polled channel consumes its window continuously, and a secret handed to a skill script or MCP sidecar counts once per hand-out.

Host-API authentication is not a credential

Skill scripts calling back into the Neuralis API declare no credential for it: every stream mints a short-lived session ticket with the real caller's identity (NEURALIS_SESSION_TOKEN, sent by neuralis request), and routes enforce that caller's grants. There is no platform bearer token or service account to store, rotate or leak (sessions).

On this page