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

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 Xcode build 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; use a NoMac smoke build.
Never change the bundle ID or entitlements without approval.
Never submit to App Review without explicit human confirmation.

Step 5: connect the cloud Xcode build

Authenticate inside WSL, under the same user that runs the agent:

npx @nomac/cli 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 call push_project and run workflow=smoke. Poll status and use get_failure 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, push the complete
project to NoMac and run a smoke build. Explain any remote diagnostic before
editing. After a successful smoke build, stop and ask whether I want a signed
TestFlight release.

Step 7: test the signed app

Approve workflow=release for a coherent feature checkpoint. When App Store Connect finishes processing, 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.

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 cloud smoke build 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.