Secrets

A secret is a named, encrypted value scoped to your guild. Operators can use secrets when they need to call a service that requires authentication. Members never see secret values directly — they're substituted at runtime by the vault, not injected into the operator's LLM context.

Egress security modes

Above the secret list, the Egress Security card sets how operators in sandboxes access external APIs. Pick one:

• Direct (off) — No egress controls. Real credentials injected into agent env / files. Lowest latency; widest blast radius if the agent leaks.
• Cooperative (Free+) — Agent sees only $$SECRET[NAME]$$ placeholders. The real value is substituted at the host's egress proxy. Bypassable by libs that ignore HTTP_PROXY, but the agent has nothing real to bypass with.
• Strict (Team+) — Cooperative + sandbox-level enforcement (iptables NAT or runtime-level proxy mandate). The agent literally cannot reach the network except via the proxy.
• Paranoid (Business+) — Strict + TLS-MITM at the sidecar. Catches any outbound call. Breaks SDKs with cert pinning.

Default is Cooperative on free, which is enough for almost everyone. Step up to Strict/Paranoid when the operator is running untrusted code or you're under a tight compliance regime.

Adding a secret

Add secret button (top right). Two paths:

1. Direct paste — paste a value, give it a slug.
2. From provider — connect via OAuth, the vault stores the tokens automatically (used by Google, GitHub, etc. integrations).

Each secret has:

• Slug — gamma-api-key, github, openai-apikey. Used to reference the secret.
• Kind — API key, OAuth token, JSON creds, PEM. Drives how it's parsed at runtime.
• Owner — your user or the guild.
• Audit metadata — Updated and Last used timestamps.

Most BYOK provider keys land here automatically when added under Usage → BYOK. The Secrets page is the power-user view of the same vault.

Access control

Two layers of access, both required:

1. Guild access — the secret is attached to the guild.
2. Operator access — within the guild, individual operators must be explicitly granted access. Default: no operator can read it.

Installing a skill that uses a secret is a two-step grant: add the secret to the guild, then grant the operator running the skill read access.

How operators consume secrets

Operators don't read secret bytes. They call a tool (e.g. fetchWithSecret) that resolves the slug at the host, makes the authenticated call, and returns the response — the raw value never reaches the LLM context.

Skills declare their requirements:

# .guilde/skills/my-skill/SKILL.md
secrets:
  - slug: slack-webhook-url
    required: true

Rotation

Edit a secret to rotate. Old encrypted bytes are overwritten in place — the secret retains its slug and ID, so dependent skills don't need re-wiring. Last few rotations are timestamped in the secret's history.

For compromised secrets: rotate at the source first (cycle the upstream key), then update Guilde's stored value. Operators using the secret pick up the new value on their next read.

Audit log

Click a secret → Usage. Every read attempt: operator + timestamp + outcome (granted / denied / error). Useful for "why is my operator failing" and access auditing.

What's next

• Usage → BYOK — the curated UI for LLM provider keys (writes here under the hood)
• Integrations — for SaaS integrations, prefer the integration's OAuth flow over raw secrets
• Skills — how skills reference secrets