teaway

Run a Mac like an always-on server.

teaway is a focused macOS command-line tool for headless and long-running Mac setups. It keeps a Mac working when normal sleep would interrupt it—including a MacBook with the lid closed—then restores the exact power setting it owned. It can also schedule and precisely cancel one delayed shutdown.

Use it for a spare MacBook build box, a Mac mini home server, a homelab node, long backups or media jobs, and self-hosted services that must survive the end of an interactive session. teaway manages the power lifecycle only; SSH, Screen Sharing, networking, service supervision, and the workload itself remain under your control.

Why teaway

• Closed-lid and headless operation. Manages the macOS disablesleep state instead of merely keeping one foreground process active.
• Reversible ownership. Records the value observed before on and restores only the state that teaway owns.
• Safe repeated use. An optional per-user helper removes repeated password prompts without granting a shell or arbitrary pmset access.
• Explicit shutdowns. Resolves a duration to an absolute local deadline, requires an exact confirmation phrase, verifies the system event, and cancels only the matching teaway event.
• No background control plane. No daemon, listener, account, telemetry, remote API, workload inspection, or cloud dependency.

Quick start

brew install soundadam/tap/teaway

# One visible administrator authorization, then narrow passwordless operations.
teaway auth register

# Keep the Mac available for remote work.
teaway on
teaway status

# Optional: shut down after a bounded delay.
teaway shutdown after 2h
teaway shutdown status
teaway shutdown cancel

# Restore the exact pre-teaway sleep setting.
teaway off

Before closing a laptop lid, verify that the Mac is on AC power, stationary, well ventilated, and reachable through the remote-access method you configured. teaway deliberately does not configure Remote Login, Screen Sharing, VPNs, firewalls, DNS, or service startup.

Commands

Command	Effect
teaway / teaway status	Read power source, observed sleep state, ownership, and shutdown state
teaway on	Snapshot the current state, disable sleep, verify, and record ownership
teaway off	Restore only the exact state owned by teaway
teaway shutdown after 30m	Plan one shutdown after an explicit duration and require typed confirmation
teaway shutdown status	Reconcile the private record with macOS scheduled power events
teaway shutdown cancel	Cancel only the exact teaway-owned shutdown
teaway auth status	Inspect ordinary/registered authorization and sudo Touch ID configuration
teaway auth register	Install the narrow per-user root helper after visible authorization
teaway auth unregister	Remove the helper and its sudoers rule
teaway version	Print the installed version

Durations accept m, h, and d units. Delayed shutdowns are bounded between 10 minutes and 7 days.

Operating model

Awake state

teaway on performs a small transaction:

1. Require AC power and inspect the current macOS sleep setting.
2. Persist the exact pre-change value in private state.
3. Apply disablesleep=1 through a fixed privileged operation.
4. Re-read macOS state and report success only after verification.

teaway off reverses that transaction. With no owned record it is a no-op, even when the live value is already 1; another tool or administrator may own that setting. This prevents teaway from silently undoing external policy.

Authorization

Without registration, mutations use ordinary sudo and preserve the system credential timestamp. With teaway auth register, the current executable is copied to a root-owned per-user helper and a validated sudoers rule permits only:

• disablesleep values 0 and 1;
• one canonical teaway shutdown schedule; and
• exact cancellation of a matching canonical or recorded legacy event.

The rule does not permit arbitrary CLI commands, arbitrary pmset arguments, or a shell. Registration is an account-level trust decision and is intended for a trusted single-user macOS account. Re-run teaway auth register after an upgrade when auth status reports a helper version mismatch.

Shutdown ownership

Shutdown scheduling is independent of on and off. teaway off never silently cancels a shutdown. The system schedule is authoritative, while the private journal supplies the exact owner and tuple needed for safe recovery. macOS 26 two-digit/four-digit schedule rendering is normalized before exact comparison.

Requirements

• macOS 13 Ventura or later
• Apple silicon or Intel Mac supported by the installed macOS release
• AC power for teaway on
• Administrator authorization for power mutations or helper registration
• Swift 5.9 / Xcode 15 or later when building from source

Safety and availability limits

A MacBook has less cooling headroom with its lid closed. Keep the machine on a hard, open surface; never run it closed inside a bag, drawer, or other confined space. teaway does not override thermal protection and cannot prevent power loss, kernel failure, forced updates, hardware faults, or a network outage.

Treat a laptop or desktop Mac as a small server only after configuring the rest of the availability stack: remote access, service startup, backups, monitoring, stable networking, and—where needed—a UPS. See Running a Mac as an always-on server.

Install and upgrade

brew install soundadam/tap/teaway
brew update
brew upgrade teaway

The Homebrew Formula builds from the immutable GitHub source tag. Public releases do not ship an unnotarized prebuilt executable.

To build directly:

git clone https://github.com/soundadam/teaway.git
cd teaway
swift test
swift build -c release --product teaway
.build/release/teaway version

Homebrew installs only teaway. The shorter tea name belongs to another Homebrew package and may be used only as a personal shell alias or shim.

Documentation

• Operating a Mac as an always-on server
• Authorization model
• Security model
• Product design and boundaries
• Migration from an older personal script
• Release readiness
• Changelog
• Contributing
• Security reporting

teaway is distributed under the MIT License.