Get started with Passlet

Lazy? Let your agent do this for you macOS · · · GitHub

01 / A QUICK INTRODUCTION

Two Passlet components: an Agent and the Approver

Passlet supports any local or remote agent and a number of providers, but let’s keep this guide simple and connect Claude to GitHub.

Agent

A CLI your coding agent uses to request temporary, scoped credentials. No background process.

Approver

A macOS background service. Uses full-access long-lived credentials stored in macOS Keychain to mint scoped short-lived tokens.

This guide installs both on your Mac, which requires macOS 26 or later on Apple Silicon. For remote agents, install just the Agent CLI.

Which coding tool will you use?
Which package manager do you use?

02 / INSTALL

Install Passlet on your Mac

Open Terminal on your Mac and run these commands. They install the two Passlet components: the Agent and the Approver.

Mac terminal
brew tap paretosecurity/passlet https://github.com/ParetoSecurity/passlet.git
brew install --cask paretosecurity/passlet/passlet

What to expect

Homebrew installs Passlet and configures the Approver service to start when you log in.

Add Passlet to your flake inputs, then enable its Home Manager module.

flake.nix inputs
passlet = {
  url = "github:ParetoSecurity/passlet";
  inputs.nixpkgs.follows = "nixpkgs";
};
Home Manager · Claude Code
imports = [ passlet.homeManagerModules.default ];
programs.passlet.enable = true;
programs.passlet.plugins.claude-code.enable = true;
Home Manager · Codex
imports = [ passlet.homeManagerModules.default ];
programs.passlet.enable = true;
programs.passlet.plugins.codex.enable = true;

Requires Home Manager 26.05 or newer.

What to expect

Rebuilding your Home Manager configuration installs Passlet and its Claude plugin, and configures the Approver service to start when you log in.

Install the Claude plugin

The Passlet plugin gives Claude instructions for requesting access and reusing approved grants.

Claude Code

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

Codex CLI

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

Start a new session

After installation, open a new Claude session to make sure the plugin is loaded. Installing it does not grant GitHub access.

03 / CONNECT

Pair Passlet with GitHub

Run the Passlet GitHub setup from a Terminal.

Mac terminal
passlet approver github setup

Passlet creates a personalized GitHub App for you. This app is used to mint short-lived tokens for agents.

Install passlet-alice

Where do you want to install passlet-alice?

Choose which repositories Passlet can grant access to, then click Install.

Install passlet-alice

Install on your personal account Alice

for these repositories:

All repositories

This applies to all current and future repositories owned by the resource owner. Also includes public repositories (read-only).

Only select repositories

Select at least one repository. Also includes public repositories (read-only).

Alice/hello-world

Review the requested permissions below.

Install

This is it, Passlet is paired with GitHub!

alice — Terminal
$ passlet approver github setup

[...]

Waiting for installation…

GitHub access enabled for alice.

Local Agent paired and connected to this Mac.

04 / YOUR FIRST REQUEST

Now let Claude ask you for access

Send this prompt in your new session. Claude will find the repository and request the access it needs.

Ask your coding agent
Show me the README of my most recently updated private GitHub repository
1. Find your latest repository

Passlet is trying to grant access to GitHub for:
• Claude from alice@macbook
• 8 hours

Account: alice

Repositories:
• all

Touch ID or enter your password to continue with Passlet.

2. Read its contents

Passlet is trying to grant access to GitHub for:
• Claude from alice@macbook
• 8 hours

Repositories:
• alice/hello-world

Permissions:
• contents: read

Touch ID or enter your password to continue with Passlet.

Claude
Claude Code v2.1
Opus 5.5 · Claude Ultra
~/work/
❯ Show me the README of my most recently updated private GitHub repository

Skill(passlet:passlet)
└ Successfully loaded skill

Ran 2 shell commands

● I’ll use Passlet to find your latest repository. Expect a Touch ID prompt.

Ran 2 shell commands

● Your latest repository is alice/hello-world. I’m requesting contents:read to read its README. Expect a second Touch ID prompt.

Ran 1 shell command

● Here’s the README from alice/hello-world:

Hello, world

A small collection of scripts for everyday tasks.

OpenAI Codex (v0.160)
~/work

Access approved through Passlet.

Your most recently updated repository is alice/hello-world. Here’s its README:

Hello, world

A small collection of scripts for everyday tasks.

SETUP COMPLETE

What’s next?

You’ve given Claude scoped access to GitHub. Here’s what you can do next.

Work across organizations

Run passlet approver github setup again and connect another GitHub organization.

Connect a remote agent via Tailscale

  1. Add tailscale = true to ~/.config/passlet/approver.toml on your Mac. Add programs.passlet.service.tailscale = true; to your Home Manager configuration.
  2. Restart Passlet Approver with passlet approver restart.
  3. Install Passlet Agent on the remote machine: macOS or Linux.
  4. Run passlet approver pair on your Mac and follow the instructions.

See Tailscale setup for details. You can use SSH forwarding on non-Tailscale devices.

Approve remote sudo access with Touch ID

Configure your Linux server to authenticate sudo through your Mac’s SSH agent, with Touch ID approval on your Mac.