Credential store

The credential store is the central API for resolving, reading, and writing credentials. It combines a storage backend with environment variable lookups and strategy-scoped overrides.

Creating a store

import {
  createCredentialStore,
  createJsonFileBackend,
  resolveCredentialsPath,
} from "@comma-agents/core";

const store = createCredentialStore({
  backend: createJsonFileBackend({ filePath: resolveCredentialsPath() }),
});

CreateCredentialStoreOptions

Prop

Type

Resolving credentials

resolve is the primary method — it walks the resolution chain and returns the best credential for a provider:

// Check strategy scope → env vars → global scope
const cred = await store.resolve("openai", "my-strategy");

// Omit scope to skip strategy-scoped lookup
const cred = await store.resolve("openai");

Returns undefined if no credential is found in any layer.

Reading and writing

Use get, set, and remove to work with credentials in a specific scope directly, bypassing the resolution chain:

// Store a global API key
await store.set("openai", "$global", { type: "api", key: "sk-..." });

// Store a strategy-specific key
await store.set("openai", "my-strategy", { type: "api", key: "sk-project-..." });

// Read from a specific scope (no fallback)
const cred = await store.get("openai", "$global");

// Remove a credential
const removed = await store.remove("openai", "my-strategy"); // true if it existed

Listing credentials

// List provider IDs in a scope
const providers = await store.list("$global");
// ["openai", "anthropic"]

// List all scopes that have credentials
const scopes = await store.listScopes();
// ["$global", "my-strategy"]

Global credential store

The daemon sets a global credential store at startup. Other parts of the system (model resolution, provider factories) access it through the global singleton:

import {
  setGlobalCredentialStore,
  getGlobalCredentialStore,
} from "@comma-agents/core";

// Set once at startup (the daemon does this automatically)
setGlobalCredentialStore(store);

// Read anywhere in the application
const globalStore = getGlobalCredentialStore();
const cred = await globalStore.resolve("anthropic");

When using the daemon, you do not need to set the global store yourself — the daemon bootstraps it from the JSON file backend on startup.