Skip to main content
🎤 Luca Berton is speaking at Red Hat Summit & KubeCon EU 2026!Learn more →
intermediate

Lessons Learned Building an AI Studio on a Mac

Work through short, practical fixes for the problems that come up when running a self-hosted AI studio on macOS.

41 lessons51mUpdated November 2026

What you'll learn

  • Fix common shell and dependency-management problems on macOS
  • Troubleshoot Docker, Colima, and Kubernetes
  • Operate local models and agents and keep their services observable

Who this is for

  • • DevOps engineers deepening their expertise
  • • SREs building production-grade systems
  • • Backend developers expanding into infrastructure

Prerequisites

  • • A Mac and familiarity with the terminal.

Course content

8 modules, 41 lessons, 51m of video

Module 1

8 lessons, 10 min
1

2 min

The default shell on Mac is outdated and lacks modern syntax.

2
BSD sed ignores \b word boundaries

2 min

macOS sed silently fails on word boundaries

3
Stop Race Conditions in Shell Locks

2 min

The cleanup runs even when the lock was never acquired.

4
Never edit a running bash script

2 min

Bash reads scripts line by line, not all at once.

5
pgrep -f matches its own shell

2 min

The check finds itself running.

6
A background server dies when its terminal closes

2 min

The process dies when the terminal closes.

7
Stop using netstat on macOS 27

2 min

The command returns nothing, but the port is open.

8
Fix macOS HTTP Server DNS Delay

1 min

Reverse DNS lookup blocks the bind call.

Module 2

3 lessons, 4 min
9
Stop Homebrew from Deleting Your AI Stack

2 min

Homebrew 7 auto-removes dependencies by default.

10
Stop Silent Brew Upgrades in CI

2 min

CI jobs fail because dependencies changed versions.

11
Helm 4 vs 3: Pin Your Major Version

2 min

A silent version mismatch breaks your agent.

Module 3

7 lessons, 10 min
12
Stop using --filter name= in Docker

2 min

Substring matching causes cross-project contamination.

13
Docker filters AND, not OR

2 min

Docker treats duplicate keys as logical AND.

14
Bind to 127.0.0.1, not 0.0.0.0

2 min

Binding to all interfaces exposes your homelab.

15
Healthcheck probes root, not API

2 min

A proxy returns 307 on root, masking a 502 on the actual service.

16
Stop Killing the Default Colima VM

2 min

One missing flag broke the environment for everyone else.

17
Stop Colima from hijacking your Docker context

2 min

A background service overrides your active environment.

18
Stop Deleting Shared Folders in VMs

2 min

Deleting and recreating a virtiofs mount point breaks the link.

Module 4

4 lessons, 5 min
19
Busybox Sleep Ignores SIGTERM

2 min

The container ignores the stop signal.

20
Stop using kubectl run --rm -i for quick checks

2 min

Fast commands in ephemeral pods cause confusing terminal artifacts.

21
Stop piping kubectl run to tail

2 min

Piping kubectl run to tail hides the actual result and exit code.

22
Port-forward dies when terminal closes

1 min

The terminal closes, killing the background process.

Module 5

8 lessons, 9 min
23
Ollama JSON 501 on MLX Runner

1 min

Your agent crashes when requesting JSON from a local model.

24
Ollama Prefill Bottleneck

2 min

Large system prompts stall the first token.

25
Set num_ctx to 64K for Hermes

2 min

Ollama defaults to the model's max KV cache, not your needs.

26
Ollama 403 on Tailscale: Use SSH Tunnel

2 min

DNS rebinding protection blocks non-local Host headers.

27
Ollama context limit breaks agent tool calls

2 min

The model truncates the prompt before it can call a tool.

28
Stop Unloading Shared Ollama Models

2 min

Automated cleanup steps interfere with active local AI sessions.

29
Stop Open WebUI from forcing tool calls

1 min

Built-in tools hijack small models like Gemma.

30
MLX GPU Stream Thread Error Fix

2 min

MLX 0.32 binds GPU streams to the main thread.

Module 6

6 lessons, 7 min
31
Stop Claude Code from compacting on 32K

2 min

The agent thinks it is out of space when it is not.

32
Stop trusting local AI cost fields

2 min

Claude Code reports costs for Anthropic models only.

33
Stop Hermes from hiding your MCP tools

2 min

Hermes tool search defaults to on, breaking local agents.

34
Stop five agents hitting the 5-hour limit

1 min

The 5-hour usage limit kills all active agents simultaneously.

35
Stop old gateway before starting new one

2 min

Auto-start logic creates duplicate connections

36
MCP stdio ignores shell env vars

2 min

The MCP Inspector does not inherit your shell environment.

Module 7

3 lessons, 3 min
37
OTel Unit 1 Adds _Ratio Suffix

2 min

OpenTelemetry appends _ratio when unit is set to 1.

38
Set metric_expiration to 3x scrape interval

2 min

Stale metrics linger because expiration is too long.

39
Stop Hardcoding Job Names in Metrics

1 min

Static names miss dynamic processes.

Module 8

2 lessons, 2 min
40
Stop piping curl to bash

2 min

One command executes remote scripts without your eyes on them.

41
Never print secrets in video

2 min

One command leaks credentials forever.

Get started

Start Free Lesson

First lesson is always free — no signup required

This course includes

41 hands-on lessons
Intermediate level
51m total
Final assessment

Want all courses?

See Pro plan →

Your instructor

Luca Berton

Founder and CEO, Open Empower. About the author

More in AI Homelab on a Mac mini

All courses in this track

Turn a Mac mini into a reproducible homelab server

You will turn an Apple Silicon Mac mini into an always-on home server. You start by planning hardware choices and initializing a Git repository to track your setup steps. This foundation ensures your configuration is documented and ready for automation. You then configure remote access using SSH and Tailscale for secure connectivity. You also adjust power settings to keep the machine running continuously without interruption. Next, you use Homebrew with a Brewfile to manage software packages consistently. You create a Makefile that journals every command and output for full reproducibility. Finally, you add a read-only health check to verify system status. You learn to rebuild the entire setup on a clean machine from your repository.

Beginner · 4 lessons · 15 min · Updated Nov 2026

Preview free lesson

Virtual machines on Apple Silicon

You will build a Linux virtual machine on your Apple Silicon Mac using Colima and the Virtualization framework. You will point Docker to this VM and manage it with simple commands. You will share files between your Mac and the VM using virtiofs mounts. You will run AMD64 container images efficiently using Rosetta translation instead of slow emulation. You will size your VM correctly for your specific Mac hardware to avoid resource issues. You will create a plain Ubuntu VM with Lima for lab environments. You will configure launchd to start your VM automatically when you log in. You will learn to stop and clean up these virtual machines when you are done.

Beginner · 6 lessons · 20 min · Updated Nov 2026

Preview free lesson

Kubernetes on your Mac

You will build a multi-node Kubernetes cluster on your Apple Silicon Mac using kind. You start by creating a single-node cluster and then expand it to three nodes using a configuration file. You install applications with Helm and reach them from your Mac using ingress or Gateway. You also manage persistent storage and resource limits for your pods. You finish by tearing down and rebuilding the entire environment in minutes. You use a Makefile to automate the setup and cleanup process. This ensures your cluster is reproducible and easy to manage. You gain hands-on experience with a real cluster that runs entirely on your laptop.

Beginner · 6 lessons · 23 min · Updated Nov 2026

Preview free lesson