An independent operator guide for using a Mac as the control surface for an NVIDIA DGX Spark. MacSpark documents secure networking, remote development, local model serving, optional routing, file exchange, desktop access, service lifecycle, and recovery.
Documentation review date: 2026-07-11. Hardware-dependent procedures remain subject to validation on the operator's exact DGX OS and runtime versions.
Warning
This is a manual and a set of reviewed examples, not an installer. Commands in this repository can change authentication, networking, packages, containers, file sharing, and remote access. Read each phase, keep a console recovery path, and adapt placeholders before running anything.
flowchart LR
mac[Mac] -->|Tailscale or verified SSH| dgx[DGX Spark]
mac -->|OpenAI-compatible client| gateway[Optional gateway]
gateway --> runtime[vLLM or another runtime]
mac -->|SMB, VNC, remote editor| services[Optional services]
dgx --- runtime
dgx --- gateway
dgx --- services
| Capability | Recommended boundary | Start here |
|---|---|---|
| Architecture and capability selection | One optional layer at a time | Architecture |
| SSH and private reachability | Verified host key plus Tailscale policy | Networking and SSH |
| NVIDIA container baseline | Read-only checks before changes | Preflight |
| OpenAI-compatible local inference | Pinned, reviewed vLLM container | Model serving |
| Local and cloud model routing | Authenticated LiteLLM gateway | Gateway |
| Finder, Zed, and remote desktop | Explicit opt-in per service | Mac integration |
| Persistence, updates, and rollback | One service at a time | Operations |
| Evidence-first fault isolation | Client-to-service layers | Troubleshooting |
The engineering patterns chapter extracts the most reusable ideas from the original operational scripts: staged SSH hardening, safe bind resolution, plan-before-mutation launches, transactional service replacement, managed configuration includes, PID identity checks, token separation, and deliberate service handoff.
- Complete NVIDIA's official first-boot guide and retain local console access.
- Run the read-only preflight on the Mac and DGX.
- Establish the private network and SSH path.
- Bring up exactly one model runtime and test it locally on the DGX.
- Test the same endpoint from the Mac, then add optional services individually.
- Record observed versions and rollback steps before enabling persistence.
MacSpark deliberately avoids a universal copy-and-paste installation command.
DGX OS, container images, model support, and client schemas change. Commands
that are version-sensitive link to the current official source and use obvious
placeholders such as <dgx-host> and <reviewed-image>.
Repository-local skills live under .agents/skills:
plan-macsparkassesses a requested setup and produces a phased plan with changes, validation, and rollback.diagnose-macsparkinvestigates connectivity and service failures using read-only evidence before suggesting a minimal fix.
Agents working in this repository must also follow AGENTS.md. The skills do not grant permission to run privileged or destructive commands.
The examples directory contains small templates for SSH,
Tailscale grants, Zed port forwarding, LiteLLM, and a systemd user service. They
are reference material, not maintained deployment artifacts. Review the linked
upstream documentation and replace every placeholder.
The guide targets a current macOS controller and an ARM64 NVIDIA DGX Spark running DGX OS. It assumes the operator owns or administers both machines. The procedures are intentionally conservative and still require hardware verification on the operator's exact OS, driver, runtime, model, and network.
Not in scope:
- public-internet exposure;
- unattended OS provisioning or upgrades;
- a hosted control plane or telemetry;
- redistributing models or third-party container images;
- claiming that every model or client is compatible with every release.
- NVIDIA DGX Spark User Guide
- NVIDIA DGX Spark developer recipes
- Tailscale access control
- vLLM OpenAI-compatible server
- Docker security warning for the
dockergroup - Hugging Face CLI
Corrections with exact versions and observed output are especially useful. See CONTRIBUTING.md and SECURITY.md.
MacSpark is available under the MIT License. See NOTICE.md for attribution and trademark notices.