VS Code and WSL for iOS development

Set up a clean Windows and WSL workspace for Swift, Git, and AI coding agents, then use remote Xcode builds and TestFlight for the native iOS steps.

September 9, 2026 · 9 min read

Need a Mac for this? NoMac gives your agent full macOS with Xcode for $0.80 an hour, billed per minute. Start now →

VS Code and WSL make a good Windows workspace for iOS source code, Git, Swift packages, and AI coding agents. They do not run Xcode or the iOS Simulator. The native app must still be compiled and signed on macOS, then tested through TestFlight or a remote Mac.

Use WSL when you want Linux command-line tools and a predictable agent environment while keeping Windows as the desktop. Use the official Swift extension for portable Swift code and a cloud Mac with Xcode for the complete iOS target.

What this setup is good at

Step 1: install WSL correctly

Microsoft's official WSL installation guide supports a one-command setup on current Windows:

wsl --install

Run that from an administrator PowerShell window and restart when prompted. The default distribution is Ubuntu, but Microsoft documents how to list and choose other distributions. New installations use WSL 2 by default.

Create a normal Linux user. Keep the repository inside the Linux filesystem, such as ~/projects/my-app, when most tools run in WSL. This avoids inconsistent permissions and slower cross-filesystem access.

Step 2: connect VS Code to WSL

Install VS Code on Windows and Microsoft's WSL extension. Open a WSL terminal, enter the project directory, and launch:

cd ~/projects/my-app
code .

Confirm that the lower-left remote indicator shows the WSL distribution. Install project extensions into the WSL environment when prompted, because language servers and terminal commands need to run beside the source.

Step 3: add Swift support where it helps

Install Swift in WSL from the current Swift.org instructions for your Linux distribution, then install the official Swift extension in the remote VS Code window. Swift.org's VS Code guide lists completion, navigation, refactoring, package tasks, debugging, and tests.

The extension is designed primarily for Swift Package Manager projects and projects that produce a compilation database. It does not reproduce all Xcode project features or make SwiftUI available on Linux. Put portable core code in a Swift package if you want meaningful local builds and tests.

cd Packages/AppCore
swift build
swift test

Step 4: install the agent in WSL

Install Claude Code, Codex, or another terminal agent using its current official instructions. Run it inside WSL so its files, shell commands, Git, and MCP tools all share one environment.

Add a short repository instruction file:

Development environment: Windows with WSL 2.
Run portable Swift tests in Packages/AppCore.
The iOS target cannot compile locally; build it on a NoMac Mac.
Never change the bundle ID or entitlements without approval.
Never submit to App Review without explicit human confirmation.

Step 5: connect a cloud Mac

Add credit at nomac.app/mac ($0.80 an hour, billed per minute). Then install the CLI and log in inside WSL, under the same user that runs the agent. It needs Node 20 or newer, OpenSSH and rsync.

npm install -g @nomac/cli
nomac login

Then register the local MCP server:

# Claude Code
claude mcp add nomac -- npx @nomac/cli mcp

# OpenAI Codex
codex mcp add nomac -- npx @nomac/cli mcp

Do not install the CLI on Windows and the agent in WSL, or the reverse, unless you deliberately manage the path and credential boundary. The simplest rule is that repository, agent, and local MCP server live together.

Step 6: use a two-level test loop

Fast local checks

• ·Run portable Swift package tests.
• ·Run JavaScript, Dart, backend, formatting, and static-analysis checks.
• ·Review the diff and search for secrets or generated output.
• ·Confirm the Xcode project, shared scheme, bundle ID, and lockfiles are present.

Authoritative iOS checks

Ask the agent to start a Mac (start_mac, or nomac start), sync the project into ~/drive/src with nomac sync ., and run an unsigned Simulator build with xcodebuild. The agent reads the compiler output before fixing a failed build. This confirms SwiftUI, UIKit, native dependencies, project configuration, and the iOS deployment target.

Run every supported local test in WSL. If they pass, start a NoMac Mac,
sync the complete project and build it for the iOS Simulator with xcodebuild.
Explain any diagnostic before editing. After a successful build, stop and ask
whether I want a signed TestFlight build.

Step 7: test the signed app

Connect an App Store Connect team key once at nomac.app/apple. For a coherent feature checkpoint, the agent runs set_up_signing (nomac sign), archives and exports with the commands it returns, and sends the .ipa with send_to_testflight (nomac testflight). When App Store Connect finishes processing, usually in 5 to 15 minutes, install the build from TestFlight. Send the build number, screenshots, steps, and expected behavior back to the WSL agent.

Test real iPhone concerns: safe areas, keyboard, large text, VoiceOver labels, camera and photo permissions, notifications, offline behavior, backgrounding, and relaunch with saved data.

Stop the Mac when you are done. Stopping deletes the VM; the account's 20 GB drive at ~/drive keeps the project and its build caches for the next session.

Common WSL problems

• ·The repo lives under /mnt/c. Large dependency trees and mixed permission behavior can be slower and less predictable. Prefer the WSL filesystem.
• ·Two copies of Git edit the same worktree. Choose the WSL Git for the WSL repository to avoid line-ending and ownership surprises.
• ·The Swift extension is installed only on Windows. Install it in the remote WSL extension host too.
• ·Local Swift tests import SwiftUI. Move portable logic into a package without Apple UI imports.
• ·The agent assumes local tests prove iOS. Make the build on the cloud Mac an explicit acceptance gate.

When to skip WSL

Use native Windows Swift if you only need portable Swift tools and prefer PowerShell. Use Cursor directly on Windows if that is already your complete editor workflow. Use a Linux VPS or Codespaces when you want the workspace to stay available without leaving the Windows computer awake.

WSL is useful plumbing, not the reason the iOS build works. The complete path is VS Code for editing, WSL for tools and agents, NoMac for Xcode and signing, and TestFlight for the phone. Continue with the complete Windows iOS guide or the 2026 publishing guide.