Set up Secret

Install

Linux/macOS:

curl -fsSL https://raw.githubusercontent.com/avhn/secret/v0.6.0/install.sh | sh

Windows PowerShell:

irm https://raw.githubusercontent.com/avhn/secret/v0.6.0/install.ps1 | iex

The script defaults to the latest release, resolved once from GitHub's release redirect, then downloads only that explicit tag. No GitHub account, gh, Python or credentials are required. Unix needs POSIX sh, curl, standard GNU/BSD utilities and sha256sum or shasum. Windows needs PowerShell 5.1 or 7 and curl.exe.

• Release binaries cover Linux, macOS and Windows on amd64 and arm64, as raw executables rather than archives.
• A new binary is checksum, format, architecture and version checked, then atomically published. Verification failures preserve the old file. The existing executable is never run.
• Unsafe ownership, writable ancestors, aliases, reparse points and DACLs are rejected, not repaired. Locks are never stolen.
• No installer changes execution policy, reads stores, registers MCP, installs hooks or edits clients.

Update, pin and roll back

Rerun either one-liner to update to the latest release. A matching installed digest is a no-op that preserves file identity, mtime and the Windows PATH. Review release changes and stop clients first, especially on Windows, where an open executable can block atomic replacement. Then restart or reconnect and verify.

Set SECRET_VERSION to a strict release version (optional leading v) to pin or roll back. Pins skip latest resolution and may replace a newer version. INSTALL_DIR selects the destination, so you can review an older release before changing a registration path.

curl -fsSL https://raw.githubusercontent.com/avhn/secret/v0.6.0/install.sh | SECRET_VERSION=0.6.0 sh

File invocations also accept --version V, --dir DIR and --help; conflicting environment and flag pins fail. For irm | iex, set SECRET_VERSION and INSTALL_DIR in that PowerShell process rather than appending parameters:

$env:SECRET_VERSION = '0.6.0'
irm https://raw.githubusercontent.com/avhn/secret/v0.6.0/install.ps1 | iex

Paths

Both installers print the concrete executable path. Use that path in client configuration. Installers never delete old binaries, remove old PATH entries or rewrite registrations.

For an AI agent

After you have installed the CLI yourself, you can hand the registration to your agent:

Follow https://github.com/avhn/secret/blob/v0.6.0/docs/setup.md to install and register secret MCP; ask me for the exact intended store references, never discover or read stores, handle values, run operator consent commands, or bypass a guard.

1. Resolve the installed executable's concrete absolute path on this machine.
2. Ask the human which exact store references may expose metadata to this client. Do not search for stores or infer a scope from the working directory.
3. Merge only the selected registration into existing client configuration, preferring user scope. Use project scope only when asked. Preserve unrelated servers and settings; do not replace a whole configuration file.
4. Never run stash, get, import, export or other operator commands as setup. No value, credential environment variable or value-consuming exec wrapper is needed.
5. Ask the human to restart or reconnect the client, then verify the names-only tools. Registration does not authorize a hook exception or installation.

The agent asks you which exact stores may expose metadata to its client. You enter values yourself, and the names-only MCP tools never return them.

Choose the store scope

In every example replace /path/to/secret with the installer's printed absolute path, and file:/path/to/STORE.secret with one exact human-approved reference. These placeholders are paths, not values. Windows examples use C:\path\to\secret.exe and file:C:\path\to\STORE.secret. Never put a secret value in configuration.

• The server argv is mcp --store STORE_REFERENCE. File references must have absolute paths; no tilde, shell expansion, glob, inferred default or directory scan is performed.
• Manual registrations can append another --store with one separately approved exact reference, up to 64 distinct stores. Do not comma-join references. The Desktop bundle accepts only one reference.
• Provider references such as libsecret:APPROVED_NAME, keychain:APPROVED_NAME, pass:APPROVED_NAME and wincred:APPROVED_NAME resolve their names-only manifests under HOME/.secrets. For another manifest directory set SECRETS_DIR in the client server's environment; it is metadata configuration, not a credential.
• age:APPROVED_NAME outer metadata is unauthenticated and requires no identity; do not use it to authorize value operations.

Register MCP clients

Prefer user scope and merge into existing configuration; do not replace a whole file. The registration ID is lowercase secret in every client.

Claude Code

claude mcp add --transport stdio --scope user secret -- "/path/to/secret" mcp --store "file:/path/to/STORE.secret"

PowerShell passes Windows paths as single arguments:

claude mcp add --transport stdio --scope user secret -- 'C:\path\to\secret.exe' mcp --store 'file:C:\path\to\STORE.secret'

Open /mcp and select the server's Reconnect action, or restart Claude Code. User scope is stored in ~/.claude.json; do not replace that file manually.

Claude Desktop, manual JSON

Use Settings > Developer > Edit Config and merge into ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows:

{
  "mcpServers": {
    "secret": {
      "command": "/path/to/secret",
      "args": ["mcp", "--store", "file:/path/to/STORE.secret"]
    }
  }
}

On Windows use "C:\\path\\to\\secret.exe" and "file:C:\\path\\to\\STORE.secret"; doubled backslashes are JSON escaping. Fully quit Desktop, including its background or tray process, and restart it.

Codex CLI and desktop

Merge into ~/.codex/config.toml (or CODEX_HOME/config.toml) without creating a duplicate table:

[mcp_servers.secret]
command = "/path/to/secret"
args = ["mcp", "--store", "file:/path/to/STORE.secret"]

Or register with the CLI:

codex mcp add secret -- "/path/to/secret" mcp --store "file:/path/to/STORE.secret"

Restart the Codex session or desktop host. This is an MCP registration, not a Codex hook trust grant.

ChatGPT desktop

The ChatGPT desktop app shares MCP configuration with Codex for the same host. Use the TOML entry above, or Settings > MCP servers > Add server, choose STDIO and enter the same absolute command and three separate arguments. Browser ChatGPT and remote connectors cannot start local stdio servers; Secret supplies no HTTP server, tunnel or remote bridge.

OpenCode

Merge into ~/.config/opencode/opencode.json (or the existing opencode.jsonc). The command is one array, not a shell string:

{
  "mcp": {
    "secret": {
      "type": "local",
      "command": ["/path/to/secret", "mcp", "--store", "file:/path/to/STORE.secret"],
      "enabled": true
    }
  }
}

Cursor

Merge into the user-wide ~/.cursor/mcp.json, not a project file unless asked:

{
  "mcpServers": {
    "secret": {
      "command": "/path/to/secret",
      "args": ["mcp", "--store", "file:/path/to/STORE.secret"]
    }
  }
}

VS Code

Run MCP: Open User Configuration and merge into that profile's mcp.json:

{
  "servers": {
    "secret": {
      "type": "stdio",
      "command": "/path/to/secret",
      "args": ["mcp", "--store", "file:/path/to/STORE.secret"]
    }
  }
}

Review the server trust prompt and use MCP: List Servers to restart the server after changes.

The schemas and configuration locations were checked against first-party client documentation on 2026-10-28. That is documentation verification, not real-host execution evidence.

Claude Desktop bundle (MCPB)

The release asset is secret-v0.6.0-desktop.mcpb. Obtain it from the exact v0.6.0 release and verify it with the trusted-checkout verifier, not an adjacent checksum alone.

In Settings > Extensions > Advanced settings > Extension Developer, choose Install Extension and select the verified bundle. Enter exactly one approved reference in the required store_reference field, never a value. There is no default or discovery. Fully quit and restart Desktop after configuration changes, and do not also add a manual registration with the same name.

The bundle contains a macOS universal amd64/arm64 executable and a Windows amd64 executable. There is no Linux Desktop bundle or Windows on Arm Desktop support claim. Locked MCPB CLI validation and native payload smoke tests do not cover actual Desktop installation, configuration interpolation or restart; treat it as an opt-in, unverified host integration.

MCP Registry

The MCP Registry name is io.github.avhn/secret. Registry discovery is separate from Desktop installation and from your client registration; the store reference is always yours to choose.

Verify and understand the limits

Run the installed binary's version command with its absolute path. Expected release output is secret 0.6.0 (go). The MCP initialize response identifies secret-metadata version 1 instead.

After reconnecting, confirm the four tools list, show, diff and health, and call health first. Health reports metadata schema version, configured readiness and store count. It does not prove provider availability, value validity, successful store reads or hook protection.

Names-only is not metadata-private: keys, labels, presence, backend, references, paths and provider account IDs may reach the client, its model and its logs.

Use Secret to launch other MCP servers

For a human-configured client launcher, exec supplies selected values to a third-party server without filtering its stdio. It works on macOS, Linux and Windows. -f takes a plain store path, not file::

"/path/to/secret" exec -f "/path/to/.secrets.env" --key OPENPROJECT_API_TOKEN -- uvx openproject-ce-mcp@0.4.1

As client JSON, with a distinct server name:

{
  "mcpServers": {
    "openproject-launcher": {
      "command": "/path/to/secret",
      "args": ["exec", "-f", "/path/to/STORE.secret", "--key", "OPENPROJECT_API_TOKEN", "--optional-key", "X", "--", "uvx", "openproject-ce-mcp@0.4.1"]
    }
  }
}

Uninstall

Stop the server, remove only its registration (or uninstall the Desktop extension), and delete only the installed secret executable when no other client uses it. Preserve other servers and settings. On Windows, manually remove the installer's user PATH entry only if no remaining installation needs it.

Never delete stores, names-only manifests, recovery records or identity files as part of uninstalling.

Advanced and verification

What the one-liners trust

The pinned scripts trust GitHub HTTPS, repository and tag governance and the script itself before payload verification. curl | sh cannot guarantee a complete download before execution; the function wrapper mitigates truncation, but is not a complete-download guarantee. HTTPS checksums detect corruption, not a compromised release publisher, and the standalone installers do not verify attestations. For stronger review, download and read the script first, or use the trusted-checkout route. For optional manual provenance verification, install gh separately and run gh attestation verify FILE --repo avhn/secret on the downloaded asset.

Commit pins

--commit and SECRET_RELEASE_COMMIT were removed from the standalone installers. Pin with SECRET_VERSION or --version only; the authenticated checkout route in docs/install.md is the place to verify an exact commit.

Migration from the staging name

From v0.4.0 onward the executable is secret or secret.exe; the published v0.3.4 installer used secret-go. After upgrading from it, re-register each MCP client with the new printed path, restart and verify, then remove only the reviewed old secret-go file. See migration from the staging name.

Explicit Bash rollback

Old Bash-only releases are not MCP substitutes. The retained Bash implementation is an explicit rollback at compat/secret in a trusted checkout, never an automatic fallback; see explicit Bash rollback.

See the tool reference and the security model.