Touch-gated local credentials for developer tools and automation.
Developer tools sometimes need credentials that should never appear in a command line, environment file, chat transcript, or agent context. Sockeye stores those credentials in macOS Keychain and gives them only to one exact child process after a human approves the request with Touch ID.
Sockeye does not have a plaintext get command or a background unlock daemon.
Read the security model before integrating it with a
tool.
The name comes from the Halkomelem word sθə́qəy, meaning “red fish.” English adapted the word as “sockeye.” See the Dictionary of Canadianisms on Historical Principles for the language history.
Sockeye is pre-release and macOS-only. Build the current development binary from a reviewed checkout:
pnpm install
pnpm run buildThe binary is written to
build/dev/<platform>-<architecture>/out/Final/sockeye. A signed GitHub release
and checksum-verified installer remain release gates; see the
release checklist.
- Command and user guide: credential operations, exact child launches, local CI, and common errors.
- Security model: trust boundaries and protections.
- Credential setup: attended storage workflows.
- Threat model: scoped threats and remaining risks.
Store a credential from an attached terminal. Sockeye hides the input; press Control-D when the value is complete.
sockeye set SOCKET_RELEASE_CLIENT_ID --binding <binding-id-from-profile>For a guided Keychain or one-time 1Password import, use
pnpm run setup:credential. The setup command
never makes 1Password a runtime credential provider.
Running a child process with an exact credential list
Run one child with an exact credential list, working directory, executable, arguments, and optional bound files:
sockeye run \
--credential SOCKET_RELEASE_APP_PRIVATE_KEY --binding <binding-id-from-profile> \
--pass-env SOCKET_RELEASE_CLIENT_ID \
--bind-file /absolute/path/to/runner.mjs \
--cwd /absolute/path/to/repository \
-- /absolute/path/to/node /absolute/path/to/runner.mjsSockeye prints the complete request and a manifest digest before showing the
Touch ID prompt. The child receives a minimal environment containing only the
listed credentials and any names explicitly added with --pass-env. For
ENVRYPT_PRIVATE_KEY, Sockeye uses Envrypt's one-use envrypt-v1 pipe instead
of putting the key in that environment.
SOCKET_RELEASE_CLIENT_ID is public configuration, so the example passes it
from the parent environment. The private key is a secret and comes from
Keychain. Keeping that distinction explicit avoids unnecessary biometric
storage for values that are safe to display.
Fleet GitHub commands use sockeye gh-run through the credentials:gh
wrapper. Sockeye reads the active github.com token from gh without printing
it. It validates the token with GitHub and stores a protected copy. It updates
that copy only when the active token changes. It leaves gh's credential
storage unchanged.
The repository bridge derives the exact secrets.NAME and vars.NAME
references from one selected workflow. It asks Sockeye for only those secret
names. Pass each public variable explicitly with --var NAME=value:
pnpm run ci:sockeye -- \
run --workflow .github/workflows/github-release.yml \
--var SOCKET_RELEASE_CLIENT_ID=example-release-client-id \
--var SOCKET_PAYLOAD_CLIENT_ID=example-payload-client-id \
--quiet --pause-on-failure --github-tokenAdd --repository /absolute/path/to/repository to run a workflow in another
checkout. The bridge resolves that checkout's installed run-local-ci package.
It rejects duplicate workflow selectors, environment files, and secret override
flags. Public variable names must match the selected workflow.
The bridge refuses --all because a multi-workflow run would widen the
credential request. It also refuses generated gh-aw .lock.yml files, which
Local CI cannot execute. The bridge process never reads a secret value; it sees
only secret names and public variable values. The Touch ID approval still
happens once, immediately before the exact Local CI child launch.
Contributor commands
pnpm install
pnpm run build
pnpm run test
pnpm run checkVitest is the test orchestrator even though the product is C++. Read native development and testing for the file layout and test boundaries.
MIT