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:
| Scope | Applies to | Typical use |
|---|---|---|
| Platform (global) | the whole instance | The organization's default provider keys |
| User | one user, everywhere | A personal provider key or OAuth login |
| Project | one project, all its members | A team key billed to that project |
| Agent | one agent | A 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-credentialsskill) writes and deletes at any scope. Reading the catalog requiresproject.credentials; writing or deleting requiresproject.credentials.write, whichadminholds by default andownerthrough 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 toadmin,managerandmember) 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).