Startup IT Troubleshooting
Runbooks for startups and small teams where engineers double as the IT department.
When to Use
You are the "accidental IT person." Nobody has IT in their title, but laptops freeze, Wi-Fi drops during investor demos, someone gets locked out of Google Workspace at midnight, and a new hire starts Monday with zero accounts. Commands are platform/version-specific examples. Start read-only, preserve current configuration and apply only authorized, reviewed changes to the exact account/device.
Priority triage: (1) Company-wide outages, (2) Executive/customer-facing blockers, (3) Team-wide degradations, (4) Individual workstation issues. Always ask: "How many people are affected?" and "Is revenue impacted?"
SSO / Identity Lockouts
Google Workspace via GAM
bash
# Obtain GAM from its official project, pin/verify the release and inspect installation instructions before installing.
gam oauth create # authorize
# Reset through the approved secure admin workflow; never literal or generated passwords in process argv.
gam update user jane@company.com suspended off # unsuspend locked-out user
gam user jane@company.com signout # force sign-out all sessions
gam user jane@company.com update backupcodes # new MFA backup codes
# Do not disable2SV as routine recovery; use verified recovery/backup methods.
Okta API
bash
: "${OKTA_DOMAIN:?Set the authorized Okta domain}"
: "${OKTA_API_TOKEN:?Inject admin token securely}"
: "${OKTA_USER_ID:?Verify the exact target user}"
curl -X POST -H "Authorization: SSWS $OKTA_API_TOKEN" "https://$OKTA_DOMAIN/api/v1/users/$OKTA_USER_ID/lifecycle/unlock"
curl -X POST -H "Authorization: SSWS $OKTA_API_TOKEN" "https://$OKTA_DOMAIN/api/v1/users/$OKTA_USER_ID/lifecycle/reset_password?sendEmail=true"
curl -X POST -H "Authorization: SSWS $OKTA_API_TOKEN" "https://$OKTA_DOMAIN/api/v1/users/$OKTA_USER_ID/lifecycle/reset_factors"
curl -X DELETE -H "Authorization: SSWS $OKTA_API_TOKEN" "https://$OKTA_DOMAIN/api/v1/users/$OKTA_USER_ID/sessions"
MFA recovery flow: Verify identity with the established independent recovery procedure (a video call alone is insufficient), generate backup codes or reset factors, have user re-enroll immediately, confirm old device is deregistered, log the incident.
Network resets, DNS overrides and VPN resets can break managed policy or remote access. Record current resolver/interface settings first, choose the actual interface and restore them after diagnostics. Public DNS may not resolve internal zones and may disclose internal queries. Package/update/reboot, encryption, account transfer and printer-queue changes below are separate mutating actions, not an automatic checklist.
Network Troubleshooting
Wi-Fi Debugging
bash
# macOS
/System/Library/PrivateFrameworks/Apple80211.framework/Versions/Current/Resources/airport -I
networksetup -setairportpower en0 off && sleep 2 && networksetup -setairportpower en0 on
sudo dscacheutil -flushcache && sudo killall -HUP mDNSResponder
# Linux
nmcli device wifi list && nmcli connection show --active
nmcli device disconnect wlan0 && nmcli device connect wlan0
sudo systemd-resolve --flush-caches
powershell
netsh wlan show interfaces
netsh wlan disconnect; netsh wlan connect name="OfficeWiFi"
ipconfig /flushdns
netsh winsock reset # full stack reset, reboot after
DNS Issues
bash
nslookup company.com 8.8.8.8 # test against known-good DNS
dig @1.1.1.1 company.com # Linux/macOS detail
sudo networksetup -setdnsservers Wi-Fi 8.8.8.8 8.8.4.4 # macOS temp override
powershell
$a = Get-NetAdapter | Where-Object {$_.Status -eq "Up"}
Set-DnsClientServerAddress -InterfaceIndex $a.ifIndex -ServerAddresses ("8.8.8.8","8.8.4.4")
VPN Not Connecting
bash
nc -zv vpn.company.com 443 # test port reachability
sudo wg show # WireGuard status
sudo wg-quick down wg0 && sudo wg-quick up wg0 # restart WireGuard
tailscale status && sudo tailscale up --reset # Tailscale re-auth
Slow Internet
bash
speedtest-cli --simple # bandwidth test (pip install speedtest-cli)
ping -c 50 8.8.8.8 # packet loss check
networkQuality -s # macOS 12+ bufferbloat test
Laptop Performance
Disk Space
bash
df -h # volume overview
du -sh ~/* | sort -rh | head -15 # biggest dirs in home
docker system df # Docker disk usage (common culprit)
docker system df -v # inventory; review exact unused artifacts/volumes before deletion
brew cleanup --prune=all # macOS Homebrew cleanup
powershell
Get-PSDrive -PSProvider FileSystem | Select Name,@{N='Free(GB)';E={[math]::Round($_.Free/1GB,2)}}
Get-ChildItem C:\ -Recurse -File -EA SilentlyContinue | Sort Length -Desc | Select -First 15 FullName,@{N='MB';E={[math]::Round($_.Length/1MB,2)}}
Memory Pressure and Runaway Processes
bash
# macOS
memory_pressure
top -o rsize -l 1 -n 10 -stats pid,command,rsize
# Inspect exact processes and save work before quitting; avoid broad pkill patterns.
# Linux
free -h && ps aux --sort=-%mem | head -11
sudo dmesg | grep -i "oom\|out of memory"
powershell
Get-Process | Sort WorkingSet64 -Desc | Select -First 10 Name,@{N='MB';E={[math]::Round($_.WorkingSet64/1MB,2)}}
# Quit the verified application after saving work; force termination is a separate approved recovery.
Battery Health
bash
system_profiler SPPowerDataType | grep -E "Cycle Count|Condition" # macOS
upower -i /org/freedesktop/UPower/devices/battery_BAT0 # Linux
powershell
powercfg /batteryreport /output "$env:USERPROFILE\Desktop\battery.html"
macOS Administration
bash
profiles status -type enrollment # MDM enrollment check
sudo systemsetup -getremotelogin # inspect; enabling SSH changes remote access
# Homebrew fleet setup — standard Brewfile
cat > Brewfile <<'EOF'
brew "git"; brew "node"; brew "python@3.12"; brew "awscli"; brew "jq"; brew "gh"
cask "google-chrome"; cask "slack"; cask "1password"; cask "visual-studio-code"; cask "docker"; cask "zoom"
EOF
brew bundle install --file=Brewfile
brew bundle dump --file=~/Brewfile --force # export current setup
# FileVault
sudo fdesetup status && sudo fdesetup enable # store recovery key in 1Password
# Updates
softwareupdate -l # schedule installation/restart only after approved downtime
Windows Administration
powershell
gpresult /r; gpupdate /force # check and refresh Group Policy
# Windows Update
Install-Module PSWindowsUpdate -Force -Scope CurrentUser
Get-WindowsUpdate # review and schedule approved install/reboot
# If stuck: reset update components
Stop-Service wuauserv,cryptSvc,bits,msiserver -Force
# Follow the supported repair procedure; preserve diagnostics instead of blind recursive deletion.
Start-Service wuauserv,cryptSvc,bits,msiserver
# BitLocker
manage-bde -status C:
Enable-BitLocker -MountPoint "C:" -EncryptionMethod XtsAes256 -UsedSpaceOnly -TpmProtector
# Remote Desktop
Set-ItemProperty -Path 'HKLM:\System\CurrentControlSet\Control\Terminal Server' -Name "fDenyTSConnections" -Value 0
Enable-NetFirewallRule -DisplayGroup "Remote Desktop"
Linux Desktop
bash
# Ubuntu — fix broken packages
sudo apt --fix-broken install && sudo dpkg --configure -a && sudo apt update && sudo apt upgrade -y
# Fedora — fix broken packages
sudo dnf check && sudo dnf distro-sync && sudo dnf update -y
# Service failures
systemctl --failed
journalctl -p err -b
# Drivers
sudo ubuntu-drivers autoinstall # Ubuntu proprietary drivers
lspci | grep -i vga && sudo lshw -C display # GPU info
sudo dmesg | grep -i firmware # missing firmware
# Display issues
xrandr --auto # reset to auto-detect
xrandr --output HDMI-1 --mode 1920x1080 --rate 60 # force resolution
echo $XDG_SESSION_TYPE # Wayland vs X11 check
Email / Calendar Issues
Google Workspace
bash
gam user jane@company.com show forwarding # check rogue forwarding rules
gam user jane@company.com delete forwarding # remove forwarding
gam user jane@company.com show delegates # check email delegation
gam user jane@company.com show filters # check mail filters
Microsoft 365
powershell
Install-Module ExchangeOnlineManagement -Force -Scope CurrentUser
Connect-ExchangeOnline -UserPrincipalName admin@company.com
Get-MessageTrace -SenderAddress jane@company.com -StartDate (Get-Date).AddDays(-7) -EndDate (Get-Date)
Get-MailboxStatistics -Identity jane@company.com | Select DisplayName,TotalItemSize
Email Deliverability
bash
dig TXT company.com | grep "v=spf1" # SPF
dig TXT google._domainkey.company.com # DKIM
dig TXT _dmarc.company.com # DMARC
Onboarding Checklist
bash
# Provision only the approved joiner, role, start date and groups through the IdP.
# Use secure credential bootstrap; no shared welcome password or token in CLI flags.
# Send invitations only to the verified corporate identity and approved teams.
# Discover supported GAM/1Password/Slack/Tailscale commands for the installed versions;
# use SSO/secure secret injection instead of literal admin tokens/auth keys.
First-Day Setup Script (macOS)
Give new hires a reviewed, versioned setup procedure. Download installers only from official sources, verify their release identity and inspect them before authorized execution. Inspect the exact hosted Brewfile and package sources before installation. Preserve existing Git settings; configure identity only as requested. Enable FileVault only after recovery-key escrow is verified; never claim escrow succeeded from a comment.
Offboarding Checklist
Apply the approved offboarding plan at the authorized time, after confirming identity, holds/retention and transfer scope. Suspension, session revocation, data transfer and mailbox delegation are separate actions; do not grant a manager blanket mailbox access automatically.
bash
gam update user departed@company.com suspended on # 1. block all access
gam user departed@company.com signout # 2. kill sessions
gam user departed@company.com transfer drive manager@company.com # 3. transfer Drive
gam user departed@company.com add delegate manager@company.com # 4. delegate email 30d
curl -X POST "https://slack.com/api/admin.users.remove" \
-H "Authorization: Bearer xoxp-your-admin-token" \
-d "user_id=U01DEPARTED&team_id=T01YOURTEAM" # 5. remove Slack
gh api orgs/your-company/members/departed-username -X DELETE # 6. remove GitHub
op user suspend departed@company.com # 7. revoke 1Password
aws iam delete-login-profile --user-name departed # 8. revoke AWS console
aws iam list-access-keys --user-name departed # then delete each key
echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) Offboarded departed@company.com" >> ~/offboarding-log.txt
Video Conferencing
bash
# macOS
lsof | grep "AppleCamera\|VDC" # check what owns the camera
pkill -f zoom.us && open -a zoom.us # restart Zoom
tccutil reset Camera # reset camera permissions
# Linux
pactl list short sources # list mics
pactl set-source-mute @DEFAULT_SOURCE@ 0 # unmute mic
powershell
Get-CimInstance Win32_SoundDevice | Select Name, Status
Quick fixes: No audio = check OS mute + correct device. No video = close other conferencing apps. Echo = use headphones. Choppy = need 3+ Mbps upload.