Local Tokens & Secrets

A skill that touches a real service needs credentials — an OAuth token, an app password, an API key. Cremind's design keeps those on your machine. Action scripts call provider APIs directly with your local token, and the Cremind Connect relay only ever carries content-free nudges, never your data or your tokens. This page explains where secrets live and how a skill's configuration reaches it.

Two kinds of secret

A skill deals with two distinct kinds of sensitive data, stored in two different places:

Tokens: scripts/.<name>.json

Tokens that a skill obtains at runtime — the OAuth access and refresh tokens from a link flow, for instance — are written to a per-skill JSON file inside the skill's scripts/ directory, named after the skill. The built-in gmail skill stores its Google token at scripts/.google_token.json.

Crucially:

• The OAuth code-to-token exchange happens locally on your machine (the built-in Google skills use a loopback PKCE flow).
• The relay never sees the token. It cannot — it only relays a resync signal that something changed.
• The token file is gitignored and stays on disk between runs, so you link once.

This is what lets the same account, linked in two Cremind installs, receive events in both: each install holds its own local token and pulls the delta itself; the relay just fans the nudge out.

Configuration: metadata.environment_variables and scripts/.env

Non-token configuration — endpoints, usernames, optional overrides — is declared in the skill's frontmatter and delivered through an environment file. A skill declares what it expects:

metadata: {
  environment_variables: ["CALDAV_URL", "CALDAV_USERNAME", "CALDAV_PASSWORD"],
  optional_environment_variables: ["CREMIND_CONNECT_URL"]
}

environment_variables lets the Settings UI render a config form for the skill. When you save values there, Cremind writes them to the skill's scripts/.env, and the script reads them at runtime. The generic terminal tool the agent uses has no per-skill environment hook, so scripts/.env is the single channel for a skill's configuration.

optional_environment_variables lists variables that have sensible defaults and only need setting to override. The built-in OAuth skills, for example, list their relay URL and OAuth client id as optional because those are fetched dynamically from Cremind Connect unless you choose to override them.

How .env survives a restart

The values you save are persisted in Cremind's database, not just on disk. This matters because Cremind re-copies the shipped skill files (including any default .env) on every boot to repair tampering or deletion. To keep your overrides, Cremind re-materializes each skill's scripts/.env from the persisted variables after that copy — so a restart never silently loses your configuration, and writing from the database also produces an empty .env when there are no overrides, clearing any credentials an older build may have shipped on disk.

Why the relay can't leak your tokens

The architecture deliberately separates actions from events:

• Actions (list, send, create, …) call the provider API directly from your machine using your local token.
• Events flow as content-free resync nudges from the relay; on each nudge the listener pulls the change locally with that same token.

At no point does a token or message body cross the relay. The most the relay knows is that an account it can route to had a change. Everything sensitive stays on the machine that linked the account. See Event Listeners for the full flow.

Re-linking and rotation

If a token is lost or revoked, you re-run the skill's link/setup flow to mint a fresh one into scripts/.<name>.json. Because client ids and secrets for the built-in skills are fetched from Cremind Connect rather than baked into the client, the org can rotate them without you updating anything — you only set them in scripts/.env to override.