home / skills / openclaw / skills / docker-osx

docker-osx skill

unsafe

/skills/nightvibes3/docker-osx

This skill lets you run macOS in Docker on Linux to build iOS apps and run macOS-only software without a Mac.

npx playbooks add skill openclaw/skills --skill docker-osx

Review the files below or copy the command above to add this skill to your agents.

Files (3)

SKILL.md

1.5 KB

---
name: docker_osx
description: "Run macOS in Docker on Linux with KVM. Use when: user wants to build iOS apps/IPAs, needs macOS environment, wants to compile Apple apps without Mac, or wants to run macOS-only software. NOT for: servers without KVM, low-resource systems (needs 4+ CPU, 8GB RAM), or production macOS deployments. Requires Docker + KVM."
homepage: https://github.com/sickcodes/Docker-OSX
metadata:
  openclaw:
    emoji: 🍎
    requires:
      bins: [docker]
      kvm: true
---

# Docker-OSX

Run macOS in Docker - build iOS apps on Linux!

## Quick Start

```bash
start macos        # Boot VM (2-5 min)
status macos       # Check if ready
ssh macos          # Connect
stop macos         # Shutdown
```

## Commands

| Command | Description |
|---------|-------------|
| `start macos` | Boot macOS VM |
| `stop macos` | Shutdown VM |
| `status macos` | Check running |
| `ssh macos` | Get SSH command |
| `vnc macos` | Get VNC address |
| `logs macos` | View logs |

## Connection

- **SSH**: port 50922, password: `alpine`
- **VNC**: port 5900

## Building iOS

```bash
# In macOS terminal:
xcode-select --install
git clone <repo>
cd repo
xcodegen generate
xcodebuild -project App.xcodeproj -scheme App -configuration Release -destination 'generic/platform=iOS' CODE_SIGN_IDENTITY="" CODE_SIGNING_REQUIRED=NO CODE_SIGNING_ALLOWED=NO build
```

## Errors

| Error | Fix |
|-------|-----|
| KVM not available | Server needs hardware virtualization |
| Docker not installed | `curl -sSL get.docker.com | sh` |

## Resources

- 4+ CPU cores
- 8GB+ RAM
- 100GB disk

Overview

This skill runs macOS inside a Docker container on Linux using KVM so you can build and test Apple apps without physical Mac hardware. It provides simple lifecycle commands to boot, check status, connect via SSH or VNC, and stop the macOS VM. Use it to compile iOS apps, generate IPAs, or run macOS-only software in a development or CI sandbox.

How this skill works

The skill launches a KVM-backed macOS virtual machine inside Docker and exposes common access methods: SSH for command-line builds and VNC for graphical access. It controls the VM lifecycle with short commands to start, stop, inspect logs, and retrieve connection details. The environment is intended for development and testing, not for production macOS hosting.

When to use it

You need to compile iOS apps or produce IPAs but don’t have access to a Mac
You must run macOS-only tools or test behavior on macOS from Linux
You want an isolated, reproducible macOS build environment for CI or local dev
You have a Linux host with hardware virtualization (KVM) available
Your host has at least 4 CPU cores and 8 GB RAM available for the VM

Best practices

Ensure the Linux host has KVM enabled and Docker installed before use
Allocate at least 4 CPU cores, 8 GB RAM, and ~100 GB disk to the VM for reliable builds
Use SSH (default port exposed) for scripted builds and VNC only for GUI troubleshooting
Treat the VM as ephemeral: store source and artifacts outside the VM or export build outputs
Do not use this for production macOS services or on hosts without hardware virtualization

Example use cases

Build and sign iOS applications in a Linux CI pipeline (generate IPAs)
Run Xcode and macOS-only developer tools for debugging or compatibility testing
Set up a disposable macOS sandbox to evaluate macOS-specific software
Use SSH to run xcodebuild commands remotely from Linux-based automation scripts

FAQ

What are the main requirements to run this skill?

A Linux host with KVM/hardware virtualization enabled and Docker installed. Recommended: 4+ CPU cores, 8+ GB RAM, and ~100 GB disk.

How do I connect to the macOS VM?

The skill exposes SSH for command-line access and VNC for GUI. SSH is preferred for automated builds; VNC is useful for interactive GUI work.

Is this suitable for production macOS hosting?

No. This is intended for development, testing, and CI. It’s not supported for production macOS deployments or servers without KVM.