macOS - Namespace Documentation

Documentation Index

Fetch the complete documentation index at: /docs/llms.txt

Use this file to discover all available pages before exploring further.

Assistant

Responses are generated using AI and may contain mistakes.

macOS instances run on Apple M4 Pro or M5 Max processors, delivering native Apple Silicon performance. These processors provide hardware acceleration for graphics, machine learning, and compute workloads.Note: To switch to M5 Max exclusively, reach out to us via support@namespace.so.

Built for Apple Development

The platform includes native support for the complete Apple development ecosystem, including Xcode, iOS, and Metal.Our macOS environment is optimized for Apple development workflows:

Fast access to the latest Xcode and macOS versions
Multiple supported OS versions: Sonoma (14), Sequoia (15), Tahoe (26) and Golden Gate (27)
- Use shape selectors to specify desired base image.
Build and test native iOS and macOS applications
Support for up to 12 vCPU and 56GB of RAM
- List of available shapes

VNC Integration

Namespace supports visual debug access which is invaluable for debugging GUI applications, testing user interfaces, and investigating display-related issues.Access your Mac runners through Remote Display (VNC) directly from the Namespace dashboard.

You can also start a VNC session using our CLI:

nsc vnc <instance-id>

VNC support is currently available for macOS runners. Support for other platforms is in development.

Running Custom Applications

You can run your own applications directly on macOS instances using the Namespace Compute API. An instance is created with one or more applications, each pointing at a container image that carries your binary and the command to execute.The macrun example demonstrates the full flow:

Build a darwin/arm64 binary (CGO_ENABLED=0 GOOS=darwin GOARCH=arm64 go build).
Package it into a container image and push it to the Namespace Container Registry.
Create a macOS instance with an InstanceShape (Os: "macos", MachineArch: "arm64") and an ApplicationRequest referencing the pushed image, the Command to run, and its Args.
Wait for the instance to become ready.

resp, err := cli.Compute.CreateInstance(ctx, &computepb.CreateInstanceRequest{
    Shape: &computepb.InstanceShape{
        VirtualCpu:      6,
        MemoryMegabytes: 14 * 1024,
        Os:              "macos",
        MachineArch:     "arm64",
    },
    Applications: []*computepb.ApplicationRequest{{
        Name:     "helloworld",
        ImageRef: mainImage,
        Command:  "entrypoint",
        Args:     []string{"-what", "caller"},
    }},
})

See the integrations repository for the complete, runnable example.

Base Image Selection

When starting a macOS workload on Namespace you can define requirements for the desired base image in form of selectors. The selectors are a sequence of name-value pairs passed to instance creation request. Note that there may be multiple selectors for the same name (all of them will try to be satisfied).

Available Selectors

These are the available selectors and options:

Name	Value	Description
macos.version		base system version
`14.x`	macOS Sonoma
`15.x`	macOS Sequoia
`26.x`	macOS Tahoe
`27.x`	macOS Golden Gate
image.with		can be specified multiple times
`xcode-26`	with Xcode 26
`xcode-beta`	with beta versions of Xcode

Using these selectors you can identify the following images:macos.version=14.x : macOS Sonomamacos.version=15.x : macOS Sequoia with Xcode 16macos.version=15.x,image.with=xcode-26 : macOS Sequoia with Xcode 26 and betasmacos.version=26.x : macOS Tahoe with Xcode 26macos.version=26.x,image.with=xcode-beta : macOS Tahoe with Xcode 26 betamacos.version=27.x : macOS Golden Gate with Xcode 27

An image can include multiple Xcode versions under /Applications/Xcode_*.app. Image selectors choose the base image, which determines the installed Xcode versions and the default. They do not select a specific installed patch version. The runner images page lists the Xcode versions included in each image. You can also list the versions on a runner and use xcode-select to switch to the one you need:

ls -d /Applications/Xcode_*.app
sudo xcode-select --switch /Applications/Xcode_26.6.app
xcodebuild -version

How to Use

The selectors can be specified on the command line when nsc CLI is used:

nsc create --selectors name1=value1,name2=value2 ...

They are part of InstanceShape message in Namespace SDK.

macOS Image Updates

Namespace team continuously makes changes to macOS runner images to keep the software up-to-date and add new Xcode versions as soon as Apple releases them. To get notified about upcoming changes and releases subscribe to the RSS feed:Base Images Updates

OS Simulators

macOS instances ship with the Apple platform simulators, so you can build and test across Apple’s operating systems without physical devices. The available simulators are:

iOS
tvOS
visionOS
watchOS

We offer broad simulator support, including the latest Duo simulator.

The latest Duo simulator is only available on macOS Tahoe 26.6.2 with Xcode 27.1-Beta.To see exactly which simulators and device types your macOS instance offers, run the following in your instance:

xcrun simctl list devicetypes

Xcode 26 Compilation Cache

Xcode 26 introduces a new Compilation Cache feature that significantly speeds up build times by reusing compiled outputs across checkouts and builds. This feature can be used in conjunction with Namespace Cache Volumes to leverage the compilation cache across CI runs.

Xcode Caching on GitHub Runners

Xcode caching is fully integrated into Namespace GitHub Runners:

Turn on caching for your runners via Runner Profile or runner labels.
Add namespacelabs/nscloud-cache-action step to your workflow to configure Xcode to use the cache (also SwiftPM and CocoaPods caches):

    - name: Configure Xcode Caching
      uses: namespacelabs/nscloud-cache-action@v1
      with:
        cache: |
          xcode
          swiftpm
          cocoapods

You can verify that the caching kicks in by looking at the CompilationCacheMetrics section in the logs that xcodebuild outputs:

...
CompilationCacheMetrics
note: 4 hits / 4 cacheable tasks (100%)
...

Last modified onSeptember 22, 2026

Ctrl+I

Documentation Index

​ Built for Apple Development

​ VNC Integration

​ Running Custom Applications

​ Base Image Selection

​ Available Selectors

​ How to Use

​ macOS Image Updates

​ OS Simulators

​ Xcode 26 Compilation Cache

​ Xcode Caching on GitHub Runners