> For AI agents: a documentation index is available at https://passlet.dev/llms.txt

# How Passlet works

Understand Agents, Approver, and how scoped credentials reach your coding tools.

Passlet gives coding agents short-lived, scoped GitHub access after you approve a request on your Mac. Approver keeps the long-lived credentials in your Mac’s protected Keychain. Agent runs beside your coding tools, locally or on another machine.

## Install Agent

Approver requires macOS. Agent supports macOS and Linux. Follow the [installation guide](https://passlet.dev/docs/getting-started/installation/) to configure Approver and set up GitHub first.

macOS

### Agent on macOS

The Homebrew cask includes both Approver and Agent:

```sh
brew tap paretosecurity/passlet https://github.com/ParetoSecurity/passlet.git
brew install --cask paretosecurity/passlet/passlet
```

Linux

### Agent on Linux

Install Agent with Homebrew:

```sh
brew tap paretosecurity/passlet https://github.com/ParetoSecurity/passlet.git
brew install paretosecurity/passlet/passlet-agent
```

You can also use [Nix or Home Manager](https://passlet.dev/docs/getting-started/installation/#install-agent-on-a-remote-machine-or-vm).

## How credentials move

```mermaid
sequenceDiagram
    accTitle: Scoped GitHub access through Passlet
    accDescr: Agent requests scoped access from Approver. After native approval on the Mac, Approver requests a token from GitHub and delivers it to Agent. Agent then uses GitHub directly.
    participant Agent
    participant Approver as Approver on your Mac
    participant User as You
    participant GitHub
    Agent->>Approver: Request repositories and permissions
    Approver->>User: Request native approval
    User->>Approver: Approve with Touch ID
    Approver->>GitHub: Request scoped token
    GitHub-->>Approver: Expiring token
    Approver-->>Agent: Scoped token
    Agent->>GitHub: Use approved access directly
```

The connection between Agent and Approver uses paired keys. It can run over a local Unix socket, an SSH-forwarded socket, or Tailscale. See [pairing](https://passlet.dev/docs/guides/setup/#pair-agents) and [Tailscale configuration](https://passlet.dev/docs/guides/setup/#tailscale).

What happens if your Mac goes offline?

### Access after disconnection

Added in version 0.12.0

Delivered tokens continue working until they expire. Sessions under the same OS user can reuse matching grants from the Agent’s private file cache while Approver is offline. Issuing a new token requires Approver to be online and your approval. Use `request --no-cache` to bypass cache lookup and storage. Passlet does not approve new tokens unattended.

## Next steps

* [Install and configure Passlet](https://passlet.dev/docs/getting-started/installation/).
* [Pair a remote Agent](https://passlet.dev/docs/guides/setup/#pair-agents).
* [Troubleshoot access](https://passlet.dev/docs/guides/setup/#diagnostics).
