Skip to content
Public beta preview — you're seeing the sneak peek

BYOK & credential custody

read as .md

Guuey holds several kinds of secrets on your behalf: your model provider keys, the platform’s own managed model keys, the secrets your hosted MCP servers need upstream, and your users’ OAuth tokens for third-party services. Each class has a different owner and a different blast radius, so each gets its own custody path. This page explains the machine behind those paths — Security & isolation has the one-screen inventory; here is the why underneath it.

For those four classes the design rule is the same: your agent’s own code is not given the plaintext. It gets a reference or a short-lived stand-in instead. Your app’s own environment variables are different, including the ones you add under Secrets: see the custody table.

Every stored credential is AWS KMS ciphertext — plaintext never touches a database row. But encryption alone isn’t the interesting part. Each ciphertext is sealed with an encryption context: a set of claims naming what the secret is and who owns it. A BYOK key is bound to its app or workspace, a user’s OAuth token to that user and that service, a hosted-MCP secret to its server.

KMS enforces the context at decrypt time: presenting a ciphertext with any other context is refused by AWS itself, not by Guuey application code. That turns the context into a structural guarantee — a ciphertext lifted from one owner’s row cannot be unsealed as another app, another user, or another credential class, even by code that holds decrypt permission on the key. The partitions are the isolation; the encryption is just the envelope.

Decryption happens only in a Guuey backend process: when a credential is used, or, for your BYOK model keys and app secrets, when Guuey deploys your app or updates its pods. The platform’s managed model keys are fetched by Guuey’s runtime when your pod starts. No read API returns a secret: key listings return a prefix and validation status, secret listings return names only, and OAuth tokens are never returned at all.

BYOK model keys: your key, your pods, still not your agent’s env

Section titled “BYOK model keys: your key, your pods, still not your agent’s env”

When you bring your own provider key (such as Anthropic, OpenAI or Google, added in the Console under your app’s Behavior → Model or at workspace level under Settings → Workspace → your workspace → Provider keys, with a dedicated guuey byok command on the roadmap), it is sealed to your app or workspace before storage. When Guuey deploys an app or updates its pods, it unseals the key with that app’s or that workspace’s own context and delivers it only into that app’s pods. A key added to an app goes only to that app. A workspace key goes to every app in the workspace that has no active key of its own for that provider. A deploy from outside that app or workspace presenting your ciphertext would be refused by KMS.

A provider key set with guuey env set (for example ANTHROPIC_API_KEY=…) is stored as an ordinary app variable, not as a BYOK key: it isn’t sealed this way, it never switches your agent’s model calls to that key or to BYOK billing, and neither your agent’s code nor your colocated MCP servers receive it (a value you set under any of the four provider-key names, ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY or OPENROUTER_API_KEY, is never passed to either).

Inside the pod, custody continues. Your agent’s code runs in a jail whose environment is built by allowlist (Runtime isolation). The provider-key slots are on a refuse list by name, so your key stays with Guuey’s runtime outside the jail, and any model call made on it leaves through the same proxy managed agents use. Your own key never sits in your agent’s process environment.

Why bother, when it’s your key in your own app? Because the jail’s threat model is prompt injection: your agent runs code and reads untrusted input, and anything in its environment is one env away from exfiltration. Keeping your key out of the jail means a hijacked conversation can spend against your provider account only through the metered proxy, for the duration of its own invoke — it can never read the key and walk away with it.

BYOK invokes draw none of your plan’s managed-model budget — the calls are billed by your provider, on your key. See Plans & billing.

Managed model keys: held outside your agent’s jail

Section titled “Managed model keys: held outside your agent’s jail”

Agents without a BYOK key run on Guuey’s managed provider keys — credentials shared across tenants, which makes them the platform’s most guarded class. By design, your agent’s process is never given one. The key stays with Guuey’s model proxy:

  • The jail’s environment is allowlist-by-construction: it starts empty and receives only values picked by name, never a copy of the pod’s environment. There is no “everything minus the secrets” subtraction that a new secret could slip past — the managed key isn’t removed from the environment; it was never a candidate.
  • In a no-code app, your app’s own environment variables, including the ones under Secrets, are set as plaintext in the process environment of your colocated MCP servers (a few names Guuey uses itself, such as any starting with AWS_, are left out), and fill any ${env.NAME} in an MCP server’s headers. The model-calling Claude process never gets them as environment variables: its environment holds only the env block of your guuey.json and a few platform settings. On the current release, a code-mode worker does not receive these variables.
  • In place of a key, your agent’s SDK receives a base URL that points at Guuey’s proxy, and an opaque per-invoke token: random bytes, bound to one provider and one invoke, revoked when the turn ends, and expiring on its own no later than a couple of minutes after the longest turn Guuey allows, even if revocation never runs.
  • The proxy on the other side validates the token, removes the credential headers your SDK sends, and injects the real key into the upstream call. The key stays with the proxy, outside the jail.

The worst a fully compromised agent can do with the managed key is make model calls that are metered and billed to its own app until its token expires. By design, it is not given the key itself to read.

Some provider features run on the provider’s own infrastructure and bill per use on top of tokens: a web search or web fetch, a code-execution container, file search, image generation, and Google Search or Maps grounding. So do a few models that search on every call: OpenAI’s search models, OpenRouter’s :online variants, Perplexity Sonar, and OpenRouter’s Fusion router. Guuey meters the managed key by tokens, so a request on the managed key that offers one of these tools, or names one of these models, is refused before it leaves your pod. The call comes back as an error with the code MANAGED_HOSTED_TOOL_REFUSED, whose message ends “Use your own provider key (BYOK) for provider-hosted tools until they are metered.”

  • On your own provider key, the same request goes through unchanged, and your provider bills it.
  • A tool you define yourself is never matched, even one named web_search: the check reads the provider’s declared tool type, not the name.

Secrets your hosted MCP server needs for its upstream calls (guuey mcp secrets set NAME=VALUE --server <id>) are sealed per server. The plaintext is never baked into a server image and never returned by any API — guuey mcp secrets list shows names only. The MCP gateway unseals a secret per invocation and hands it to your server for that call. Agent pods calling the server see nothing: they authenticate to the gateway with a short-lived federation token, and the secret stays on the server’s side of the gateway.

When an end user connects a third-party service to an agent, the OAuth dance happens at the provider — Guuey receives tokens, never passwords. Custody then follows the claude.ai model, detailed in The MCP proxy:

  • The token is sealed to that user and that service — authorize once, then each app’s access is granted per app via an explicit consent card. The grant is a database row, not a copy of the token.
  • The agent pod never holds the token. It carries a short-lived, KMS-signed federation token addressed to the gateway; the gateway checks the per-app grant and injects the real credential into the upstream call. Plaintext exists only inside the gateway process for the duration of that forward.
  • Disconnecting a service deletes the ciphertext, drains every app grant on the connection, and makes a best-effort revocation call to the provider.

The same envelope model also seals the platform’s identity credentials — per-app signing keys (The identity model) and an optional BYO OIDC client secret (Sign-in on the agent’s page).

Credential class Sealed to Unsealed by What your agent’s processes get
BYOK model key your app / workspace Guuey, when it deploys your app or updates its pods, into Guuey’s runtime in your pod At most a per-invoke stand-in: the key is held by Guuey’s runtime and injected only by its model proxy
Managed model key the platform Guuey’s model proxy A per-invoke stand-in token: the key is held by Guuey’s model proxy
Hosted MCP secret the server MCP gateway, per invocation Nothing: it stays on the server’s side of the gateway
End-user OAuth token the user × service credential broker, per forwarded call A federation token only: the token stays with the broker
App secret (added under Secrets in Settings → Deployment & scaling) your app Guuey, when it deploys your app or updates its pods, into a per-build Kubernetes Secret for your no-code app’s pod In a no-code app: the value itself, as a plaintext environment variable in your colocated MCP servers, and in any ${env.NAME} header you declare on an MCP server

Two properties fall out of the design rather than being enforced case by case:

  • By design, your agent gets stand-ins, not credentials. For the first four classes in the table, what Guuey hands your agent’s process is a path, its own declared configuration, or a short-lived stand-in minted for its one invoke and useless outside its one scope. Your app’s own environment variables are the exception: under Secrets or not, Guuey never swaps them for stand-ins. Your colocated MCP servers can read them, and so can your agent’s worker, so put there only what you’d trust that code with.
  • A breach of one partition stays in that partition. Ciphertext is owner-bound at the KMS layer, the plaintext of those four classes is kept out of your agent’s jail at the runtime layer, and the network walls in Security & isolation close the paths between them.

For the pod model itself — one pod per app, sizes, pause and resume — see How hosting works; the second wall around your agent’s worker is on Runtime isolation.