# Wheelie BYOK and secrets guide

Agent docs index: /llms.txt

Wheelie can use your own model/API keys and other developer credentials, but the
support level depends on the integration. The safe rule is: Wheelie stores saved
credentials encrypted and write-only, then tells you whether a task will use a
mediated capability, a short-lived token, or raw env/file projection into your
trusted workspace.

## What Wheelie stores

- User-provided model/API keys are encrypted at rest.
- Credential status surfaces are write-only: they show metadata such as provider,
  label, scopes, state, and last check, not the plaintext value.
- Commands use your verified session or a scoped capability as the actor source.
  A user ID, email, or workspace ID typed into a prompt, flag, header, or request
  body is not authority.
- CLI session tokens and agent grants are scoped and revocable. Wheelie prefers
  OS credential storage for local CLI auth; trusted single-user hosts may use a
  `0600` file fallback.

## How a credential reaches work

| Mode | What it means | Support level |
| --- | --- | --- |
| Mediated capability | Wheelie calls the provider through a supported adapter and gives the workspace a capability or receipt, not a long-lived provider secret. | Native or preview only for the specific command/provider that reports support. |
| Short-lived credential | A selected supported path mints an expiring, scoped token for a cloud/tool flow. | Adapter-gated or selected-path support; check the command output. |
| Raw env/file projection | Wheelie decrypts your saved secret and passes it to the workspace as an environment variable or owner-only file. | Developer-mode support for trusted single-user workspaces. Treat it like putting the key on your own dev machine. |

Raw projection is sometimes the right compatibility path for normal CLIs and SDKs,
but it is not the same as mediated custody. An agent or process running in that
workspace may be able to read a projected env var or file.

## BYOK model keys

When you bring a model/provider key, Wheelie stores it encrypted at rest and does
not show it back in status output. The selected model path may be mediated for a
supported provider, or it may use raw env/file projection when the provider/tool
needs a normal local credential. Wheelie should label the selected mode before an
agent depends on it.

Do not paste model keys, OAuth codes, cookies, SSH keys, service-account JSON, or
private tokens into prompts, command arguments, PR bodies, logs, screenshots, or
support artifacts. If a credential is invalid, revoked, expired, or rate-limited,
share only the typed `reason`, `support_state`, `next_action`, operation refs,
and redacted artifact refs described in [Support and friendly error states](./support.md).

## Revocation and deletion

Deleting or revoking a credential in Wheelie stops later Wheelie projection or
mediated use. Already-running processes can keep inherited environment variables,
open files, local provider sessions, or cached SDK credentials until you restart
them or revoke the credential at the provider. For high-risk keys, do both:
remove it from Wheelie and rotate or revoke it at the provider.

## Boundaries to remember

- In raw projection mode, an agent or process in the trusted workspace may be able
  to read the projected env var or file.
- OAuth and provider mediation are support-level-specific; check the command's
  reported mode instead of assuming every provider is mediated.
- Long-lived provider credentials stay outside the workspace only on paths that
  explicitly report mediated or short-lived-token support.
- Revocation may not clear already-running processes or provider-side sessions
  outside Wheelie immediately.

## Before you run an agent

1. Check the command's `support_state`, `reason`, and `next_action` fields.
2. Confirm whether the credential mode is mediated, short-lived, or raw
   projection.
3. Use raw projection only for a trusted single-user workspace.
4. Keep secrets out of prompts, shell history, screenshots, and shared artifacts.
5. Rotate provider-side keys when you no longer want a workspace/process to have
   any possible access.