# Random Bytes — use the local vault helper

For key material or random tokens, use the locally installed **MCPBytes Vault** tool named
`get_random_bytes`. Its arguments are `label`, `n` and `operation_id`. The hosted REST endpoint
`/v1/sealed-random` (with `pk_c` and `request_id`) is an encrypted transport for custom local
clients and is not offered as an MCP tool; it is not a plaintext key generator or a replacement
for the local helper.

Owner setup and downloads: https://mcpbytes.com/docs/random-bytes

The helper is open source (AGPL-3.0): https://github.com/MCPBytes/mcpbytes-vault. Its public releases
are local-only (no network code; `local_only` is their only mode). The hardware contribution needs the
MCPBytes release from the setup page. Either way, the tool's arguments and receipts are the same.

The setup page includes per-user Bash (macOS Apple silicon / Linux x64) and PowerShell
(Windows x64) installers. They verify the release, create private configuration and provide
local MCP settings. The owner supplies the API key privately afterward. Reinstalling preserves
existing policy, pins, state and saved secrets.
Client-specific connection instructions: https://mcpbytes.com/docs/random-bytes#connect.
Vault is a local stdio server. Use the installer’s Claude/Codex commands or the client’s
local server settings. Pi requires an MCP adapter; the REST skill is not a substitute.
Codex must forward `MCPBYTES_API_KEY` through `env_vars` in the server’s config table.

## Before calling

- The owner must install/configure the helper, its approved public pins, API-key environment and
  chosen local destination. Do not request that they paste an API key or a generated secret into chat.
- Confirm that the tool belongs to the local vault server and exposes `label`, `n`, `operation_id`.
- `label` must match the owner-configured prefix and use only letters, digits, `_` or `-` (1–64 characters).
  Version 0.2.0 and later state the prefix, storage and policy in the tool description; errors are
  `code: hint` (e.g. `label_prefix_mismatch: label must start with "agent-"`). Fix the argument, not the policy.
- `n` is 1–64 bytes. These are raw bytes for an application's cryptographic library, not automatically
  an asymmetric key pair, formatted password or application configuration.
- `operation_id` is a stable caller-chosen identifier using letters, digits, `_` or `-` (1–128 characters).

## Use the reference

Successful output contains `reference`, `label`, `version`, `bytes`, `backend`, `entropy_mode`,
`format` (`raw`: unencoded bytes) and, when applicable, `fallback_reason` and `store_name` (the
Windows Credential Manager entry). It contains no generated bytes. Return/pass the reference to
the application that owns the secret. Never open, print, encode, upload or paste the saved secret
into the conversation. The helper has no plaintext read/export MCP tool.

`list_secrets` (no arguments, read-only) returns the label prefix and each secret's label, version,
size, status (`saved`, `deleted`, `incomplete`), entropy mode and creation time. Use it to find an
existing label or version instead of creating a duplicate.

The owner reads, deletes or enrolls secrets with the helper's terminal commands
(`mcpbytes-vault reveal | delete | totp-qr`). They refuse to run without an interactive terminal:
do not try to run them through a shell tool or work around that. When the owner needs a secret's
value, tell them the command to run in their own terminal. For an authenticator (TOTP) seed, create
20 bytes and tell the owner to run `mcpbytes-vault totp-qr <label>`.

Keep the operation ID and arguments unchanged after an uncertain reply. A completed retry returns
the same receipt without another remote generation. A new ID creates a new immutable version.
An interrupted or ambiguous save requires owner inspection; do not delete its state journal or
blindly create a replacement operation.

## Honor owner policy

The owner chooses `remote_required`, `remote_preferred` or `local_only`. Mixed mode combines an
authenticated encrypted hardware contribution with fresh local OS randomness. Local-only results
are explicitly marked. Unknown pins, bad authentication and malformed responses do not silently
fall back. The selected file/vault destination must be available; there is no storage fallback.

Do not change the owner's policy, pins or storage through shell tools to make a failed call succeed.
If the helper is missing or unconfigured, direct the owner to setup. Do not switch to the generic
REST client or create a recipient private key in agent-visible output.

The reference is not an isolation boundary from other programs with the same OS access. An owner
who gives an agent unrestricted shell access needs a separate identity or sandbox to enforce
storage separation. A completed remote job is billed even if local verification/saving later fails;
failed API jobs are refunded. The tool catalog supplies current pricing.