Skip to content
ParetoSecurityPublic

About

Short-lived credentials for your agents.

Topics

Resources

Contributing

Security policy

Stars

22 stars

Watchers

1 watching

Forks

Latest commit

 

History

84 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Passlet icon Passlet

Short-lived credentials for your agents.
GitHub API actions retain your identity.
Features · Get started · Website · Releases · Discord

About

Give your coding agent GitHub access when it needs it. The agent asks for specific repositories and permissions, and you approve on your Mac with Touch ID.

Passlet delivers a short-lived token the agent can use with Git and gh, even after your Mac goes offline. Your long-lived credentials stay in your Mac's protected Keychain.

Features

Feature What it does
Scoped GitHub access Approve the repositories and permissions needed for each task.
Native approval Review each request on your Mac and approve with Touch ID.
Protected credentials Keep parent tokens, refresh tokens, and client secrets in your Mac's Keychain. Only the scoped token reaches the agent.
Local and remote agents Connect through a local socket, SSH forwarding, or opt-in Tailscale HTTPS.
macOS and Linux agents Run your agents on macOS or Linux.
Claude Code and Codex plugins Let your agent request access and reuse approved grants through the bundled skill.
SSH-agent forwarding Let paired Agents use your Mac’s SSH agent with its normal signing approval, without a persistent tunnel.
Work after approval Use delivered tokens until expiry, even while your Mac is offline.
Audit history Inspect requests, decisions, scopes, and delivery outcomes without recording credentials.

We're hoping to do these next:

Feature Status
Fly.io, AWS, Cloudflare, and Vercel providers Coming soon
Approve requests on Linux and Windows Coming soon
iOS and Android companion apps for approvals Coming soon
Resume setup after organization approval Coming soon
Renew GitHub authorization without recreating your app Coming soon

Install and set up your Mac

Approving requests requires macOS 26 or later on Apple Silicon and a logged-in graphical session.

Install Passlet Approver on your Mac to hold credentials and approve requests. Passlet Agent is included for local coding tools. The guide starts with Nix/Home Manager.

Install through Homebrew or Nix/Home Manager. The package manager installs the CLI and signed approval helper, starts the per-user service, and owns updates and removal.

brew tap ParetoSecurity/passlet https://github.com/ParetoSecurity/passlet.git
brew install --cask ParetoSecurity/passlet/passlet
passlet approver github setup
passlet doctor

The first CLI-only release must publish package metadata before these installation commands are available.

setup github opens your browser to create a personal GitHub App, install it on eligible repositories, and authorize your GitHub account. Review the maximum permissions shown in GitHub. The default maximum requests the highest supported level for the repository, organization, and account permissions in the checked-in GitHub API catalog, including administration, secrets, and account keys. Metadata remains read-only. Enterprise-only and single-file permissions are excluded. Select All repositories during installation; each agent token remains scoped to explicitly approved repositories. Each later agent request must still name its exact repositories and permissions, within that maximum.

Credentials go directly into user-presence-protected Keychain storage (WhenUnlockedThisDeviceOnly). The unused private signing key returned by GitHub is discarded without being written to disk. No shared Passlet app secret or broker is needed. Setup verifies the authorizing user owns the app and that an installation grants its requested permissions with accessible repositories. Pending organization approval shows a waiting page where you can check access after an owner approves. Keep setup running until it completes. If initial setup is interrupted, remove the incomplete app in GitHub before starting a fresh setup. Setup refuses to replace an existing protected credential.

The package-managed LaunchAgent starts at graphical login and restarts after a crash. Manage it with passlet approver stop or restart. For checkout testing, stop the installed service and use the checkout’s passlet approver start in the foreground, then restore the installed service with passlet approver restart when finished. It never unlocks credentials. Successful GitHub setup also pairs the local Agent and selects this Mac as its Approver. See setup and troubleshooting.

Local agents

Successful passlet approver github setup automatically pairs your local Agent and switches its saved connection to this Mac. No separate pairing command, endpoint configuration, SSH, or Tailscale is needed. Clear any explicit PASSLET_ENDPOINT to use the saved setting. If you revoked the local Agent, pair it explicitly to restore access.

Remote agents over SSH

Pair each Agent, then forward the Mac’s shared socket. Approval prompts identify the trusted key’s configured label, such as alice@hetzner. See SSH configuration.

On the remote machine, install the Linux CLI archive and create a private directory under your Unix account:

mkdir -p "$HOME/.local/share/passlet"
chmod 700 "$HOME/.local/share/passlet"

From your Mac, keep this SSH connection open, substituting your actual remote username and host. The path before the colon is the remote absolute path; the path after it is on your Mac:

ssh -NT -o ExitOnForwardFailure=yes \
  -o StreamLocalBindUnlink=yes \
  -R /home/alice/.local/share/passlet/passlet.sock:"$HOME/.local/share/passlet/passlet.sock" \
  alice@hetzner

On that remote account, before starting Claude:

passlet pair --endpoint unix:///home/alice/.local/share/passlet/passlet.sock --code <code>
passlet doctor

The remote SSH server must permit Unix socket forwarding. See SSH server configuration, stale sockets, and Alice/Bob setup. Bob uses his own remote Unix account, socket path, Mac, and GitHub App. Do not share a Unix account or use a shared /tmp/passlet.sock.

Choose an Approver

Run passlet approver pair on your Mac, then copy its passlet pair command to the Agent and approve with Touch ID. Pairing saves the endpoint and trusted keys locally. No configuration files need editing, and Nix rebuilds preserve the pairing. Use passlet doctor to check an existing connection. See pairing and revocation.

Request and use access

Run commands with the minimum scope needed. Passlet reuses cached access or requests approval:

passlet exec --repos acme/project --permissions contents:read \
  -- gh repo view acme/project

Scoped exec and request automatically save approved grants in a private file cache on this Agent machine. Later sessions reuse the narrowest matching grant with at least one minute remaining, including while the Approver is offline. Grants are separated by Agent key, Approver key, and endpoint. Repository requests can reuse organization or account grants for the same owner when the granted permissions cover the request. Matching repository grants are preferred. A broader matching grant keeps its original scope and expiry, it is not narrowed or renewed. Requests without a matching grant require approval.

The cache lives at ~/.local/share/passlet/grants, with mode 0700 on the directory and mode 0600 on its files. Passlet checks ownership and rejects shared files, symlinks, and hard links. Atomic writes prevent partial reads, and locking prevents duplicate approvals from simultaneous sessions. Each paired identity and endpoint retains at most 128 grants. Expired grants are ignored and removed when the cache is updated. Grants survive command exits, upgrades, and machine restarts, but retain their original expiry.

Cache files contain plaintext tokens. Other ordinary OS users cannot read them, but processes under your user and root remain trusted. Backups and snapshots may retain copies. To discard cached access, finish active requests and remove the .json files from the cache directory. Leave its .lock files in place so concurrent requests continue using the same locks. Deleting files does not revoke issued tokens. Clear cached grants after changing GitHub accounts on the Approver.

For fresh approval without cache lookup or storage, use --no-cache --stdout with Bash or Zsh process substitution:

passlet exec \
  --grant <(passlet request --no-cache --stdout --repos acme/project --permissions contents:read) \
  -- gh repo view acme/project

--no-cache never reads, writes, or creates the cache, even if a matching grant exists. It does not remove grants already cached. The grant travels through a separate pipe, leaving the child command's standard input available. It still exists transiently in process memory and in the launched command's environment. This avoids Passlet retaining the grant, but does not make it single-use or isolate processes under the same user. One invocation can run a script containing multiple commands. OS swap or crash dumps may persist process memory.

request prints only a receipt on stderr by default, reporting the user and original expiry without the token. Use --stdout to explicitly emit grant JSON for piping, or --out /private/path/grant.json to create a mode-0600 file without overwriting an existing file. These output options are mutually exclusive. --no-cache requires one of them and leaves existing cached grants untouched.

After a scoped command fails, Passlet checks its token with GitHub. A 401 response removes that token from the cache, so the next scoped invocation can obtain and cache fresh approval. Other responses and network failures leave the cache unchanged. Passlet does not replay failed commands, and successful commands need no extra token check. Saved and piped grants bypass this cache recovery.

exec accepts the same scope and endpoint options to reuse a cached grant or request approval and cache the result. Denied approval or an unavailable Approver prevents the command from starting. Alternatively, use exec --grant /private/path/grant.json -- COMMAND with a saved or piped grant without requesting approval. --grant cannot be combined with scope options. Use HTTPS Git remotes. exec overrides ambient Git/gh credentials for the child and does not save the token in Git configuration. Tokens typically expire in eight hours, as set by GitHub. Parent tokens, refresh tokens, and client secrets never go to the agent.

Tailscale, explicitly opt-in

Enable programs.passlet.service.tailscale = true; with Home Manager, or set tailscale = true in ~/.config/passlet/approver.toml for Homebrew and restart the service.

Passlet keeps its shared local/SSH socket and opens a paired TLS listener at 127.0.0.1:17401. Tailscale Serve forwards TCP port 17400 to it without terminating TLS. Startup reuses matching forwarding, creates it when absent, and refuses conflicts. The GUI Tailscale app is supported, and tailnet HTTPS certificates are not required.

Pair each Agent, using the command printed by passlet approver pair. Permit intended devices on TCP 17400 in tailnet policy. Each user on a shared machine has their own trusted key and approval label. Neither caller headers nor forwarded socket paths determine identity.

Agent plugins

Home Manager users can enable programs.passlet.plugins.claude-code.enable and programs.passlet.plugins.codex.enable. See declarative plugin installation.

Install the native plugin on each agent account. Both plugins use the same Passlet skill. GitHub CLI (gh) is optional: when it is unavailable, the skill uses the GitHub REST API through curl with the same scoped Passlet grant.

Claude Code:

claude plugin marketplace add ParetoSecurity/passlet
claude plugin install passlet@passlet --scope user

Codex CLI:

codex plugin marketplace add ParetoSecurity/passlet
codex plugin add passlet@passlet

Start a new agent session after installation. To update:

# Claude Code
claude plugin marketplace update passlet
claude plugin update passlet@passlet

# Codex CLI
codex plugin marketplace upgrade passlet
codex plugin add passlet@passlet

Install the Passlet CLI separately and configure the transport first. Local Mac agents use the default socket; remote agents establish trust with passlet pair. Installing a plugin does not mint a token or bypass native approval. Remove any previous manually installed standalone Passlet skill to avoid duplicate skills. The skill is also included in release archives and the app's Contents/Resources/skills.

The app and both agent plugins share the same version. The release process generates both plugin manifests alongside the Homebrew/Nix metadata, and the release PR includes them before it is squash-merged and the final release tag is created. Version tags contain matching package and plugin metadata. Do not bump plugin versions separately.

Updating

Use brew upgrade --cask ParetoSecurity/passlet/passlet, or update your pinned Passlet Nix source and activate Home Manager. The package manager restarts the service. Uninstall through the same manager. Credentials and audit history remain in place.

Diagnostics and audit

Run passlet or passlet --help for the command list. Client commands stay at the top level: connect, request, exec, and doctor. Local service and credential commands live under passlet approver: start, stop, restart, doctor, github setup, github reset, and audit. A Mac can approve requests and also run client commands, without choosing an installation mode.

Run passlet approver to discover commands for managing approvals and credentials. passlet doctor checks the selected endpoint, while passlet approver doctor always checks the local service, ignoring PASSLET_ENDPOINT and the saved connection. Both verify GitHub access with native approval and issue no token. A stopped local service fails without prompting. Local socket permission errors, timeouts, and unhealthy responses are reported separately. Denying approval stops diagnostics immediately. After successful verification, local diagnostics show socket and Tailscale listener status and connection instructions for verified Tailscale forwarding.

passlet doctor
passlet approver audit --limit 20

doctor asks for Touch ID approval on the Approver’s Mac, unlocks Keychain, refreshes authorization when needed, and verifies your GitHub identity. It works through local and remote endpoints and returns nonzero if verification fails. It never issues an agent token. audit reads an existing local SQLite database without creating one and shows readable event summaries. Use audit --json for complete structured events, including caller/transport, scopes, decisions, expiry, and delivery outcome, with no credentials.

Trust and failure boundaries

  • Requests infer the app label from CLAUDECODE=1 (Claude) or a nonempty CODEX_THREAD_ID (Codex). Missing or conflicting markers display “Shell”. Inference happens on the Agent machine for both request and exec when requesting access. This label is unverified and does not authenticate the requesting app. The Approver determines the device or socket route separately.
  • A socket connection proves access to the socket, not that Claude initiated it. SSH labels identify the configured socket route, not an authenticated remote host or process. A process running as your Mac user or root can access every route socket. Other processes in the same account can request approval and read that account's delivered grants. Remote root is trusted and can access Alice or Bob's sockets. Prompts describe socket callers honestly.
  • Tailscale identifies a node, not a process or remote Unix account. On a shared host, use separate SSH-forwarded sockets for each user's Mac. The private Tailscale socket trusts Tailscale and processes with access to the same Unix account.
  • Issuing a new grant requires native user presence. Cache hits reuse an existing approval, without contacting the Approver. Concurrent cache misses wait for the current request to finish so they can reuse its grant. Cache hits remain available during approval. There are no automatic approval retries or unattended renewals.
  • If the Mac is offline, continue work requiring no new credential. Bring it online and make a new explicit request when ready. The connection timeout is 5 seconds, server deadline 120 seconds, and client timeout 130 seconds. Timeout or disconnect cancels pending authentication.
  • Tokens are bearer credentials. Anyone who obtains one can use its granted access until expiry. Effective access is constrained by the requested scope, app permissions/installation, and the author's GitHub access. Some GitHub listing endpoints expose metadata beyond the scoped content repositories.
  • Requests accept one repository owner, at most three repositories and eight permissions, with bounded prompt text. No caller-provided description or requested TTL is accepted.
  • A successful response write records delivery from the server's perspective, not proof the agent saved it. Failed rotated-credential storage may require fresh GitHub authorization.

See SSH-agent forwarding for using Secretive from a remote terminal or sudo session.

Development and validation

Install Nix with flakes enabled, then use the pinned devenv shell:

nix-shell
make check-all
make integration             # Linux KVM, or a configured Linux remote builder
make check-macos             # macOS with Apple Command Line Tools

The pinned flake exports lib.integrationTest; nix/tests.nix supplies the repository source to it. On an Apple Silicon Mac with an aarch64 Linux KVM builder, run nix-build nix/tests.nix --argstr system aarch64-linux --no-out-link. Three isolated NixOS guests run real SSH, Unix accounts, Git, gh, and Passlet. Approval and GitHub fixtures exist only in the test binary; production has no bypass switches. These VM tests do not test Keychain, Touch ID, launchd, or Mac sleep/wake.

Swift validation, lifecycle, and helper process tests run with make check-macos and in macOS CI without requesting approval or reading protected credentials. See manual and UI validation and release controls. For a development-signed helper, set PASSLET_PROVISIONING_PROFILE and PASSLET_SIGNING_IDENTITY, then make macos. The output is build/Passlet.app; use a dedicated test account/profile for isolated Keychain testing.

The default package set and Home Manager use the stable 26.05 release. Go 1.27 comes from stable. Only golangci-lint comes from a separate pinned nixpkgs-unstable input because the stable linter is built with Go 1.26. Both package sets are updated by the weekly updater.

nix/flake.lock pins the tools and the non-flake teamniteo/agents input. Entering the environment links upstream rules and skills into .agents (.claude is a committed symlink to it) alongside the repository's own passlet and release-passlet skills. Generated links are ignored and are not release assets. nix flake update --flake ./nix advances these conventions along with dependencies; the lock and workflow pins use the format supported by the Sunday updater in teamniteo/ops. Its updates/projects.yaml still needs a Passlet entry with remote: ParetoSecurity/passlet, flakes: [nix], go: ["."], actions: [.github/workflows], lint: {dir: ".", target: check-all}, ci: ci.yml, and active: true before weekly updates include this repository. Update Go modules inside the shell with go get -u ./... && go mod tidy, then refresh the integration package’s vendorHash in nix/test-package.nix if dependencies changed and run checks. CI uses standard GitHub-hosted runners. Linux uses the same teamniteo/gha-actions/nix environment for linting, coverage enforcement, and tests. macOS uses Go 1.27.3 and native Xcode tools for Go race tests, Swift tests, and Apple Silicon app builds, without loading Nix. A parallel macOS job builds its own app fixture and checks Nix packaging and signature preservation on every run. Linux pulls prebuilt devenv dependencies from the public devenv Cachix cache without a cache credential. GitHub Actions caches Go modules and compilation outputs per OS, architecture, dependency/toolchain lock, and commit, with reuse across commits sharing that lock. Fork PR caches remain scoped by GitHub and are not restored by the signing workflow. NixOS integration runs separately. If a newly pinned Nix dependency is missing from the binary cache, the cold run still builds it from source.

Claude PR reviews

Install the Claude GitHub App for this repository, then run claude setup-token locally and save the result as the CLAUDE_CODE_OAUTH_TOKEN Actions secret. After .github/workflows/claude.yml is merged into main, add a new @claude Please review this PR. comment to the PR conversation. The commenting user needs write access to the repository. Review progress appears in the Claude workflow run and on the PR. See the Claude GitHub Actions setup guide.

License

MIT License. See LICENSE.

Download a development build

The macOS CI job builds and uploads a Apple Silicon app before running its tests. Linux checks and NixOS integration run in parallel. Open the CI runs, select the commit or PR, and download Passlet-macOS-preview.zip from Artifacts once the build job finishes. Extract the ZIP once to obtain Passlet.app. Tests may still be running, so check the complete run before trusting a change. After CI finishes, a bot updates one PR comment with the preview download link, build-job link, and protected-Keychain limitation. The commenting workflow activates after it is merged into the default branch.

Preview builds use ad-hoc signatures without an Apple signing identity, provisioning profile, or notarization. They have a separate dev.passlet.preview bundle identifier and cannot exercise the production protected-Keychain flow. Use them to test CLI features that do not require credentials. Keep the released app installed for real credentials. Do not run preview and release services simultaneously because they share the local service configuration. macOS may require allowing the downloaded preview in System Settings → Privacy & Security. Only run artifacts from code you trust, including when downloading PR builds.

Developer ID signing and notarization remain exclusive to approved releases. To reproduce the preview locally, run PASSLET_BUILD_MODE=unsigned ./scripts/build-macos.sh inside devenv.

Website documentation

Public docs are authored here and rendered at https://passlet.dev/docs/ by teamniteo/site-passlet. docs/site.json selects the pages and their stable URLs. Use Markdown for ordinary pages and MDX for tabs, callouts, and <AddedIn version="unreleased" /> labels. See authoring and release labels.

Docs merges dispatch the website’s docs-deploy.yml workflow using the existing DOCS_PREVIEW_TOKEN repository secret. Successful releases dispatch it again to update release labels. The website builds the latest merged docs, runs its checks, and deploys with its existing CLOUDFLARE_API_TOKEN. Both website workflows must be on main before dispatch succeeds. No additional deploy-hook secret is needed.

Documentation previews

Pushes that change docs/ or CONTRIBUTING.md in ParetoSecurity/passlet build the website from that exact commit. The docs/preview commit status links to the preview, and a bot updates one comment on each open PR with the preview link. Opening or reopening a matching PR also builds a preview so it receives a comment even if the push finished before the PR existed. This applies to branches in the Passlet repository, not forks. Cloudflare version uploads leave the production deployment unchanged.

For initial setup, merge the Passlet documentation first, then the website changes, whose build imports those docs. Preview statuses will fail until the website workflow is on main and both secrets are configured. Set DOCS_PREVIEW_TOKEN in Passlet to a credential with Actions read/write access to teamniteo/site-passlet, and set CLOUDFLARE_API_TOKEN in the website repository to a token with Workers Scripts Edit access for its Cloudflare account. The website's Documentation preview workflow also accepts a full Passlet commit SHA manually. Builds run without deployment credentials, then a separate job uploads the generated static assets using trusted website code.

About

Short-lived credentials for your agents.

Topics

Resources

Contributing

Security policy

Stars

22 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages