shush 🤫

中文

An in-memory secret cache agent for CLI tools, accessible via Unix domain sockets. Secrets never touch the filesystem — they live only in a background agent process, protected by peer UID verification and automatic TTL expiry.

Use it as a Go library or as a standalone CLI.

Features

• Memory-only — secrets are never written to disk
• Unix socket IPC — fast, local-only communication
• Peer UID verification — only the same OS user can access the agent (Linux & macOS)
• TTL expiry — secrets automatically expire after a configurable duration
• Secure wipe — secret buffers are zeroed after use
• One-time tokens — register secrets with limited use count (ideal for askpass-style helpers)
• Optional capability token — require a shared token for every request
• Auto-start — agent process launches on demand
• Dual interface — use as a Go library or a CLI tool

Install

Go library

go get github.com/tiangong-dev/shush

CLI (Go)

go install github.com/tiangong-dev/shush/cmd/shush@latest

CLI (Homebrew)

The release pipeline automatically updates Formula/shush.rb.

brew tap tiangong-dev/shush https://github.com/tiangong-dev/shush
brew install tiangong-dev/shush/shush

Upgrade:

brew update
brew upgrade shush

CLI Usage

Agent lifecycle

shush serve  [--socket <path>] [--capability <token>]   # run agent in foreground
shush start  [--socket <path>] [--capability <token>]   # start agent in background
shush stop   [--socket <path>] [--capability <token>]   # stop agent
shush status [--socket <path>] [--capability <token>]   # check if agent is running
shush ping   [--socket <path>] [--capability <token>]   # alias for status
shush version                                            # print version

Secret management

# Store secret (from stdin or --secret)
echo "my-secret" | shush set <key> [--ttl 10m] [--socket <path>] [--capability <token>]
shush set <key> --secret "my-secret" [--capability <token>]

# Retrieve secret
shush get <key> [--capability <token>]

# Clear secret
shush clear <key> [--capability <token>]

One-time tokens

# Create token (secret from stdin)
echo "password" | shush token create [--ttl 2m] [--max-uses 8] [--capability <token>]

# Resolve token and print secret
shush token resolve <token> [--capability <token>]

Default socket: ~/.config/shush/agent.sock (override with --socket or SHUSH_SOCKET env var).
Capability source: --capability / --cap or SHUSH_CAPABILITY env var.

Go Library Usage

Cache & retrieve secrets

import "github.com/tiangong-dev/shush"

client := shush.NewClient("/tmp/my-agent.sock", "my-app-key", 10*time.Minute)
client.Capability = "my-session-capability" // optional

// Store
client.Set([]byte("my-secret"))

// Retrieve
secret, found, err := client.Get()
if found {
    defer shush.Wipe(secret)
    // use secret
}

// Clear
client.Clear()

One-time tokens

// Register a token with 2 allowed uses and 30s TTL
token, cleanup, err := shush.RegisterToken("/tmp/my-agent.sock", "password123", 30*time.Second, 2)
defer cleanup()

// Consume from another process
secret, err := shush.ResolveToken("/tmp/my-agent.sock", token)

Embed in your own CLI

If you're building a CLI tool (like onessh), you can embed the agent server and customize the auto-start command:

// In your "myapp agent serve" handler:
shush.Serve(socketPath, os.Stderr)

// Configure client to auto-start via your own binary:
client := shush.NewClient(socketPath, "myapp-key", 10*time.Minute)
client.ServeArgs = []string{"myapp", "agent", "serve", "--socket"}

Utilities

shush.Ping(socketPath)              // check if agent is running
shush.Stop(socketPath)              // stop the agent
shush.StartProcess(socketPath, nil) // start agent in background
shush.ResolveSocketPath(os.Args[1:])// resolve socket from flag/env/default
shush.ResolveCapability(os.Args[1:])// resolve capability from flag/env
shush.DefaultSocketPath()           // return default socket path
shush.Wipe(secretBytes)             // zero out a byte slice

Security

Mechanism	Detail
Socket permissions	0600 — owner-only access
Peer UID check	SO_PEERCRED (Linux) / LOCAL_PEERCRED (macOS)
Capability token (optional)	Shared token required on every request
Memory safety	Secrets zeroed on expiry, clear, and shutdown
No disk I/O	Nothing is logged or persisted
Token limits	One-time tokens with TTL + max use count

Automated Release (GitHub Actions)

This repository includes a release workflow:

• Trigger: push tag v* (for example: v0.1.0)
• Actions:
  • Build multi-platform binaries (Linux/macOS/Windows, amd64/arm64)
  • Create GitHub Release and checksums automatically
  • Update Homebrew formula (Formula/shush.rb) automatically

Release example:

git tag v0.1.0
git push origin v0.1.0

Before first release, ensure Actions > Workflow permissions is set to Read and write permissions.

License

Unlicense