macOS 15.7.5

AI Agent Development, Evaluation & Deployment Environment
Version: 1
Base System: macOS Sequoia 15.7.5
Architecture: x86_64
Last Updated: May 2026
Developer: Kartik (NullVoider)

⚖️ Legal Notice

IMPORTANT - PLEASE READ CAREFULLY

This container includes macOS, which is proprietary software owned by Apple Inc. By using this container, you acknowledge and agree to the following:

Apple EULA Compliance: You must comply with Apple's Software License Agreement for macOS. The developer of this container does not grant, and cannot grant, any rights to macOS itself.
Licensing Separation:
- The container infrastructure (Docker configuration, scripts, documentation) is licensed under GPL-3.0
- macOS and Apple software remain under Apple's EULA
- You must comply with BOTH licenses
Commercial Use: Commercial deployment of macOS may require additional licensing from Apple. You are responsible for ensuring compliance with Apple's terms.
No Warranty: This container is provided "as is" without any warranty. The developer is not affiliated with or endorsed by Apple Inc.
User Responsibility: You are solely responsible for ensuring your use of this container complies with all applicable licenses, laws, and regulations.

By proceeding to use this container, you acknowledge that you have read, understood, and agree to comply with both the GPL-3.0 license (for container components) and Apple's EULA (for macOS).

Overview
Key Features
Container Capabilities
Technical Specifications
Installation & Deployment
Customizing the Image
Installed Software
Development Environments
The-Eye Integration
Task Executor REST API
Remote Access Methods

NoMachine (Recommended)
VNC (Temporary Monitoring)
SSH Access

Troubleshooting
CI/CD Integration
Reporting Issues
FAQ
License
About This Project

Overview

The macOS 15.7.5 Container is a complete macOS Sequoia environment designed for AI agent development, evaluation, testing, and deployment — including Computer Use Agents (CUA) and coding agents. It provides a full macOS desktop experience with pre-configured development tools, integrated monitoring capabilities, and a REST API task executor — all within a single Docker container.

IMPORTANT LEGAL NOTICE: This container includes macOS software. By using this container, you agree to comply with Apple's Software License Agreement (EULA) for macOS. The GPL-3.0 license applies to the container configuration, scripts, and custom components created by the developer, but does not and cannot apply to macOS itself or Apple's proprietary software. Users are responsible for ensuring their use complies with Apple's EULA.

Purpose

This container is designed for:

Computer Use Agent Development: Pre-configured environment for building and testing CUA applications
Coding Agent Evaluation: Full OS environment for running coding agent benchmarks including SWE-bench Lite
AI Agent Development: Pre-configured environment for building, testing, and deploying any AI agent
Task Execution via REST API: Structured task submission, execution, and result retrieval over HTTP (port 9090)
macOS Development: Native macOS environment for developing Mac-specific applications
Automated Testing: Consistent, reproducible macOS environment for CI/CD pipelines
Remote Development: Full-featured macOS desktop accessible via NoMachine and VNC
Multi-Language Development: Support for 10+ programming languages out of the box
Visual Monitoring: Integrated Eye tool for screen capture and agent training data collection

What Makes This Unique

Single Container Design: Complete macOS 15.7.5 system with no external file dependencies
Ephemeral State: Everything is isolated inside the container, providing clean state management
4TB Virtual Disk: Massive storage capacity for development projects
RAM: Customizable memory allocation (minimum 4 GB for smooth operation)
Optimized Performance: Significantly smoother than Dockur and Docker-OSX alternatives
Fully Customizable: Configuration can be modified to improve performance based on hardware
Zero External Files: Unlike Dockur and Docker-OSX, everything is self-contained
Developer-Ready: Pre-installed IDEs, tools, and language runtimes

Note: The virtual storage does not mandate requirement of exactly 4TB of storage in the device running the container. The virtual disk is a growable disk, and 4TB is the cap on the virtual disk.

Key Features

Operating System

✅ macOS Sequoia 15.7.5 - Latest macOS release
✅ Virtual Disk - Massive 4TB virtual storage
✅ RAM - Customizable memory allocation (minimum 4 GB for smooth operation)
✅ Intel i3 CPU Configuration - Optimized for stability and compatibility
✅ Ephemeral State - Clean isolation with no external dependencies

Development Tools

✅ 10+ Languages - Python, Go, Rust, Java, C#, C++, Node.js, TypeScript, Kotlin, Scala
✅ VS Code - Pre-installed with essential extensions
✅ Xcode Tools - Command line tools for macOS development
✅ Homebrew - Package manager for macOS
✅ Git & Git LFS - Version control with large file support
✅ Terminal Tools - Modern shell utilities and productivity tools

Applications

✅ Brave Browser - Privacy-focused web browser
✅ VS Code - Feature-rich code editor
✅ Terminal Apps - zsh, tmux, and modern CLI tools

Remote Access

✅ NoMachine - High-performance remote desktop (4000/TCP) - Recommended
✅ VNC - Standard VNC access (5900/TCP) - For temporary monitoring only
✅ SSH - Secure shell access (2222/TCP)
✅ Eye Server - Screen capture endpoint (4444/TCP)
✅ Task Executor REST API - Structured task execution for coding agents (9090/TCP)

Performance & Stability

✅ Fast Boot Time - Container ready in ~30 seconds
✅ Low CPU Usage - 20-30% under normal workload
✅ Smooth Performance - Optimized for regular development tasks
✅ Single Container - No external files or dependencies
✅ KVM Acceleration - Hardware virtualization for optimal performance

Container Capabilities

Operating System

macOS Sequoia 15.7.5

Complete macOS desktop experience
Native macOS applications support
Standard macOS file system and permissions
macOS security features
Native macOS APIs and frameworks

Storage Configuration:

Virtual Disk: 4TB capacity
Format: APFS (Apple File System)
RAM: Fully customizable (minimum 4 GB for smooth operation)
CPU: Intel i3 configuration (optimized for compatibility)

Pre-installed Applications:

Browser: Brave
Editor: Visual Studio Code
Terminal: Built-in Terminal app with modern shell tools
File Manager: Finder
System Utilities: Standard macOS utilities

Development Tools

Programming Languages & Runtimes

Language	Version	Package Manager	Notes
Python	3.14.4	pip 26.1	Default `python` command
Go	1.26.2	go modules	Full Go development environment
Rust	stable	cargo	System-wide installation
Node.js	25.9.0	npm 11.12.1	TypeScript & tsx included
Java	25 (latest)	-	Oracle JDK
C#/.NET	10.0 SDK	dotnet	LTS version
C/C++	clang/gcc	-	Xcode command line tools
Kotlin	2.3.0	-	Compiler installed
Scala	3.8.3	coursier	Latest stable
PowerShell	latest	-	Cross-platform shell

IDEs & Editors

Visual Studio Code (latest)

Pre-installed extensions:

C++ Tools Extension Pack
Docker Extension
Java Extension Pack
Oracle Java Extension
.NET Runtime & C# DevKit
GitLab Workflow & GitLens
Go Extension
Python Extension Pack (Pylance, debugpy, environment manager)
Rust Analyzer
Scala Language Server

Build Tools & Utilities

Homebrew - macOS package manager
Git (latest) - Version control with LFS support
Xcode Command Line Tools - Essential development tools
CMake - Cross-platform build system
GDB / LLDB - Debuggers

Remote Access

NoMachine (Port 4000) - Recommended

Why NoMachine?

Best Performance: Optimized for macOS with hardware acceleration
Low Latency: Minimal input lag for smooth development experience
High Quality: Superior video quality with efficient compression
Full Features: Clipboard sharing, file transfer, audio support

Configuration:

Port: 4000 (TCP)
Default remote access method
Pre-configured for optimal performance
Clipboard sharing enabled
Audio support enabled

Use Cases:

Primary development interface
Extended coding sessions
Full desktop interaction
Multi-window workflows

VNC (Port 5900) - For Temporary Monitoring Only

Configuration:

Port: 5900 (TCP)
Standard VNC protocol
Compatible with any VNC client

Important Notes:

VNC performance is significantly lower than NoMachine
Recommended only for temporary monitoring or quick checks
Not suitable for extended development sessions
Use NoMachine for regular work

Use Cases:

Quick status checks
Emergency access when NoMachine is unavailable
Automated monitoring scripts
Screenshot capture

SSH (Port 2222)

Configuration:

Port: 2222 (TCP)
Secure shell access
Terminal-based access to macOS

Use Cases:

Command-line operations
File transfers via SCP/SFTP
Remote script execution
System administration

Technical Specifications

System Requirements

Minimum Requirements

Component	Requirement	Notes
RAM	6 GB	Absolute minimum for container operation
Disk Space	100 GB free	For container image and virtual disk
CPU	4 cores	x86_64 architecture with KVM support
Virtualization	KVM enabled	Hardware virtualization must be enabled in BIOS
Host OS	Linux	Ubuntu 20.04+, Debian 11+, or similar
Docker	24.0+	Recent Docker version required
Kernel	6+	For proper KVM support

Recommended Requirements

Component	Recommendation	Benefit
RAM	8 GB	Better performance and headroom
Disk Space	150 GB free	Ample space for projects and data
CPU	4+ cores	Improved responsiveness
Storage Type	SSD/NVMe	Faster disk I/O operations
Network	100 Mbps+	Better remote access experience

Container Resource Usage

Runtime Allocations:

Virtual RAM: Fully customizable (minimum 4 GB for smooth operation)
Virtual Disk: 4 TB (APFS filesystem)
Virtual CPU: Intel i3 configuration
Network: Bridged networking with port forwarding

Host Resource Impact:

CPU Usage: 20-30% under normal workload
Memory Overhead: ~2-3 GB for container management
Disk I/O: Moderate (depends on workload)
Network: Minimal overhead

Performance Metrics

Boot Performance:

macOS Boot: ~30 seconds
Container Start: Immediate
Desktop Ready: Immediate after boot completion

Runtime Performance:

Idle CPU: 5-10%
Normal Workload CPU: 20-30%
Memory Usage: Stable at allocated 8GB
Disk Performance: Depends on host storage type

Comparison to Alternatives:

vs. Dockur: Significantly smoother performance
vs. Docker-OSX: Better responsiveness and stability
External Files: None required (vs. multiple external files in alternatives)
Customization: Fully customizable configuration
State Management: Clean ephemeral state

Optimization Notes:

Current configuration (Intel i3) is optimized for compatibility and stability
Configuration is based on tested and confirmed safe settings
Performance can be improved by adjusting CPU configuration to match host hardware
Animations may cause slight performance impact with current CPU configuration
Heavy animation applications may slow down during transitions
Regular development workflows run smoothly without issues

Installation & Deployment

Prerequisites

1. Install Docker

For Ubuntu/Debian:

# Update package index
sudo apt-get update

# Install dependencies
sudo apt-get install -y \
    ca-certificates \
    curl \
    gnupg \
    lsb-release

# Add Docker's official GPG key
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# Set up the repository
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker Engine
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Verify installation
docker --version
docker compose version

For Other Linux Distributions:

# Fedora/RHEL/CentOS
sudo dnf install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Arch Linux
sudo pacman -S docker docker-compose

Post-Installation Steps:

# Add your user to docker group (to run docker without sudo)
sudo usermod -aG docker $USER

# Enable Docker service
sudo systemctl enable docker
sudo systemctl start docker

# Log out and log back in for group changes to take effect

2. Enable KVM

Check KVM Support:

# Check if KVM is supported
lscpu | grep Virtualization

# Check if KVM modules are loaded
lsmod | grep kvm

# Expected output:
# kvm_intel (for Intel CPUs) or kvm_amd (for AMD CPUs)
# kvm

Enable KVM:

# Install KVM packages (Ubuntu/Debian)
sudo apt-get install -y qemu-kvm libvirt-daemon-system libvirt-clients bridge-utils

# For Fedora/RHEL/CentOS
sudo dnf install -y qemu-kvm libvirt virt-install bridge-utils

# Verify KVM is working
sudo kvm-ok

# Expected output:
# INFO: /dev/kvm exists
# KVM acceleration can be used

Set KVM Permissions:

# Add user to kvm group
sudo usermod -aG kvm $USER

# Verify /dev/kvm permissions
ls -l /dev/kvm

# Should show: crw-rw---- 1 root kvm

# Log out and log back in for group changes to take effect

Verify KVM Access:

# After logging back in, verify you can access KVM
groups | grep kvm

# Test KVM device access
test -r /dev/kvm && test -w /dev/kvm && echo "KVM is accessible" || echo "KVM access denied"

If KVM is Not Enabled in BIOS:

Restart your computer
Enter BIOS/UEFI settings (usually F2, F10, F12, or Del key during boot)
Look for virtualization settings:
- Intel: "Intel VT-x" or "Intel Virtualization Technology"
- AMD: "AMD-V" or "SVM Mode"
Enable the setting
Save and exit BIOS
Boot into Linux and verify with kvm-ok

Docker Compose Deployment

Recommended Deployment Method: The ONLY recommended way to run this container is using Docker Compose. This ensures proper configuration and port mappings.

1. Create Docker Compose File

Create a file named deploy-macos.yaml:

services:
  mac-agent:
    image: nullvoider/mac15-base:v1
    container_name: mac_agent
    restart: unless-stopped
    tty: true
    stdin_open: true
    ports:
      - 4000:4000      # NoMachine (recommended remote access)
      - 4444:4445      # Eye server
      - 2222:2222      # SSH
      - 5900:5900      # VNC (temporary monitoring only)
      - 9090:9090      # Task Executor REST API
    environment:
      - API_TOKEN=your-secret-token
      - TASK_MAX_AGE=3600
    devices:
      - /dev/kvm:/dev/kvm
    cap_add:
      - NET_ADMIN
    extra_hosts:
      - "host.docker.internal:host-gateway"

2. Deploy the Container

# Start the container
docker compose -f deploy-macos.yaml up -d

# View logs
docker compose -f deploy-macos.yaml logs -f

# Check container status
docker compose -f deploy-macos.yaml ps

3. Container Management

# Stop the container
docker compose -f deploy-macos.yaml stop

# Start the container
docker compose -f deploy-macos.yaml start

# Restart the container
docker compose -f deploy-macos.yaml restart

# Remove the container
docker compose -f deploy-macos.yaml down

# Remove container and volumes
docker compose -f deploy-macos.yaml down -v

Testing the Container

1. Verify Container is Running

# Check container status
docker ps | grep mac_agent

# Expected output:
# CONTAINER ID   IMAGE                        STATUS          PORTS
# abc123def456   nullvoider/mac15-base:v1   Up 2 minutes    0.0.0.0:4000->4000/tcp, ...

2. Check Boot Progress

# Monitor container logs
docker logs -f mac_agent

# Look for successful boot messages indicating:
# - macOS boot sequence completed
# - Services started
# - NoMachine server ready
# - VNC server ready

3. Test Remote Access

NoMachine (Recommended):

# Connect using NoMachine client to:
# Host: your-server-ip
# Port: 4000

VNC (Temporary):

# Connect using any VNC client to:
# Host: your-server-ip
# Port: 5900

SSH:

# Test SSH connection
ssh -p 2222 user@your-server-ip

4. Verify Services

Once connected via NoMachine or VNC:

Open Terminal
Check system information: sw_vers
Verify development tools: python --version, node --version, etc.
Open VS Code to verify it's installed

5. Health Check

# Check container resource usage
docker stats mac_agent

# Expected metrics:
# CPU: 20-30% (normal workload)
# MEM: ~4GB allocated
# NET I/O: Varies based on remote access usage

Customizing the Image

This section walks through the full process of modifying the macOS environment and rebuilding a custom Docker image — useful for adding languages, tools, updated scripts, or any workflow-specific configurations and customizations.

Prerequisites

Repository cloned
Docker and QEMU utilities installed (qemu-img must be on PATH)
At least 100 GB free disk space for the conversion steps

Step 1 — Modify the YAML Configuration (Optional)

If you need to adjust the RAM or CPU core allocation before booting into macOS, edit the YAML file inside the scripts/ directory of the cloned repo:

# Example: open and edit the YAML before moving it
nano scripts/mac15.yaml

Then move it to a separate working directory of your choice — this directory will be your build workspace for all subsequent steps:

mv scripts/mac15.yaml /your/working/directory/

⚠️ WARNING: Only change RAM and CPU core values in the YAML. Do not change the disk size — altering the disk size will corrupt data.img and make it unusable. If that happens, you will need to re-run Step 2 from the original QCOW2 file to start over.

Step 2 — Convert the QCOW2 to a Raw Image

From the root of the cloned repository, convert the QCOW2 disk image to a raw format that QEMU can use as a mutable disk:

qemu-img convert -p -f qcow2 -O raw mac15-image/mac15.qcow2 data.img

This may take several minutes depending on your disk speed. The -p flag shows progress.

Step 3 — Create the macOS Directory Structure

Navigate to the working directory where you moved the YAML file and create the expected directory layout:

cd /your/working/directory
mkdir macos
mkdir macos/15

Step 4 — Place the Disk Images

Copy or move base.dmg and the data.img produced in Step 2 into the directory you just created:

# Copy (safe — preserves originals)
cp /path/to/base.dmg macos/15/base.dmg
cp /path/to/data.img macos/15/data.img

# Or move (saves disk space if originals are no longer needed)
mv /path/to/data.img macos/15/data.img

Step 5 — Boot and Customize

Start the container from your working directory:

docker compose -f mac15.yaml up -d

Connect via NoMachine or VNC and perform your customizations inside the running macOS environment — updating the Task Executor script, installing apps, adding programming languages, configuring tools, or anything else your workflow requires.

Step 6 — Clean Up Before Capture

Before shutting down, ensure the macOS environment is clean so no personal or session data ends up in your image:

Browser: Close all tabs and clear all browsing history, cookies, and cached data in every browser installed
Terminal: Wipe shell history — in the terminal run history -c && > ~/.zsh_history && > ~/.bash_history
Recent items: Clear recent files, recent apps, and recent servers from the Apple menu → Recent Items → Clear Menu
Trash: Empty the Trash

Step 7 — Shut Down and Stop the Container

Shut down macOS cleanly from within the OS (Apple menu → Shut Down) and wait for the guest to fully power off. Then, from the host terminal in your working directory:

docker compose -f mac15.yaml down

Step 8 — Convert Back to QCOW2

From the macos/15/ directory, convert the modified raw image back to a compressed QCOW2:

cd macos/15
qemu-img convert -p -O qcow2 -c data.img mac15.qcow2

The -c flag enables compression to keep the image size manageable. This step may take several minutes.

Step 9 — Move the QCOW2 to the Build Directory

Move the new QCOW2 back into the mac15-image/ directory of the cloned repository. If a QCOW2 already exists there, remove it first:

# Remove existing if present
rm /path/to/cloned-repo/mac15-image/mac15.qcow2

# Move new QCOW2 into place
mv macos/15/mac15.qcow2 /path/to/cloned-repo/mac15-image/mac15.qcow2

Step 10 — Build Your Custom Image

From the root of the cloned repository, build the Docker image with your chosen tag:

docker build -f mac15-base.dockerfile -t <username>/<image-name>:<version-number> .

Example:

docker build -f mac15-base.dockerfile -t myorg/mac15-custom:v1 .

Once the build completes, clear the Docker builder cache to avoid storage bloat:

docker builder prune --all

Your custom image is ready to use in your workflow.

Installed Software

Pre-installed Applications

Productivity & Development

Brave Browser - Privacy-focused web browser (default)
Visual Studio Code - Feature-rich code editor with extensions
Terminal - Built-in macOS terminal with modern shell tools

System Utilities

Finder - macOS file manager
System Preferences - macOS settings
Activity Monitor - System resource monitoring
Console - System log viewer

Command Line Tools

Package Managers

Homebrew - macOS package manager
pip - Python package manager
npm - Node.js package manager
cargo - Rust package manager
go modules - Go dependency management

Development Utilities

git - Version control (with Git LFS)
zsh - Z shell (default shell)
tmux - Terminal multiplexer
vim / nano - Text editors

Build Tools

Xcode Command Line Tools - Essential development tools
gcc / clang - C/C++ compilers
make - Build automation
cmake - Cross-platform build system

Development Environments

Python Development

# Python 3.14.4 pre-installed
python --version

# Install packages
pip install numpy pandas tensorflow

# Virtual environments
python -m venv myenv
source myenv/bin/activate

Node.js Development

# Node.js 25.9.0 pre-installed
node --version
npm --version

# Install packages
npm install -g typescript tsx

# Project setup
npm init -y
npm install express

Go Development

# Go 1.26.2 pre-installed
go version

# Initialize module
go mod init myproject

# Install dependencies
go get github.com/gin-gonic/gin

Rust Development

# Rust stable pre-installed
rustc --version
cargo --version

# Create new project
cargo new myproject
cd myproject
cargo build

Java Development

# Java 25 pre-installed
java --version
javac --version

# Compile and run
javac HelloWorld.java
java HelloWorld

C#/.NET Development

# .NET 10.0 SDK pre-installed
dotnet --version

# Create new project
dotnet new console -n MyApp
cd MyApp
dotnet run

iOS/macOS Development

# Xcode command line tools available
xcode-select --version

# Build tools
xcodebuild -version

The-Eye Integration

The Eye is an AI-native vision capture tool integrated into the macOS container, providing automated screen capture capabilities for Computer Use Agent training, monitoring, and debugging.

Overview

The Eye captures screen content at configurable intervals for:

Agent Training: Collect visual data for training CUAs, train coding agents with full environment rather than a partial one and also evaluate agents in a full OS environments
Debugging: Record agent interactions for troubleshooting
Monitoring: Track agent behavior during execution
Dataset Creation: Build machine learning datasets from screen captures

Configuration

Eye Server Port: 8080 (HTTP)
Architecture: Client-server model with RESTful API
Storage: In-memory circular buffer (configurable capacity)

Important Note: The Eye server configuration is specific to the macOS container. Server port and settings differ from the Ubuntu build, though core functionality remains the same.

Connection & Endpoints

Eye Server Base URL:

http://your-server-ip:8080

Available Endpoints:

GET /health - Server health status and metrics
GET /snapshot.png - Retrieve latest captured frame
POST /upload - Upload captured frames (for external agents)
POST /admin/config - Update capture configuration
GET /debug - Server runtime statistics

Python SDK

The Eye includes a Python SDK for programmatic access:

Installation (if not using container's built-in Eye):

pip install eye-capture

Basic Usage:

from eye.core import EyeClient

# Connect to Eye server
client = EyeClient("http://localhost:8080", token="your-token")

# Health check
health = client.health_check()

# Get latest screenshot
image_data = client.get_snapshot()
with open("screenshot.png", "wb") as f:
    f.write(image_data)

# Get frame metadata
metadata = client.get_snapshot_metadata()
print(f"Frame ID: {metadata['frame_id']}")

# Get debug info
debug = client.get_debug_info()
print(f"Uptime: {debug['uptime_sec']}s")

Advanced Features:

from eye.core import EyeClient, SessionManager
from eye.integrations import DatasetExporter

# Initialize components
client = EyeClient("http://localhost:8080", token="TOKEN")
exporter = DatasetExporter()

# Capture session
for i in range(100):
    frame = client.get_snapshot()
    metadata = client.get_snapshot_metadata()
    exporter.add_frame(frame, i, metadata)
    time.sleep(1.5)

# Export dataset
exporter.export_json("training_data.json")
exporter.export_csv("training_data.csv")

Key Features

Capture Capabilities:

Multiple image formats (PNG, JPEG, WebP, BMP, TIFF)
Configurable quality (1-100)
Adjustable capture interval (0.1s minimum)
Automatic retries with exponential backoff

API Features:

RESTful HTTP endpoints
Token authentication
Dynamic configuration updates
Health monitoring
Debug statistics

Integration Options:

Python SDK for programmatic access
REST API for any language
Dataset export (JSON, JSONL, CSV)
Webhook support for event notifications
Cloud storage integration patterns

Quick Usage Examples

REST API (curl):

# Get latest screenshot
curl http://localhost:8080/snapshot.png > screenshot.png

# Check health
curl http://localhost:8080/health

# Update configuration
curl -X POST http://localhost:8080/admin/config \
  -H "Authorization: Bearer your-token" \
  -d '{"interval": 2.0, "format": "jpeg", "quality": 85}'

Python SDK:

from eye.core import EyeClient

client = EyeClient("http://localhost:8080")

# Continuous monitoring
while True:
    snapshot = client.get_snapshot()
    # Process snapshot for agent training
    process_for_training(snapshot)
    time.sleep(1.5)

Performance Impact

CPU Overhead: <3% during capture
Memory Usage: 50-150 MB (in-memory buffer)
Network Bandwidth: 0.5-2 MB/s @ 1.5s interval
Capture Latency: 10-50ms (platform dependent)
Display Performance: No noticeable impact on macOS GUI

Configuration Options

The Eye service runs automatically when the container starts. Configure via API:

import requests

# Update capture settings
response = requests.post(
    "http://localhost:8080/admin/config",
    headers={"Authorization": "Bearer your-token"},
    json={
        "interval": 2.0,      # Capture every 2 seconds
        "format": "jpeg",     # Use JPEG format
        "quality": 85         # 85% quality
    }
)

For more details, see The Eye documentation: https://github.com/nullvoider07/the-eyes

Task Executor REST API

The Task Executor is a Flask/waitress HTTP service running directly inside the macOS QEMU guest, exposed on port 9090 via QEMU port-forwarding. It provides structured task submission and result retrieval for coding agents and evaluation harnesses, including SWE-bench Lite compatibility.

Architecture

[external client]
    │  HTTP  port 9090
    ▼
[QEMU port-forward  hostfwd tcp::9090-:9090]
    ▼
[Flask service — running natively inside macOS guest]
    │  subprocess / native macOS calls
    ▼
[git, python3, pytest — all native on macOS]

Important: docker exec cannot reach the macOS QEMU guest. All task execution must go through this REST API or SSH (port 2222). Never use docker exec mac_agent <cmd> to run commands inside macOS.

Service Setup (one-time, via SSH)

# 1. Copy files into the guest
scp -P 2222 task_executor.py AgentUser@localhost:/Users/AgentUser/tasks/
scp -P 2222 com.cua.taskexecutor.plist AgentUser@localhost:/Users/AgentUser/tasks/
 
# 2. SSH in and complete setup
ssh -p 2222 AgentUser@localhost
 
# 3. Install dependencies
pip3 install flask waitress
 
# 4. Register as a launchd system service (auto-starts on boot)
sudo cp /Users/AgentUser/tasks/com.cua.taskexecutor.plist /Library/LaunchDaemons/
sudo chown root:wheel /Library/LaunchDaemons/com.cua.taskexecutor.plist
sudo chmod 644 /Library/LaunchDaemons/com.cua.taskexecutor.plist
 
# 5. Start immediately without rebooting
sudo launchctl load /Library/LaunchDaemons/com.cua.taskexecutor.plist

Service logs are written to /Users/AgentUser/tasks/task_executor.log.

Endpoints

POST /task/submit

Submit a task for execution. Returns immediately with a task ID.

Request body:

{
  "repo_url":        "https://github.com/org/repo",
  "base_commit":     "abc1234",
  "patch":           "--- a/file.py\n+++ b/file.py\n...",
  "test_command":    "python3 -m pytest tests/ -x --tb=short",
  "timeout":         300,
  "lint_command":    "ruff check . --output-format json",
  "capture_diff":    true,
  "reference_patch": "--- a/file.py\n+++ b/file.py\n..."
}

Field	Required	Default	Description
`repo_url`	✅	—	Git-clonable URL
`base_commit`	❌	`HEAD`	Commit, tag, or branch to check out
`patch`	❌	—	Unified diff applied after checkout
`test_command`	✅	—	Command run in the repo root
`timeout`	❌	`300`	Seconds before the process is killed
`lint_command`	❌	—	CLI lint command run after tests; result is a soft score only
`capture_diff`	❌	`false`	Capture `git diff <base_commit>` after tests
`reference_patch`	❌	—	Ground-truth unified diff for patch similarity scoring

Response 202 Accepted:

{ "task_id": "550e8400-e29b-41d4-a716-446655440000", "status": "pending" }

GET /task/{id}

Lightweight status poll — no stdout/stderr payload.

Response 200:

{ "task_id": "...", "status": "pending|running|completed|failed" }

GET /task/{id}/result

Full result once the task completes. Returns 202 while still running.

Response 200:

{
  "task_id":          "...",
  "status":           "completed",
  "exit_code":        0,
  "stdout":           "...",
  "stderr":           "...",
  "tests_passed":     5,
  "tests_failed":     0,
  "lint_errors":      2,
  "lint_output":      "Found 2 errors.",
  "patch_diff":       "diff --git a/src/foo.py ...",
  "patch_similarity": 0.9412,
  "execution_time":   14.2
}

DELETE /task/{id}

Remove a task record from the store.

Response 200:

{ "task_id": "...", "deleted": true }

SWE-bench Lite Compatibility

The task executor is designed to be compatible with the SWE-bench Lite evaluation harness:

Clean workspace per task: Each task runs in its own UUID subdirectory (/Users/AgentUser/tasks/<uuid>/repo/). No git state is shared between tasks — no VM reboot required.
Pinned base commit: The base_commit field maps directly to the SWE-bench instance's base_commit.
Patch application: The patch field accepts a standard unified diff, applied via git apply after checkout.
pytest execution: test_command accepts any pytest invocation; pass/fail counts are parsed from output automatically.
Structured results: Exit code, stdout, stderr, pass/fail counts, and execution time are all returned in a single JSON response. Example SWE-bench task submission:

curl -X POST http://localhost:9090/task/submit \
  -H "Content-Type: application/json" \
  -d '{
    "repo_url":     "https://github.com/psf/requests",
    "base_commit":  "a1b2c3d4",
    "patch":        "<unified diff from SWE-bench instance>",
    "test_command": "python3 -m pytest tests/test_requests.py -x --tb=short",
    "timeout":      600
  }'

Supported Test Frameworks

The executor auto-detects the test framework from test_command and routes to the appropriate parser.

`test_command` contains	Framework	Output parsed
`pytest`, `py.test`	pytest	`5 passed, 2 failed, 1 error in 3.14s`
`cargo`	cargo test	`test result: ok. 5 passed; 0 failed`
`go test`	go test	`--- PASS/FAIL:` lines; `ok`/`FAIL` package lines
`jest`, `npm test`, `yarn test`, `pnpm test`	Jest	`Tests: 2 failed, 5 passed, 7 total`
`dotnet`	dotnet test	`Failed: 2, Passed: 3, Total: 5`
`mvn`, `gradle`, `sbt`, `junit`	JUnit/Surefire	`Tests run: 7, Failures: 2, Errors: 0`

For unrecognised commands, all parsers are tried in order and the first non-zero result is used.

Supported Linters (Soft Score)

Lint results are recorded in lint_errors and lint_output but never change status or exit_code. This is consistent with SWE-bench, HumanEval, and LiveCodeBench conventions.

Linter	Language	Example `lint_command`
`ruff`	Python	`ruff check . --output-format json`
`flake8`	Python	`flake8 src/`
`mypy`	Python	`mypy src/ --ignore-missing-imports`
`pylint`	Python	`pylint src/`
`cargo clippy`	Rust	`cargo clippy -- -D warnings`
`eslint`	JS/TS	`eslint src/ --format json`
`go vet`	Go	`go vet ./...`
`clang-tidy`	C/C++	`clang-tidy src/*.cpp`
`dotnet build`	C#	`dotnet build --no-restore`

API Authentication

When API_TOKEN is set (via environment variable in the macOS guest or the Docker Compose file), every request must include:

Authorization: Bearer <token>

Requests without a valid token return 401 Unauthorized. Set it via SSH before starting the executor:

ssh -p 2222 AgentUser@localhost
export API_TOKEN=your-secret-token
python3 /Users/AgentUser/tasks/task_executor.py &

Or set it persistently in the launchd plist:

<key>EnvironmentVariables</key>
<dict>
    <key>API_TOKEN</key>
    <string>your-secret-token</string>
    <key>TASK_MAX_AGE</key>
    <string>3600</string>
</dict>

Cleanup After Testing

To remove all traces of the task executor from the macOS guest:

ssh -p 2222 AgentUser@localhost
 
# Stop and unload the service
sudo launchctl unload /Library/LaunchDaemons/com.cua.taskexecutor.plist
 
# Remove the plist
sudo rm /Library/LaunchDaemons/com.cua.taskexecutor.plist
 
# Remove the script, log, and any remaining task directories
rm -rf /Users/AgentUser/tasks
 
# Uninstall dependencies
pip3 uninstall flask waitress -y

Remote Access Methods

NoMachine (Recommended)

Primary Remote Access Method: NoMachine provides the best performance and user experience for macOS container access.

Why NoMachine?

Performance Benefits:

Hardware-accelerated rendering
Optimized for macOS GUI
Low latency input handling
Efficient bandwidth usage
Superior video quality

Features:

Full desktop experience
Clipboard sharing (bidirectional)
File transfer capabilities
Audio support
Multi-session support
Keyboard and mouse optimization

Connection Setup

1. Install NoMachine Client:

Download from: https://www.nomachine.com/download
Available for Windows, macOS, Linux

2. Create Connection:

Protocol: NX
Host: your-server-ip
Port: 4000

3. Connect:

Open NoMachine client
Select the connection
Connect to macOS desktop

Best Practices

For Best Performance:

Use wired network connection when possible
Close unused applications in the container
Disable unnecessary animations in macOS settings
Use NoMachine's adaptive quality settings

Network Requirements:

Minimum: 10 Mbps
Recommended: 100 Mbps+
Latency: <50ms for best experience

Use Cases

Primary Development:

Extended coding sessions
Full IDE usage (VS Code, Xcode)
Multi-window workflows
GUI application development

Testing & Debugging:

Interactive debugging
Visual testing
GUI automation development
Screen recording

VNC (Temporary Monitoring)

Important: VNC should ONLY be used for temporary monitoring. Performance is significantly inferior to NoMachine.

When to Use VNC

Appropriate Use Cases:

Quick status checks
Emergency access when NoMachine is unavailable
Automated monitoring scripts
Screenshot capture for monitoring

Not Recommended For:

Primary development work
Extended sessions
Resource-intensive applications
High-quality video requirements

Connection Setup

1. Use Any VNC Client:

TigerVNC
RealVNC
TightVNC
Built-in VNC clients (macOS Screen Sharing)

2. Connect:

Host: your-server-ip:5900
or
Host: your-server-ip
Port: 5900

Performance Comparison

Aspect	NoMachine	VNC
Video Quality	Excellent	Moderate
Latency	Very Low	Higher
Bandwidth Usage	Optimized	Higher
CPU Usage	Low	Higher
Features	Full	Basic
Recommendation	Primary Use	Emergency Only

SSH Access

Port: 2222

Connection

# Basic SSH connection
ssh -p 2222 username@your-server-ip

# With key authentication
ssh -i ~/.ssh/id_rsa -p 2222 username@your-server-ip

# Port forwarding example
ssh -L 8080:localhost:8080 -p 2222 username@your-server-ip

Use Cases

Command-Line Operations:

Script execution
Package installation
System administration
Log viewing

File Transfer:

# Copy files to container
scp -P 2222 file.txt username@your-server-ip:/path/to/destination

# Copy files from container
scp -P 2222 username@your-server-ip:/path/to/file.txt ./

# Using rsync
rsync -avz -e "ssh -p 2222" ./local-dir username@your-server-ip:/remote-dir

Remote Script Execution:

# Execute single command
ssh -p 2222 username@your-server-ip "python3 script.py"

# Execute multiple commands
ssh -p 2222 username@your-server-ip << 'EOF'
cd /path/to/project
git pull
python3 script.py
EOF

Troubleshooting

Common Issues

1. Dock Not Appearing

Symptoms:

macOS dock is missing after boot
Desktop appears but dock doesn't load
Dock was visible before but disappeared

Causes:

Docker not releasing RAM/CPU completely
macOS process management issue
System resource constraints

Solutions:

Option 1: Restart Container (Try This First)

# Stop the container
docker compose -f deploy-macos.yaml stop

# Wait 10 seconds
sleep 10

# Start the container
docker compose -f deploy-macos.yaml start

# Monitor logs
docker logs -f mac_agent

Option 2: Restart Docker Service

# Restart Docker service
sudo systemctl restart docker

# Wait for Docker to fully restart
sleep 15

# Start the container
docker compose -f deploy-macos.yaml up -d

Option 3: System Restart (If Above Don't Work)

# If Docker doesn't release resources properly, a system restart may be necessary
sudo reboot

Prevention:

Ensure adequate system RAM free (8GB recommended)
Don't run too many containers simultaneously
Monitor host system resources regularly
Perform clean container shutdowns

2. Slow Performance During Animations

Symptoms:

Lag during window transitions
Slow animations
Choppy GUI movements
Applications with heavy animations slow down other apps

Cause:

Intel i3 CPU configuration limits animation performance
Current configuration optimized for stability, not animation speed

Solutions:

Option 1: Reduce Animations in macOS

Open System Preferences
Go to Accessibility → Display
Enable "Reduce motion"
Disable "Reduce transparency" if needed

Option 2: Close Animation-Heavy Applications

Avoid running multiple apps with complex animations
Close unnecessary applications
Focus on development tools without heavy UI effects

Option 3: Configuration Adjustment (Advanced)

The current i3 configuration is based on tested and confirmed settings
Configuration can be customized for better animation performance
Requires understanding of system limits and testing
Contact for configuration guidance if needed

Note:

Regular development workloads run smoothly
Issue only affects excessive animation scenarios
Normal coding, browsing, and terminal work unaffected

3. Container Won't Start

Symptoms:

Container exits immediately after start
Error messages in logs
Container status shows "Exited"

Diagnostic Steps:

# Check container logs
docker logs mac_agent

# Check container status
docker ps -a | grep mac_agent

# Inspect container
docker inspect mac_agent

Common Solutions:

KVM Not Available:

# Verify KVM is accessible
ls -l /dev/kvm

# Check if you're in kvm group
groups | grep kvm

# Add user to kvm group if missing
sudo usermod -aG kvm $USER
# Log out and back in

Insufficient Resources:

# Check available RAM
free -h

# Check disk space
df -h

# Verify at least 4GB RAM available

Port Conflicts:

# Check if ports are already in use
sudo netstat -tlnp | grep -E '4000|4444|2222|5900|9090'

# Stop conflicting services or change ports in docker-compose.yaml

4. Remote Access Connection Issues

NoMachine Won't Connect:

# Verify port is exposed
docker port mac_agent 4000

# Check if service is listening
docker exec mac_agent netstat -an | grep 4000

# Test connectivity from host
telnet localhost 4000

VNC Not Working:

# Check VNC port
docker port mac_agent 5900

# Verify VNC server is running
docker exec mac_agent ps aux | grep vnc

SSH Connection Refused:

# Check SSH port mapping
docker port mac_agent 2222

# Verify SSH service
docker exec mac_agent ps aux | grep sshd

5. macOS-Specific Issues

Standard macOS Troubleshooting Applies:

Most macOS-related issues can be resolved using standard macOS troubleshooting methods:

System Preferences Reset:
- Open System Preferences
- Reset specific settings causing issues
- Restart affected applications
Application Issues:
- Force quit misbehaving applications
- Clear application caches
- Reinstall problematic applications via Homebrew
Disk Issues:
- Run Disk Utility
- Verify and repair disk if needed
- Check available storage space
Permission Issues:
- Reset permissions in System Preferences
- Use chmod and chown as needed
- Check application permissions in Security & Privacy

These are standard macOS issues, not container-specific problems.

Getting Help

If you encounter issues not covered here:

Check container logs: docker logs mac_agent
Review system resources: Ensure minimum requirements are met
Verify KVM access: Confirm /dev/kvm is accessible
Test connectivity: Check network and port accessibility
See Reporting Issues section for how to get support

CI/CD Integration

The macOS container is designed for seamless integration into CI/CD pipelines, particularly for Computer Use Agent development and deployment.

IMPORTANT: When deploying this container in CI/CD pipelines or production environments, ensure compliance with Apple's Software License Agreement (EULA) for macOS. Commercial or enterprise deployments may require additional licensing from Apple.

Supported Platforms

Container Orchestration:

✅ Docker - Native Docker deployment
✅ Kubernetes - K8s pod deployment
✅ Docker Compose - Multi-container orchestration
✅ Docker Swarm - Swarm service deployment

CI/CD Systems:

GitHub Actions
GitLab CI/CD
Jenkins
CircleCI
Travis CI
Any system supporting Docker

Docker-Based CI/CD

GitHub Actions CI/CD Example

name: Agent macOS Tests
 
on: [push, pull_request]
 
jobs:
  test:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v3
      
      - name: Set up KVM
        run: |
          sudo apt-get update
          sudo apt-get install -y qemu-kvm libvirt-daemon-system
          sudo usermod -aG kvm $USER
      
      - name: Start macOS Container
        run: |
          docker compose -f deploy-macos.yaml up -d
          sleep 90  # Wait for macOS boot and task executor to be ready
      
      - name: Submit task via REST API
        run: |
          # The task executor runs inside the macOS QEMU guest.
          # Use the REST API on port 9090 — docker exec cannot reach the guest.
          TASK_ID=$(curl -s -X POST http://localhost:9090/task/submit \
            -H "Content-Type: application/json" \
            -d '{
              "repo_url": "https://github.com/your-org/your-repo",
              "base_commit": "main",
              "test_command": "python3 -m pytest tests/ -x --tb=short",
              "timeout": 300
            }' | python3 -c "import sys,json; print(json.load(sys.stdin)['task_id'])")
          echo "TASK_ID=$TASK_ID" >> $GITHUB_ENV
      
      - name: Poll for result
        run: |
          for i in $(seq 1 60); do
            STATUS=$(curl -s http://localhost:9090/task/$TASK_ID | python3 -c "import sys,json; print(json.load(sys.stdin)['status'])")
            echo "Status: $STATUS"
            if [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ]; then
              break
            fi
            sleep 5
          done
          curl -s http://localhost:9090/task/$TASK_ID/result | python3 -m json.tool
      
      - name: Cleanup
        if: always()
        run: docker compose -f deploy-macos.yaml down

GitLab CI Example

stages:
  - test

macos_tests:
  stage: test
  image: docker:latest
  services:
    - docker:dind
  variables:
    DOCKER_DRIVER: overlay2
  before_script:
    - docker info
  script:
    - docker compose -f deploy-macos.yaml up -d
    - sleep 90
    - |
      TASK_ID=$(curl -s -X POST http://localhost:9090/task/submit \
        -H "Content-Type: application/json" \
        -d '{"repo_url":"https://github.com/your-org/your-repo","test_command":"python3 -m pytest tests/ -x","timeout":300}' \
        | python3 -c "import sys,json; print(json.load(sys.stdin)['task_id'])")
    - sleep 30
    - curl -s http://localhost:9090/task/$TASK_ID/result | python3 -m json.tool
  after_script:
    - docker compose -f deploy-macos.yaml down
  tags:
    - kvm

Kubernetes Deployment

Pod Specification

apiVersion: v1
kind: Pod
metadata:
  name: macos-agent
  labels:
    app: macos-base
spec:
  containers:
  - name: mac-agent
    image: nullvoider/mac15-base:v1
    ports:
    - containerPort: 4000
      name: nomachine
    - containerPort: 4444
      name: eye-server
    - containerPort: 2222
      name: ssh
    - containerPort: 5900
      name: vnc
    - containerPort: 9090
      name: task-executor
    securityContext:
      capabilities:
        add:
        - NET_ADMIN
    volumeMounts:
    - name: kvm
      mountPath: /dev/kvm
  volumes:
  - name: kvm
    hostPath:
      path: /dev/kvm
      type: CharDevice
  restartPolicy: Always

Deployment with Service

apiVersion: apps/v1
kind: Deployment
metadata:
  name: macos-agent-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      app: macos-base
  template:
    metadata:
      labels:
        app: macos-base
    spec:
      containers:
      - name: mac-agent
        image: nullvoider/mac15-base:v1
        ports:
        - containerPort: 4000
        - containerPort: 4444
        - containerPort: 2222
        - containerPort: 5900
        - containerPort: 9090
---
apiVersion: v1
kind: Service
metadata:
  name: macos-agent-service
spec:
  selector:
    app: macos-base
  ports:
  - name: nomachine
    port: 4000
    targetPort: 4000
  - name: eye
    port: 4444
    targetPort: 4444
  - name: ssh
    port: 2222
    targetPort: 2222
  - name: vnc
    port: 5900
    targetPort: 5900
  - name: task-executor
    port: 9090
    targetPort: 9090
  type: LoadBalancer

Use Cases

Computer Use Agent Development:

Automated testing of CUA implementations
Training data collection in reproducible environments
Performance benchmarking
Integration testing

macOS Application Testing:

Cross-platform application testing
macOS-specific feature validation
GUI automation testing
Compatibility verification

Continuous Integration:

Automated builds on macOS environment
Unit testing with macOS dependencies
Integration testing with macOS services
End-to-end testing workflows

Best Practices

Resource Management:

# Kubernetes resource limits
resources:
  requests:
    memory: "4Gi"
    cpu: "4"
  limits:
    memory: "8Gi"
    cpu: "8"

Health Checks:

# Kubernetes liveness probe
livenessProbe:
  exec:
    command:
    - /bin/bash
    - -c
    - "pgrep -f NoMachine"
  initialDelaySeconds: 120
  periodSeconds: 30

Cleanup Strategy:

Always use docker compose down or equivalent cleanup
Implement timeout for long-running tests
Monitor resource usage during CI runs
Use ephemeral runners when possible

Reporting Issues

When reporting issues, please provide comprehensive information to help diagnose and resolve problems quickly.

Bug Reports

Required Information:

Environment Details:

# Docker version
docker --version
docker compose version

# Host OS information
cat /etc/os-release
uname -a

# KVM information
kvm-ok
ls -l /dev/kvm

System Resources:

# Available RAM
free -h

# Disk space
df -h

# CPU information
lscpu

Container Logs:

# Full container logs
docker logs mac_agent > container-logs.txt

# Last 200 lines
docker logs --tail 200 mac_agent

# Real-time logs
docker logs -f mac_agent

Container Status:

# Container details
docker ps -a | grep mac_agent
docker inspect mac_agent

# Resource usage
docker stats mac_agent --no-stream

Steps to Reproduce:
- Detailed steps to reproduce the issue
- Expected behavior
- Actual behavior
- Screenshots or screen recordings if applicable
Configuration:
- Docker Compose file contents
- Any custom modifications
- Environment variables used

Feature Requests

Required Information:

Use Case Description:
- What problem does this feature solve?
- Who would benefit from this feature?
- How urgent is this feature?
Proposed Implementation:
- How should the feature work?
- What configuration options should it have?
- Any technical considerations?
Impact Assessment:
- How would this affect existing functionality?
- Resource implications (CPU, RAM, disk)?
- Compatibility considerations?
Alternatives Considered:
- What alternatives have you considered?
- Why is this approach preferred?

Contact Information

For Direct Support:

X (Twitter): @nullvoider07

When Reporting:

Be specific and detailed
Include all requested information
Attach logs and screenshots
Describe impact and urgency

FAQ

Coding Agent Evaluation Questions

Q: What new eval capabilities were added in v1? A: The Task Executor API now supports lint_command (soft-score linting), capture_diff (records git diff <base_commit> after the test run), and reference_patch (ground-truth unified diff for patch similarity scoring returning a 0.0–1.0 ratio). Multi-framework test scoring covers pytest, cargo, go test, jest, dotnet, and JUnit/Maven/Gradle/sbt — auto-detected from test_command. See the Task Executor REST API section for full field reference.

Q: Why is lint scoring soft — why doesn't it fail the task? A: The majority of established coding benchmarks (SWE-bench, HumanEval, LiveCodeBench) use test pass/fail as the primary correctness signal. Lint errors reflect code quality but not functional correctness. Keeping lint as a soft score lets you track quality trends without invalidating otherwise correct solutions.

Q: What is patch_similarity and when is it useful? A: It is a 0.0–1.0 similarity ratio between the agent's actual diff and a ground-truth reference patch, computed after stripping all unified diff metadata (file paths, line numbers, git object hashes). Most useful for patch-apply evals where a canonical solution exists. Always interpret alongside tests_passed — a lower similarity score does not mean the solution is wrong.

Q: How do I access the Task Executor API remotely from outside the container? A: The Task Executor runs inside the macOS QEMU guest and is forwarded to the Docker host via QEMU's hostfwd on port 9090. From outside the host, it is reachable at http://your-server-ip:9090 as long as port 9090 is exposed in the Compose file (which it is by default). Always set API_TOKEN when the port is reachable outside a trusted network boundary.

Q: In a k8s deployment with many replicas, how does an orchestrator target a specific pod? A: Each replica runs its own Task Executor with its own in-memory task store. The orchestrator must track the pod IP (or headless service DNS entry) at submission time and send all status/result polls to the same pod — a load-balanced service may route to a different replica and return 404 Task not found. Use a headless k8s service to get per-pod DNS entries, or record the pod IP at submission time.

Q: What happens to in-flight tasks if a pod is evicted or restarted? A: Tasks are in-memory inside the macOS guest and are lost on restart. The macOS container's ~4-second boot means recovery is fast, but the orchestrator must still implement retry logic and treat 404 Task not found as a signal to resubmit.

Q: How do I pass API_TOKEN securely in a k8s deployment? A: Mount it as a k8s Secret and inject it into the launchd plist environment via an init container or startup script. Never hardcode tokens in the Compose file or Dockerfile:

env:
  - name: API_TOKEN
    valueFrom:
      secretKeyRef:
        name: task-executor-secret
        key: api-token

Q: Can the Task Executor run tasks in parallel? A: Yes — each submitted task runs in an independent background thread with its own isolated UUID workspace under /Users/AgentUser/tasks/. Tasks never share git state. For large-scale parallelism, deploy multiple container replicas via k8s; each replica maintains its own in-memory store.

General Questions

Q: Can I use this container for coding agent evaluation like SWE-bench? A: Yes. The Task Executor REST API (port 9090) provides exactly the interface needed: submit a repo URL, base commit, patch, and test command; poll for status; retrieve structured results including exit code, stdout, stderr, and pytest pass/fail counts. Each task gets an isolated UUID workspace so concurrent tasks and sequential tasks never share state. See the Task Executor REST API section for full setup and usage.

Q: Why can't I use docker exec mac_agent <command> to run commands inside macOS? A: This container runs macOS inside a QEMU virtual machine. docker exec executes commands on the Ubuntu Docker host layer, not inside the macOS guest. To run commands in macOS, use SSH on port 2222 or the Task Executor REST API on port 9090.

Q: How is the entire macOS system running in a single container?
A: This container uses advanced virtualization techniques with KVM acceleration to run a complete macOS system. Unlike Dockur and Docker-OSX which require multiple external files and complex setups, this build has everything self-contained within the container image, the result is a fully functional macOS 15.7.5 environment that's completely isolated and ephemeral.

Q: Why doesn't this container need external files like Dockur and Docker-OSX?
A: The container architecture was designed from the ground up to be self-contained. All necessary components, including the macOS system files, bootloader, and configuration, are embedded within the container image itself. This provides significant advantages: easier deployment, cleaner state management, no external file dependencies, and true ephemeral operation.

Q: What makes this container different from Docker-OSX and Dockur?
A: Several key differences:

No External Files: Everything is self-contained in the container
Better Performance: 20-30% CPU usage vs higher overhead in alternatives
Smoother Operation: Optimized for stability and responsiveness
Ephemeral State: Clean isolation without external dependencies
Simpler Deployment: Just Docker Compose, no complex file management
Customizable: Configuration can be tuned for specific hardware

Q: Can I run multiple instances of this container?
A: Yes, but each instance requires 4GB of RAM. Ensure your host has sufficient resources (e.g., 8GB+ RAM for 2 instances).

Q: How much disk space does it need?
A: The container image requires approximately 100GB of host disk space. The macOS system inside has a 4TB virtual disk.

Q: Is this suitable for production use?
A: Yes, it's specifically designed for Computer Use Agent development and deployment in production environments. The container provides a stable, reproducible macOS environment ideal for CI/CD pipelines and automated testing. Important: For production use, ensure compliance with Apple's Software License Agreement (EULA), as commercial deployment of macOS may have specific licensing requirements.

Performance Questions

Q: What is the boot time?
A: The container is ready in approximately 30 seconds — the macOS system and all services (NoMachine, Task Executor, Eye) are live immediately after the container starts. This is one of the key advantages over Dockur and Docker-OSX alternatives.

Q: Can I improve the performance?
A: Yes, the current Intel i3 CPU configuration can be customized for better performance based on your hardware. The existing configuration prioritizes stability and compatibility. For better animation performance, you can adjust the CPU configuration, though this requires testing on your specific hardware.

Q: Why does NoMachine perform better than VNC?
A: NoMachine uses hardware acceleration, optimized protocols, and better compression algorithms specifically designed for remote desktop performance. VNC uses a more basic protocol that's less efficient for macOS GUI rendering.

Q: What's the CPU usage under heavy load?
A: Under normal development workloads (coding, browsing, terminal work), expect 20-30% CPU. Heavy compilation or animation-intensive applications may increase this to 40-50%.

Compatibility Questions

Q: Does it work on Windows/macOS hosts?
A: It requires a Linux host with KVM support. Windows (WSL2 with nested virtualization) and macOS hosts are not officially supported due to KVM requirements.

Q: What Linux distributions are supported?
A: Any modern Linux distribution with Docker 24.0+ and KVM support:

Ubuntu 20.04+
Debian 11+
Fedora 36+
CentOS 8+
Arch Linux

Q: Can I use AMD CPUs?
A: Yes, as long as AMD-V (SVM) is enabled in BIOS and the KVM kernel modules are loaded.

Q: What about ARM processors (Apple Silicon)?
A: Not supported. This is an x86_64 container designed for Intel/AMD processors only.

Configuration Questions

Q: Can I change the RAM allocation?
A: The container is configured for 4GB RAM. Changing this requires rebuilding the container image with modified configuration. This is not recommended without thorough testing.

Q: How do I add more software to the container?
A: Use Homebrew inside the running container:

brew install package-name

For persistence, create a custom image based on this one.

Q: Can I use this for iOS app development?
A: Xcode command line tools are available, but full Xcode IDE may require additional configuration. The container is optimized for Computer Use Agent development.

Q: How do I persist data across container restarts?
A: Use Docker volumes to mount directories from the host:

volumes:
  - ./my-projects:/Users/username/projects

Remote Access Questions

Q: Why can't I use VNC for development work?
A: VNC performance is significantly lower than NoMachine. It's suitable only for monitoring or quick checks. For actual development work, the lag and lower frame rate make it impractical.

Q: Can I use other remote desktop solutions?
A: The container is pre-configured with NoMachine and VNC. Adding other solutions would require custom configuration.

Q: What's the bandwidth requirement for NoMachine?
A: Minimum 10 Mbps, recommended 100 Mbps+ for best experience. Less bandwidth will work but may impact video quality.

Troubleshooting Questions

Q: The dock isn't appearing. What should I do?
A: First try restarting the container. If that doesn't work, restart the Docker service. In rare cases, a system restart may be needed to fully release resources.

Q: Why are animations slow?
A: The Intel i3 CPU configuration prioritizes stability. You can reduce animations in macOS settings or customize the CPU configuration for better animation performance.

Q: How do I access container logs?
A:

docker logs mac_agent
docker logs -f mac_agent  # Follow mode

Q: The container won't start. What's wrong?
A: Check:

KVM is accessible (ls -l /dev/kvm)
Sufficient RAM available (8GB free)
Ports aren't conflicting
Docker service is running
Container logs for specific errors

Security Questions

Q: Is this container secure?
A: The container runs with NET_ADMIN capability and requires KVM access. It's designed for development environments. For production, review security considerations and implement appropriate network isolation.

Q: Can I run this in a public cloud?
A: Only on infrastructure that exposes hardware virtualization extensions to the guest. Bare-metal instances work universally. Standard VM instances require the cloud provider to explicitly enable nested virtualization — AWS Nitro, Google Cloud, and Azure support it on select instance types, but it must be enabled per-instance and is not on by default. The limiting factor is the hypervisor configuration, not the host OS.

Q: How do I secure remote access?
A: Use VPN or SSH tunneling to access the container:

ssh -L 4000:localhost:4000 -p 2222 host-server

Then connect NoMachine to localhost:4000.

License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0) for the container infrastructure, configuration, and custom components. However, macOS and Apple software are subject to Apple's Software License Agreement.

License Scope

GPL-3.0 Applies To:

Container configuration files and Docker Compose setup
Custom scripts and automation tools created by the developer
Integration code and custom components
Documentation and setup instructions
Any modifications you make to these components

GPL-3.0 Does NOT Apply To:

macOS operating system (proprietary Apple software under Apple EULA)
Apple applications and frameworks
Third-party commercial software included in the container
Other third-party software with their own licenses

GPL-3.0 License Summary

Permissions (for GPL-3.0 covered components only):

✅ Commercial use
✅ Modification
✅ Distribution
✅ Patent use
✅ Private use

Conditions (for GPL-3.0 covered components):

📋 License and copyright notice
📋 State changes
📋 Disclose source
📋 Same license (copyleft)

Limitations:

❌ Liability
❌ Warranty

Apple EULA Requirements

IMPORTANT: By using this container, you agree to comply with Apple's Software License Agreement for macOS. Key requirements include:

macOS is licensed, not sold
Use restrictions apply based on Apple's EULA
Commercial deployment may require additional Apple licenses
Redistribution of macOS is subject to Apple's terms
You are responsible for ensuring EULA compliance

What This Means for Users

For the Container Infrastructure (GPL-3.0):

You can use, modify, and distribute the container configuration
You can create derivative works of the setup scripts
If you distribute modified versions, you must:
- Include the GPL-3.0 license
- Make your source code modifications available
- License your modifications under GPL-3.0
- Document any changes made

For macOS and Apple Software (Apple EULA):

You must comply with Apple's Software License Agreement
Review Apple's EULA before commercial use
Some use cases may require Apple's approval or additional licensing
You are solely responsible for EULA compliance

Combined Usage: When using this container, you must comply with BOTH:

GPL-3.0 for container infrastructure components
Apple's EULA for macOS and Apple software

The developer provides the container infrastructure under GPL-3.0 but cannot grant rights to macOS itself—those rights come from Apple's EULA.

Full Licenses

GPL-3.0: https://www.gnu.org/licenses/gpl-3.0.en.html
Apple EULA: https://www.apple.com/legal/sla/

Disclaimer

This container is provided "as is" without warranty of any kind. The developer is not affiliated with Apple Inc. Users are responsible for ensuring their use complies with all applicable licenses and laws.

About This Project

The macOS 15.7.5 Container represents a significant advancement in containerized macOS environments. Built for Computer Use Agent development and frontier coding agent evaluation, this project addresses the key challenges faced by developers working with macOS-based automation and AI agents.

Version 2 extends the original CUA environment into a full coding agent evaluation platform. The Task Executor API — covering multi-framework test scoring, programmatic lint integration, diff capture, and ground-truth patch similarity scoring — was designed to support rigorous benchmarking on a native macOS runtime, enabling SWE-bench-style workflows and broader eval harness compatibility on Apple's platform.

Project Goals

Primary Objectives:

Provide a reproducible macOS environment for CUA development
Eliminate external file dependencies for cleaner deployments
Optimize performance while maintaining stability
Enable seamless CI/CD integration for macOS workflows
Support scalable agent training and testing

Design Philosophy:

Self-Contained: Everything in one container, no external files
Ephemeral: Clean state management with proper isolation
Performant: Optimized for real-world development workflows
Tested: Based on confirmed safe and stable configurations
Accessible: Simple deployment with Docker Compose

Development Journey

This container was built from the ground up through:

Extensive testing on real hardware
Iterative performance optimization
Configuration tuning for stability
Integration of development tools
Refinement of remote access methods

Every configuration choice, from the Intel i3 CPU setting to the customizable RAM allocation, is based on tested and confirmed performance characteristics. The current configuration represents what can be safely delivered and has been verified to work reliably.

Why This Matters

For Developers:

Consistent macOS environment across team members
No "works on my machine" issues
Fast setup and deployment
Integrated development tools
Built-in monitoring capabilities

For Organizations:

Reproducible testing environments
CI/CD pipeline integration
Scalable agent deployment
Cost-effective macOS access
Clean resource management

Future Direction

While the current configuration is optimized for compatibility and stability, the container is designed to be customizable. As hardware capabilities evolve and use cases expand, configurations can be adjusted to leverage more powerful systems while maintaining the core benefits of containerization.

Acknowledgments

This project builds on the containerization ecosystem and the work of many in the Docker and virtualization communities. Special recognition to:

The Docker team for container technology
The KVM project for virtualization
The open-source community for tools and libraries

Get Involved

Feedback & Contact:

X (Twitter): @nullvoider07
Report issues with detailed information
Share your use cases and experiences
Suggest improvements and features

Contributing: While the core implementation details are open-source, feedback on:

Performance optimization suggestions
Use case requirements
Bug reports and fixes
Documentation improvements

...is always welcome and appreciated.

Last Updated: May, 2026
Version: 1
Developer: Kartik (NullVoider)
License: GPL-3.0

macOS 15.7.5 - Full macOS in one self-contained container. No compromises, no external files, no BS. Powerful. Just works. 🚀

Downloads last month: -; Downloads are not tracked for this model. How to track

Inference Providers NEW

This model isn't deployed by any Inference Provider. 🙋 Ask for provider support

macOS 15.7.5

⚖️ Legal Notice

Table of Contents

Overview

Purpose

What Makes This Unique

Key Features

Operating System

Development Tools

Applications

Remote Access

Performance & Stability

Container Capabilities

Operating System

Development Tools

Programming Languages & Runtimes

IDEs & Editors

Build Tools & Utilities

Remote Access

NoMachine (Port 4000) - Recommended

VNC (Port 5900) - For Temporary Monitoring Only

SSH (Port 2222)

Technical Specifications

System Requirements

Minimum Requirements

Recommended Requirements

Container Resource Usage

Performance Metrics

Installation & Deployment

Prerequisites

1. Install Docker

2. Enable KVM

Docker Compose Deployment

1. Create Docker Compose File

2. Deploy the Container

3. Container Management

Testing the Container

1. Verify Container is Running

2. Check Boot Progress

3. Test Remote Access

4. Verify Services

5. Health Check

Customizing the Image

Prerequisites

Step 1 — Modify the YAML Configuration (Optional)

Step 2 — Convert the QCOW2 to a Raw Image

Step 3 — Create the macOS Directory Structure

Step 4 — Place the Disk Images

Step 5 — Boot and Customize

Step 6 — Clean Up Before Capture

Step 7 — Shut Down and Stop the Container

Step 8 — Convert Back to QCOW2

Step 9 — Move the QCOW2 to the Build Directory

Step 10 — Build Your Custom Image

Installed Software

Pre-installed Applications

Productivity & Development

System Utilities

Command Line Tools

Package Managers

Development Utilities

Build Tools

Development Environments

Python Development

Node.js Development

Go Development

Rust Development

Java Development

C#/.NET Development

iOS/macOS Development

The-Eye Integration

Overview

Configuration

Connection & Endpoints

Python SDK

Key Features

Quick Usage Examples

Performance Impact

Configuration Options

Task Executor REST API