Supported Platforms

Wallfacer runs VMs on two platforms: Linux (Firecracker micro-VMs) and macOS (Tart / Apple Virtualization). Each platform has different pre-installed tools, workspace paths, and capabilities.

Linux (linux/amd64)

The default platform for most development work. Linux VMs run inside Firecracker micro-VMs, providing lightweight and fast isolation.

Default workspace: /workspace

Set in manifest:

platform:
  os: linux/amd64

Pre-Installed Tools

Capabilities

• Build and run web applications in any language or framework
• Use Docker Compose for multi-container stacks (databases, caches, message queues)
• Access a browser-based VSCode editor alongside Claude Code
• Run full test suites with real databases and services
• Install additional packages via apt (sudo access is available)
• Use npm global packages without root access (pre-configured npm prefix)

Docker-in-Docker

Linux VMs include a full Docker daemon. Projects that rely on Docker Compose can spin up their entire stack -- database, cache, background workers -- exactly as they would on a developer's local machine.

macOS (darwin/arm64)

For iOS, macOS, and Swift development. macOS VMs run on Apple Silicon hardware via Tart (Apple Virtualization.framework).

Default workspace: /Users/admin/workspace

Set in manifest:

platform:
  os: darwin/arm64

Pre-Installed Tools

Common development tooling via Homebrew, plus:

Capabilities

• Build and run iOS apps using Xcode and the iOS Simulator
• Test on specific device types (iPhone, iPad)
• View the simulator screen in real time via WebSocket streaming
• Send touch input, swipes, and gestures through the browser
• Take screenshots and record video
• Install dependencies via CocoaPods or Swift Package Manager
• Run Expo and React Native projects with hot reload

iOS Simulator

The iOS Simulator is auto-configured when you include a simulators section in the manifest. wallfacer-agent boots the simulator, starts SimulatorCapture for browser-based streaming, and registers an MCP server so Claude Code can interact with the simulator directly (screenshots, taps, swipes, text input).

The simulator and its build/run commands execute asynchronously after the VM is declared ready, so they do not block session start.

Docker is not available on macOS VMs.

Tools the Agent Is Offered

An agent is offered only the controls its own computer can run, so it does not reach for something that was never going to work on that platform.

• Browser control (open a page, read it, click, fill, screenshot it, read its DOM) comes with Linux, where headless Chromium is part of the base image. It is not offered on macOS.
• iOS simulator control (screenshot, tap, swipe, type, press a button, open a URL, list or terminate apps) is offered only when the environment's manifest declares a simulators section, which needs the macOS platform. An environment without one, on either platform, is not offered the simulator controls.

Everything else, the shell, the files, search, and the platform's own tools, is offered on both platforms. Adding a simulators section to a macOS environment is what turns the simulator controls on for the sessions that boot from it; there is no separate setting.

Choosing a Platform

Use Linux unless you need Xcode or the iOS Simulator. Linux VMs boot faster, restore from snapshots more quickly, and have lower resource overhead. macOS VMs exist specifically for Apple platform development.

Set the platform in your environment configuration (via the app or API) or directly in the manifest's platform.os field.

Platform Comparison

Pre-Installed Tool Versions

Base images are updated periodically. Tool versions reflect the latest base image build. wallfacer-agent and agent-api are updated independently via rollouts.