Skip to content

About

Personal system configurations, scripts, and documentation for MacOS setup.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

3 stars

Watchers

0 watching

Forks

Latest commit

ย 

History

2,503 Commits

Folders and files

NameName
Last commit message
Last commit date
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

Repository files navigation

Personal System Configuration

CodeScene general Changelog Status

CodeScene Average Code Health CodeScene Hotspot Code Health CodeScene System Mastery CodeScene Missed Goals CodeRabbit Pull Request Reviews

Quality gate

A comprehensive repository for personal system configurations, scripts, and documentation to make my macOS development and gaming setup reproducible and backed up.

Overview

This repository contains configuration files, automation scripts, and detailed documentation for my personal computing environment. Key features:

  • ๐Ÿ” Secure SSH Configuration - 1Password and [Proton Pass (NEW!)] integration with dynamic network support
  • ๐ŸŒ Enhanced VPN + DNS Integration - Windscribe VPN with Control D privacy filtering
  • ๐Ÿ›ก๏ธ Dual Protection System - VPN encryption + DNS privacy filtering with real-time logging
  • ๐Ÿ› ๏ธ Automated Maintenance System - Comprehensive system health monitoring and cleanup (NEW!)
  • โš™๏ธ Development Tools - Optimized configurations for Cursor IDE and terminal workflows
  • ๐ŸŽฎ Gaming Optimization - Specialized DNS profiles for gaming performance
  • ๐Ÿ“ฑ Network Automation - VPN-aware configurations with automatic failover

By keeping these configurations in version control, I can:

  • Back up critical system configurations
  • Track changes over time with full history
  • Reproduce my environment on any new machine
  • Document solutions to complex networking challenges
  • Share working configurations with the community

๐ŸŽฏ Quick Start

ProtonDrive one-way home backup (archived)

The ProtonDrive backup script lives under maintenance archive (not ./scripts/):

# Safe preview (no changes)
./maintenance/bin/archive/protondrive_backup.sh --dry-run --no-delete

# Live mirror into ProtonDrive (uses --delete-delay unless you pass --no-delete)
./maintenance/bin/archive/protondrive_backup.sh --run

Edit ./maintenance/conf/protondrive_backup.exclude to tune exclusions (git repos, build artifacts, caches, etc.). Confirm the archived script still matches your rclone setup before relying on it.

Bootstrap this Mac (idempotent)

cd ~/dev/personal-config
./setup.sh
# Requires: macOS, Homebrew, 1Password CLI (`op`), rclone installed via brew
# Does:
#  - Installs CLI tooling (macos/Brewfile + gh extensions incl. gh-stack)
#  - Links dotfiles (SSH, fish, Cursor/VSCode) with backup/verify
#  - Installs maintenance launchd agents
#  - Prepares Control D / Windscribe helpers
#  - Seeds rclone config from template (fill secrets via 1Password)
#  - Stages media services + LaunchAgents (WebDAV + Alldebrid)

Linting and Formatting

Requires: Trunk CLI โ€” install with brew install trunk-io or curl https://get.trunk.io -fsSL | bash

# Run all linters (full Trunk pass: style + correctness)
make lint

# Correctness-only regression gate โ€” SC2155/SC2145; no Trunk required; fast pre-commit check
make lint-errors

# Auto-fix lint issues
make lint-fix

CodeScene PR remediation

When a PR is blocked by CodeScene code health checks during review/salvage sessions, comment the following on that PR:

/cs-agent skill:fix-code-health-degradations

For canonical triage/salvage policy, see docs/automated-pr-review-agent.md and docs/automated-pr-salvage-agent.md.

Automated Maintenance System (NEW!)

# Check system health
~/dev/personal-config/maintenance/bin/run_all_maintenance.sh health

# Quick system cleanup
~/dev/personal-config/maintenance/bin/run_all_maintenance.sh quick

# Weekly maintenance (Monday)
~/dev/personal-config/maintenance/bin/run_all_maintenance.sh weekly

# Monthly deep clean (1st of month)
~/dev/personal-config/maintenance/bin/run_all_maintenance.sh monthly

# View automation status
launchctl list | grep com.abhimehrotra

# View latest health report
ls ~/Library/Logs/maintenance/health_report-*.txt | tail -1 | xargs cat

Enhanced VPN + DNS Integration

Using Fish Shell Functions (Recommended):

# After installing configs and reloading fish shell (exec fish)
nm-status          # Check current network status
nm-browse          # Switch to Control D browsing mode
nm-privacy         # Switch to Control D privacy mode
nm-gaming          # Switch to Control D gaming mode
nm-vpn             # Switch to Windscribe VPN mode
nm-regress         # Run full regression test
nm-cd-status       # Check Control D daemon status

Using Scripts Directly:

# Preferred: use the unified network mode manager
./scripts/network-mode-manager.sh controld browsing   # Enable Control D DNS mode
./scripts/network-mode-manager.sh windscribe          # Enable Windscribe VPN mode

# Full end-to-end regression (Control D โ†’ Windscribe)
./scripts/network-mode-regression.sh browsing

Control D (2026-07-09): Expect WORKING / local_fallback (profile-aware Local Config, brew ctrld v1.5.3). Check with ./scripts/controld-status.sh. CD Mode is upstream-broken; see AGENTS.md.

Under the hood, controld-system/scripts/controld-manager remains the engine that starts ctrld and applies the correct Control D profile; network-mode-manager.sh wraps this with IPv6 management, DNS routing, and verification.

SSH Configuration

# Install SSH configuration with 1Password integration
./scripts/install_ssh_config.sh

# Test your setup
./tests/test_ssh_config.sh

# Connect to development machine (generic hostnames)
ssh dev-mdns   # Primary (works with/without VPN)
ssh dev-auto   # Smart alias / fallback

Note: SSH dev hosts (dev-mdns, dev-local, dev-auto) are defined locally in ~/.ssh/config.local. See the Troubleshooting section below if connections fail.

Run Performance Benchmarks

# Install hyperfine (one-time setup โ€” required)
brew install hyperfine

# Benchmark all critical scripts
make benchmark

# Benchmark a specific script
./tests/benchmarks/benchmark_scripts.sh nm-status

# Available targets: nm-status, sync-all, verify-all, all

Legacy DNS Management (v3.x)

# Alternative direct DNS switching (without VPN)
# Kept for fallback and historical reference; v4.x prefers network-mode-manager.
sudo dns-privacy     # Privacy mode
sudo dns-gaming      # Gaming mode

๐Ÿ“ Repository Structure

personal-config/
โ”œโ”€โ”€ ๐Ÿ› ๏ธ maintenance/            # Automated Maintenance System (NEW!)
โ”‚   โ”œโ”€โ”€ bin/                   # Executable maintenance scripts
โ”‚   โ”‚   โ”œโ”€โ”€ run_all_maintenance.sh  # Master orchestration script
โ”‚   โ”‚   โ”œโ”€โ”€ health_check.sh    # System health monitoring
โ”‚   โ”‚   โ””โ”€โ”€ quick_cleanup.sh   # Quick system cleanup
โ”‚   โ”œโ”€โ”€ conf/                  # Configuration files
โ”‚   โ”œโ”€โ”€ lib/                   # Shared libraries
โ”‚   โ””โ”€โ”€ README.md              # Maintenance system guide
โ”œโ”€โ”€ ๐ŸŒ windscribe-controld/     # Enhanced VPN + DNS Integration
โ”‚   โ”œโ”€โ”€ windscribe-controld-setup.sh  # Automated setup & verification
โ”‚   โ”œโ”€โ”€ setup-guide.md         # Complete integration guide
โ”‚   โ””โ”€โ”€ ctrld.toml.backup      # Configuration backup
โ”œโ”€โ”€ ๐ŸŒ scripts/network-mode-manager.sh  # Control D โ‡„ Windscribe mode switching
โ”œโ”€โ”€ ๐ŸŒ controld-system/        # Low-level Control D profile management
โ”œโ”€โ”€ ๐Ÿ” configs/                # System Configuration Files
โ”‚   โ”œโ”€โ”€ ssh/                   # SSH configuration
โ”‚   โ”‚   โ”œโ”€โ”€ config             # Main SSH configuration
โ”‚   โ”‚   โ””โ”€โ”€ agent.toml         # 1Password SSH agent settings
โ”‚   โ”œโ”€โ”€ fish/                  # Fish shell configuration
โ”‚   โ””โ”€โ”€ .vscode-R/             # R development settings
โ”œโ”€โ”€ ๐Ÿ“œ scripts/                # Automation Scripts
โ”‚   โ”œโ”€โ”€ ssh/                   # SSH automation
โ”‚   โ”‚   โ”œโ”€โ”€ smart_connect.sh   # Intelligent connection
โ”‚   โ”‚   โ”œโ”€โ”€ check_connections.sh # Connection testing
โ”‚   โ”‚   โ””โ”€โ”€ diagnose_vpn.sh    # VPN troubleshooting
โ”‚   โ””โ”€โ”€ install_ssh_config.sh  # SSH setup automation
โ”œโ”€โ”€ ๐Ÿงช tests/                  # Validation & Testing
โ”‚   โ”œโ”€โ”€ test_ssh_config.sh     # SSH configuration tests
โ”‚   โ””โ”€โ”€ test_config_fish.sh    # Fish shell tests
โ”œโ”€โ”€ ๐Ÿ“š docs/                   # Documentation
โ”‚   โ””โ”€โ”€ ssh/                   # SSH setup guides
โ””โ”€โ”€ ๐ŸŽจ cursor/                 # Cursor IDE themes

โœจ Key Features

๐ŸŒ Dynamic DNS Management (New!)

Intelligent DNS switching system with Control D integration:

Privacy Mode (dns-privacy)

  • Enhanced security filtering
  • Malware & tracking protection
  • Optimized for browsing and AI applications

Gaming Mode (dns-gaming)

  • Minimal filtering for maximum performance
  • Gaming service optimizations (Battle.net, GeForce Now, Overwatch 2)
  • Ultra-low latency DNS resolution

Features:

  • โœ… Windscribe VPN Integration - Seamless VPN compatibility
  • โœ… Profile-Specific DoH Endpoints - Optimized upstream resolvers
  • โœ… Automatic Network Detection - Skips VPN interfaces intelligently
  • โœ… DNS Leak Protection - Built-in firewall integration
  • โœ… Smart Verification - Real-time DNS resolution testing
  • โœ… One-Command Switching - Simple sudo dns-* commands

๐Ÿ” SSH Configuration

Professional SSH setup optimized for development:

Features:

  • ๐Ÿ” 1Password SSH Agent - Secure key management without local storage
  • ๐ŸŒ Dynamic Network Support - VPN-aware connection methods
  • ๐ŸŽจ Cursor IDE Optimized - Perfect remote development setup
  • ๐Ÿ“ฑ mDNS/Bonjour Support - Reliable local machine discovery
  • ๐Ÿ”ง Multiple Fallback Options - Connection reliability guaranteed
  • ๐Ÿ“Š Comprehensive Diagnostics - Built-in testing and troubleshooting

Connection Methods (generic hostnames):

ssh dev-mdns    # Primary (works with/without VPN)
ssh dev-local   # Local network only
ssh dev-auto    # Auto-detection fallback

๐Ÿš€ Installation

Complete Setup (Recommended)

# Clone the repository
git clone <your-repo-url> ~/dev/personal-config
cd ~/dev/personal-config

# Install all configuration files (symlinks to home directory)
./scripts/install_all_configs.sh

# This will:
# - Create symlinks for SSH, Fish shell, Cursor, VS Code configs
# - Backup any existing configuration files
# - Verify all symlinks are correctly established
# - Set up Control D fish functions

# Reload fish shell to use new functions
exec fish

# Test Control D functions
nm-status          # Check network status

Configuration Management (Symlink-Based)

This repository uses a symlink-based configuration model where repository files are linked to your home directory. This ensures:

  • โœ… Repository updates automatically reflect in your home directory
  • โœ… Single source of truth for all configurations
  • โœ… Easy backup and restore via git

Symlinked Configurations:

  • ~/.ssh/config โ†’ configs/ssh/config
  • ~/.ssh/agent.toml โ†’ configs/ssh/agent.toml
  • ~/.config/fish/ โ†’ configs/.config/fish/
  • ~/.cursor/ โ†’ .cursor/
  • ~/.vscode/ โ†’ .vscode/

Management Commands:

# Sync all configs (create/update symlinks)
./scripts/sync_all_configs.sh

# Verify all symlinks are correct
./scripts/verify_all_configs.sh

# Complete installation (sync + verify)
./scripts/install_all_configs.sh

Individual Component Setup

SSH Configuration Only

# Quick install
./scripts/install_ssh_config.sh

# Or use the sync script
./scripts/sync_ssh_config.sh
./scripts/verify_ssh_config.sh

DNS / network mode switching

# Show current Control D / Windscribe state
./scripts/network-mode-manager.sh status

# Standalone Control D (profiles: browsing|privacy|gaming)
./scripts/network-mode-manager.sh controld privacy

# Verify expected state
./scripts/network-mode-verify.sh controld privacy

See AGENTS.md for DoH/DoH3 ร— IPv6 mode matrix and repair notes.

SSH Configuration Only

# Quick install
./scripts/install_ssh_config.sh

# Manual install
cp configs/ssh/config ~/.ssh/config
cp configs/ssh/agent.toml ~/.ssh/agent.toml
chmod 600 ~/.ssh/config ~/.ssh/agent.toml

๐Ÿ”ง Configuration

Environment Setup

# Add required environment variables
export PATH="$HOME/bin:$PATH"  # For DNS scripts

# Optional: Set Control D profile IDs
export CTRLD_PRIVACY_PROFILE=<Privacy-Profile-ID>
export CTRLD_GAMING_PROFILE=<Gaming-Profile-ID>

Media automation (Infuse + Alldebrid + cloud union)

  • Data roots: iCloud Desktop/Documents (~/Library/Mobile Documents/com~apple~CloudDocs/Media) via rclone union of gdrive:Media + onedrive:Media (no local duplication).
  • WebDAV server: LaunchAgent com.<your-home-folder>.media.webdav runs /Users/<your-home-folder>/Library/Media/bin/start-media-server.sh on port 8088 (read-only).
  • Alldebrid helper: LaunchAgent com.<your-home-folder>.media.alldebrid mounts to /Users/<your-home-folder>/mnt/alldebrid and serves on 8080.
  • Secrets:
    • ~/.config/rclone/rclone.conf (seed from media-streaming/configs/rclone.conf.template, fill via op inject).
    • ~/.config/media-server/credentials (optional fallback only in the current 1Password-first setup) (untracked; copy media-streaming/configs/media-credentials.example and inject creds with 1Password).
  • Cache & logs: ~/Library/Application Support/MediaCache (kept out of iCloud) and ~/Library/Logs/media/*.out|*.err.
  • Control: launchctl list | grep media to verify; manual start: ~/Library/Media/bin/start-media-server.sh.

MCP tooling

  • Templates live in mcp-configs/README.md and mcp-configs/mcp-servers.template.json.
  • Copy the template to a local servers.local.json, fill keys from 1Password, and keep it gitignored (patterns already in .gitignore).
  • When running commands that need secrets resolved from 1Password, use op run -- <command> (e.g., op run -- uv run python main.py --dry-run --profiles dummy).

VPN Integration

Windscribe Configuration:

  • VPN Tunnel DNS: Leave default (inherits Control D)
  • App Internal DNS: Set to "OS Default"
  • Firewall: Enable for DNS leak protection

ProtonVPN Alternative:

  • Use Control D custom DNS when needed

๐Ÿงช Testing & Verification

Running Tests

This repository includes a comprehensive test suite. The shell tests run in parallel by default for maximum performance.

# Run all shell tests in parallel (automatically ignores known macOS-specific failures)
make test

# Run smoke test subset only โ€” fast, cross-platform, ideal for pre-commit hooks
make test-quick

# Run a single shell test
bash tests/test_ssh_config.sh

# Run all Python tests
make test-python

# Run all tests (shell + Python)
make test-all

# Run all Python tests directly (alternative)
python3 -m unittest discover -s tests -p 'test_*.py' -v

DNS System

# Test current DNS resolution
dig +short google.com @127.0.0.1

# Check active profile
dig +short txt test.controld.com @127.0.0.1

# Verify system DNS configuration
scutil --dns | head -20

SSH Configuration

# Comprehensive SSH tests
./tests/test_ssh_config.sh

# Test all connection methods
./scripts/ssh/check_connections.sh

# Manual connection verification
./scripts/ssh/setup_verification.sh

โšก Performance Benchmarking

This repository includes a performance benchmarking infrastructure for tracking script execution speed and detecting performance regressions.

Quick Start

# Install hyperfine (required dependency)
brew install hyperfine

# Run all benchmarks
make benchmark

# Run specific benchmark
./tests/benchmarks/benchmark_scripts.sh nm-status

Available Benchmark Targets

Target Script Description
nm-status network-mode-manager.sh status Network mode status check
sync-all sync_all_configs.sh Configuration sync operations
verify-all verify_all_configs.sh Configuration verification
all All scripts above Run all benchmarks (default)

Benchmark Configuration

  • Warmup Runs: 2 iterations to prime caches
  • Benchmark Runs: 5 iterations for statistical accuracy
  • Baseline Storage: tests/benchmarks/baselines/*.json

Usage Examples

# Benchmark network mode status check
./tests/benchmarks/benchmark_scripts.sh nm-status

# Benchmark config sync performance
./tests/benchmarks/benchmark_scripts.sh sync-all

# Benchmark verification speed
./tests/benchmarks/benchmark_scripts.sh verify-all

# Run all benchmarks via Makefile
make benchmark

Baseline Results

Results are saved as JSON files in tests/benchmarks/baselines/ for:

  • Performance regression tracking
  • Before/after optimization comparisons
  • CI/CD integration potential

๐Ÿ“Š Monitoring & Maintenance

DNS Logs

# View DNS switching logs
sudo tail -f /var/log/ctrld-privacy.log
sudo tail -f /var/log/ctrld-gaming.log

# Check daemon status
sudo lsof -nP -iTCP:53 -sTCP:LISTEN -iUDP:53

System Health

# Network diagnostics
./scripts/ssh/diagnose_vpn.sh

# DNS resolution testing
for server in 127.0.0.1 8.8.8.8 1.1.1.1; do
  echo "Testing $server:"
  dig +short google.com @$server
done

๐ŸŽฎ Use Cases

Development Workflow

  1. Connect: ssh dev-mdns
  2. Privacy Mode: sudo dns-privacy
  3. **Code with enhanced security filtering`

Gaming Session

  1. Gaming Mode: sudo dns-gaming
  2. Minimal filtering for maximum performance
  3. Optimized for Battle.net, Steam, Nvidia GeForce Now, Overwatch 2

VPN Switching

  1. Windscribe VPN: Default setup with Control D integration
  2. Proton VPN: When port forwarding or different geo-location needed
  3. DNS profiles work seamlessly with both

๐Ÿ”’ Security & Privacy

  • ๐Ÿ” Secrets Management: Uses 1Password for SSH keys, environment variables for configs
  • ๐ŸŒ DNS Leak Protection: Built-in firewall integration prevents leaks
  • ๐Ÿ›ก๏ธ Profile Isolation: Separate DNS policies for different use cases
  • ๐Ÿ“Š Verification: Real-time testing ensures configuration integrity
  • ๐Ÿ”„ Version Control: All changes tracked with full history

๐Ÿ› ๏ธ Troubleshooting

Common Issues

DNS switching problems:

# Check what's using port 53
sudo lsof -nP -iTCP:53 -sTCP:LISTEN -iUDP:53

# Reset DNS to defaults
for s in $(networksetup -listallnetworkservices | tail -n +2 | sed 's/^\*//'); do
  sudo networksetup -setdnsservers "$s" empty || true
done

SSH connection issues:

# Comprehensive diagnostics
./scripts/ssh/diagnose_vpn.sh

# Test individual connection methods
./scripts/ssh/check_connections.sh

Support Resources

๐Ÿ“Œ Pinned Formulae (Homebrew)

Some Homebrew formulae are pinned to protect a working install from brew upgrade. scripts/pin-redshift.sh manages the redshift entry below; the block between the markers is auto-generated, so update it via the script rather than by hand.

Formula Version Pinned (date) Disable date
redshift 1.12_1 2026-06-25 2027-06-21

Why redshift is pinned: the core formula is deprecated (upstream is unmaintained; last release was 1.12), and Homebrew has it scheduled for disable on June 21, 2027. Pinning keeps the current build from being upgraded/reinstalled out from under the True Tone + manual-elevation config in configs/.config/redshift/redshift.conf. Pinning protects through the deprecation window only; it does not survive the disable date, see the escape hatch below.

Manage the pin:

./scripts/pin-redshift.sh           # pin redshift + refresh the block above
./scripts/pin-redshift.sh --fetch   # also cache the bottle and record its path
brew list --pinned                  # confirm what is pinned
brew unpin redshift                 # release the pin when migrating

Escape hatch after the disable date (source build)

When redshift is disabled, a cached bottle is not a reliable long-term fallback: a bottle is a frozen binary compiled against today's macOS SDK and today's glib/gettext, so an OS bump or a dependency upgrade can break its linkage with no way to rebuild it. The durable path is a from-source build, vendored into a personal tap so brew keeps managing it and recompiles against whatever libraries are current at the time:

brew tap-new "$USER/local"
brew extract --version=1.12 redshift "$USER/local"
brew install --build-from-source "$USER/local/redshift@1.12"

A cached bottle is still worth keeping as a convenience snapshot for a quick same-OS reinstall, but treat it as disposable, not as the guarantee. Its resolved location (populated by --fetch) lives outside this repo:

  • Cached bottle artifact (lives outside this repo โ€” do not commit): /Users/speedybee/Library/Caches/Homebrew/downloads/623d419163f0150768b1328191f9fb4095d89066e4452abf965ff39f3abf095a--redshift--1.12_1.arm64_tahoe.bottle.1.tar.gz

๐Ÿšง Future Enhancements

  • Automated VPN Detection - Dynamic VPN provider switching
  • Profile Scheduling - Time-based DNS profile switching
  • Network Location Awareness - Location-based configuration switching
  • Performance Monitoring - DNS resolution latency tracking
  • Mobile Device Integration - iOS/Android configuration sync
  • Backup Automation - Scheduled configuration backups

๐Ÿ“ˆ Version History

  • v4.1 (November 2025) - Network mode manager + regression harness; refined verification & docs; archived legacy Windscribe glue.
  • v4.0 (October 2025) - Enhanced VPN + DNS Integration with Windscribe + Control D
  • v3.0 (September 2025) - Dynamic DNS Management System
  • v2.0 (August 2025) - SSH Configuration with 1Password
  • v1.0 (April 2025) - Initial repository structure

๐Ÿ“„ License

Personal use configurations. Feel free to adapt and use any parts that are helpful for your own setup.


๐ŸŽ‰ Your complete development and gaming network is now perfectly automated!

Last Updated: November 19, 2025 VPN + DNS Integration: v4.1 DNS Management System: v3.0 SSH Configuration: v2.0

๐Ÿ”ง Configuration Details

SSH Configuration (1Password-managed)

  • Single source of truth for SSH config and agent settings lives in this repo:
    • configs/ssh/config
    • configs/ssh/agent.toml
  • Local symlinks:
    • ~/.ssh/config โ†’ ~/dev/personal-config/configs/ssh/config
    • ~/.ssh/agent.toml โ†’ ~/dev/personal-config/configs/ssh/agent.toml
  • 1Password integration:
    • Include ~/.ssh/1Password/config
    • IdentityAgent: ~/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock
  • Multiplexing control dir:
    • ~/.ssh/control (700)

Maintenance:

  • Verify: scripts/verify_ssh_config.sh
  • Sync: scripts/sync_ssh_config.sh

Notes:

  • Keep 1Password unlocked with SSH agent integration enabled.
  • No private keys are stored in ~/.ssh; all keys are 1Password-managed.

Proton Pass SSH (optional second agent)

  • Proton vaults:

    • Personal (general items)
    • SSH Keys (dedicated vault for SSH keys)
  • Helper scripts (all under scripts/ssh/):

    • op_to_proton_import.sh โ€“ paste a private key from 1Password โ†’ import into Proton (SSH Keys vault) with a secure temp file workflow.
    • proton_ssh_helpers.sh โ€“ wrapper for:
      • start-agent โ€“ pass-cli ssh-agent start --vault-name "SSH Keys"
      • load-into-agent โ€“ pass-cli ssh-agent load --vault-name "SSH Keys"
      • import-key โ€“ calls op_to_proton_import.sh.
  • Fish functions (auto-loaded from ~/.config/fish/conf.d/proton_pass_ssh.fish):

    • pp_ssh_agent_start โ€“ start Proton SSH agent for SSH Keys vault.
    • pp_use_proton_agent โ€“ point current shell at Protonโ€™s agent socket.
    • pp_load_proton_into_agent โ€“ load Proton keys into whatever agent SSH_AUTH_SOCK points at.
    • pp_which_agent โ€“ show active agent + listed keys.
    • Abbreviations: pp-start, pp-load, pp-import (wrappers around the above).
  • SSH host aliases (in configs/ssh/config):

    • github-proton โ€“ same as github.com but bound to Protonโ€™s IdentityAgent.
    • proton-* โ€“ any host matching this pattern prefers Protonโ€™s agent.
  • Shell integration (fish / zsh / bash + agent-shell workspaces):

    • SSH_AUTH_SOCK auto-selects ~/.ssh/proton-pass-ssh-agent.sock when the agent is actually responding (probed with ssh-add -l); falls back to the 1Password / launchd agent otherwise.
    • Override with PROTON_AGENT_SKIP=1; skipped in agent/CI contexts (CURSOR_AGENT, CI, GITHUB_ACTIONS) and non-interactive fish.

Usage examples:

# Import a key from 1Password into Proton (SSH Keys vault)
./scripts/ssh/op_to_proton_import.sh "GitHub main SSH key"

# Start Proton SSH agent (dedicated tab)
./scripts/ssh/proton_ssh_helpers.sh start-agent

# In a different shell, point SSH to Proton agent
pp-start         # or: pp_ssh_agent_start in one tab
pp-use-proton    # then: ssh -T git@github-proton

Fish Shell Configuration

The Fish setup in this repo is meant to stay practical, reproducible, and easy to recover after a rebuild.

Source of truth:

  • ~/dev/personal-config/configs/.config/fish/config.fish
  • ~/.config/fish/ should be symlinked to configs/.config/fish/

What the Fish config does:

  • sets up core PATH entries and shell defaults
  • configures NM_ROOT as ~/dev/personal-config
  • prefers the 1Password SSH agent and falls back to the macOS native agent when needed
  • initializes interactive tools such as chruby-fish, fnm, zoxide, and fzf
  • keeps a Dracula-aligned experience across Fish syntax colors, Tide, fzf, and bat
  • provides aliases, abbreviations, autoloaded helper functions, and a time-based greeting

Theme layering:

  • Ghostty provides the terminal color theme
  • Tide manages prompt styling via universal variables
  • Fish syntax highlighting is repaired on interactive startup by __ensure_dracula_theme, which re-runs fish_config theme choose "Dracula Official" only when drift is detected
  • fzf uses Dracula colors with the full style preset via FZF_DEFAULT_OPTS

Control D network mode functions:

After reloading Fish with exec fish, these helpers are available:

Function / abbr Description
nm-status (nms) Check current network status (Control D vs Windscribe)
nm-browse (nmb) Standalone Control D browsing (default doh3-ipv6)
nm-privacy (nmp) Standalone Control D privacy (default doh3-ipv6)
nm-gaming (nmg) Standalone Control D gaming (default doh3-ipv6)
nm-doh (nmpd/nmbd/nmgd) Standalone DoH + IPv6 off (doh-ipv4)
nm-doh6 (nmp6/nmb6/nmg6) Standalone DoH + IPv6 on (doh-ipv6)
nm-vpn (nmv/nmvp/nmvb/nmvg) Windscribe + Control D (auto IPv6)
nm-vpn4 (nmvp4/nmvb4/nmvg4) Windscribe + Control D, force IPv6 off
nm-vpn6 (nmvp6/nmvb6/nmvg6) Windscribe + Control D, force IPv6 on
nm-regress (nmr) Run full regression test (Control D โ†’ Windscribe)
nm-cd-status (nmcs) Check Control D daemon status

VPN abbrs accept a location: nmvp4 Dallas (static IPv4) or nmvp6 Atlanta (IPv6 non-static). Defaults match windscribe-connect.sh (Dallas static / Atlanta when forcing IPv6).

Safe files to edit manually:

  • configs/.config/fish/config.fish
  • configs/.config/fish/fish_plugins
  • configs/.config/fish/RESTORE_CUSTOMIZATIONS.md
  • configs/.config/fish/functions/__ensure_dracula_theme.fish
  • configs/.config/fish/functions/fish_greeting.fish
  • configs/.config/fish/functions/git-mirror-clean.fish
  • configs/.config/fish/functions/vibe.fish
  • configs/.config/fish/functions/__run_editor.fish

Usually plugin-managed or machine-generated:

  • configs/.config/fish/conf.d/*.fish
  • configs/.config/fish/functions/_fzf_*
  • configs/.config/fish/functions/_tide_*
  • configs/.config/fish/fish_variables

Useful commands:

exec fish
fish --no-config --no-execute ~/dev/personal-config/configs/.config/fish/config.fish
fisher update

About

Personal system configurations, scripts, and documentation for MacOS setup.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

3 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages