Environments

An environment is the blueprint for a development machine. It tells Wallfacer how to set up a VM for your repo: what to clone, what to install, and what services to run. Every coding session boots from an environment.

What Is an Environment

An environment defines:

Which repo to clone
Which platform to run on (Linux or macOS)
Who can see and use it within the account
An AES manifest that declares setup commands, services, health checks, and more

When you start a task, Wallfacer reads the environment config, boots a VM, and runs the manifest. The result is a fully configured machine with your repo cloned, dependencies installed, and services running.

Creating an Environment

Environments appear as Computers in the app's navigation.

From onboarding

Once your account's agent is connected to GitHub, the app shows a repo picker. Select one or more repos, then choose Create. Wallfacer generates a default manifest based on the repos you picked.

From the Computers page

Open Computers and start a new one:

Web: New Computer, in the page header.
iPad and Android: New Computer, above the list.
iPhone: the + button at the trailing end of the bottom toolbar, alongside the search field and the filter menu.

Either entry point opens Build a computer, which specs the machine section by section:

Chassis. The platform the computer runs on, Linux or macOS.
Specs. The memory and processing power the chassis provisions. Each chassis provisions one size today, so this states the machine rather than offering a choice.
Repositories. The repos to check out. This needs the agent's GitHub connected. Without it you can still build a blank computer and add repositories later.
Services. Long-running processes to start when the computer boots, such as a dev server or a database. Add service appends a row with a name and a command, and the trash button at the end of a row removes that row.
Setup steps. One-time commands that run while the computer is built, such as installing dependencies or running migrations. Same row controls, under Add setup step.
Name. What the computer is called. Leave it blank to name it after its repositories.

Your configuration at the bottom lists what you picked, with Build computer underneath it. On an iPhone the submit sits in the bottom toolbar instead and reads Create, then Creating… while the computer is being created. Either way Wallfacer creates the computer and opens its Logs tab, where the build runs.

Backing out of a part-filled form on iOS or Android asks Discard this computer? first, because nothing is created until you submit. Keep editing returns to the form, Discard leaves and loses the configuration. On web, the back link leaves without a prompt.

Environment Settings

Name and description

A human-readable label. Use something that identifies the repo and purpose, like "api-backend" or "ios-app".

Git repository

The source repo in owner/repo, host-qualified, or full URL format.

Platform

linux/amd64: Default for most projects. General-purpose Linux VM.
darwin/arm64: For iOS and macOS development. Gives you Xcode, iOS Simulator, and Apple's ARM toolchain.

Visibility

New environments default to private.

private: Only you can see, use, or change it.
account_read: Account members can see and use it, but only you can edit or delete it.
account_edit: Account members can see, use, edit, and delete it.

The Manifest

The AES (Agent Environment Spec) manifest is the heart of the environment. It's a YAML or JSON file that declares everything the VM needs.

Sources

Git repos to clone, with workspace paths and branch targets:

sources:
  - repo: github.com/your-org/your-repo
    workspace: /workspace/your-repo
    branch: main

Setup commands

Commands that run sequentially after clone. These handle dependency installation and build steps:

setup:
  - name: install-deps
    run: npm install
    working_dir: /workspace/your-repo
  - name: build
    run: npm run build
    working_dir: /workspace/your-repo

Services

Background processes with health checks and port declarations:

services:
  - name: dev-server
    run: npm run dev
    working_dir: /workspace/your-repo
    ports:
      - port: 3000
        name: web
        protocol: http
    healthcheck:
      url: http://localhost:3000
      interval: 5s

Mounts

S3 buckets you own, attached to the VM's filesystem so the files an agent writes outlive the machine. Linux only, up to four, with credentials referenced from the environment's secrets:

mounts:
  - at: /mnt/artifacts
    bucket: acme-agent-artifacts
    region: us-east-1
    credentials:
      access_key_id: ${secrets.S3_ACCESS_KEY_ID}
      secret_access_key: ${secrets.S3_SECRET_ACCESS_KEY}

See Mounted S3 Storage for mountpoint rules and what happens to in-flight uploads when the VM is destroyed.

Agent config

Claude Code instructions files and the MCP servers available to the agent. Instruction files are loaded into Claude's context at the start of a turn; MCP tool definitions are loaded on demand, so a long list of connected tools does not consume the context window before the work starts.

agent:
  instructions:
    - CLAUDE.md

MCP servers are not part of the manifest. They belong to the environment itself; see MCP Servers below.

See the Manifest Reference for the full schema and all available options.

MCP Servers

The MCP Servers section of the environment lists the servers your agents can call during a session on it. Each server has a name, which becomes the namespace its tools appear under, and one of three shapes:

Remote. A hosted https MCP endpoint the session calls directly. Add the headers it needs, such as Authorization. Header values can reference the environment's secrets as ${secrets.NAME}, so the token stays in the secret store.
Remote, signed in with OAuth. The same hosted endpoint, where the provider runs its own sign-in instead of you pasting a token. Declare the server and the scopes you want, then sign in once. Wallfacer holds the resulting grant encrypted, renews it in the background, and attaches it to each call the agent makes. The sign-in is never copied onto the machine the agent works on, so revoking it at the provider takes it away everywhere at once. Start the sign-in through the API: see Environments and Secrets.
Sandbox. A command Wallfacer runs inside the session VM over stdio, next to your code and tools. Give it a command, its arguments, and any environment variables it needs; env values can reference ${secrets.NAME} too.

sandbox, simulator, comms, and submit_result are reserved names -- the platform provides servers of its own under them.

Because MCP servers sit outside the manifest, changing them takes effect on the next session and never regenerates the environment's snapshot.

Snapshots

What they are

A snapshot is a saved VM image taken after the full manifest lifecycle completes: clone, setup, services, and health checks all pass. It captures the exact state of a fully configured machine.

Restoring from a snapshot boots significantly faster than a fresh VM.

Status indicators

Snapshot status is visible on the environment card and detail page, and it updates live as the snapshot builds -- you see a build move to ready or fail without refreshing:

Green: Ready. Sessions will boot from this snapshot.
Orange: Generating. A VM is running the manifest lifecycle to create the snapshot.
Red: Failed. The manifest lifecycle didn't complete. Check your setup commands and service health checks.

When they regenerate

Automatically when you change the manifest.
Automatically to stay fresh. Wallfacer periodically rebuilds a snapshot that has aged so it keeps reflecting a recent build. The rebuild runs in the background and the fresh snapshot is swapped in only once it's ready, so your sessions keep starting fast in the meantime.
Automatically to recover. If a snapshot can't be restored, Wallfacer boots the session from a fresh build and rebuilds the snapshot in the background, instead of failing the session. You may notice one slower start while this happens.
Manually via the Regenerate Snapshot button on the environment detail page.

Why they matter

Without a snapshot, every session boots fresh. That means cloning, installing dependencies, and starting services from scratch. With a snapshot, the VM restores to a fully configured state much faster.

This is what makes it practical to check in from your phone, fire off a quick coding task, and move on.

Deleting an Environment

Deleting an environment removes the configuration and its snapshot. It does not destroy any running VMs that were created from it. Active sessions continue until they're closed or time out.