Configuration

Wallfacer is configured through the Settings UI, environment variables in ~/.wallfacer/.env, CLI flags, and file-based overrides for system prompts and workspace instructions. The .env file is auto-generated on first run with commented-out defaults; edit it directly or use the Settings UI. Most settings take effect on the next task run without restarting the server.

🚀 Essentials

Opening Settings

Open the Settings modal by clicking the gear icon in the top-right corner of the task board. The modal contains six tabs: Appearance, Execution, Sandbox, Workspace, Trash, and About.

🎨 Appearance

Theme -- Choose between Light, Dark, or Auto (follows the operating system preference). The theme applies to the current browser session.

Done Column -- Toggle "Show archived tasks" to display or hide archived completed tasks on the board.

🔑 Setting Up Sandbox Credentials

At minimum, you need one of these credentials configured in Settings > Sandbox:

Claude configuration:

• Sign in with Claude button -- starts an OAuth flow: opens your browser to authenticate, then stores the token automatically. This is the easiest way to set up credentials.
• OAuth Token (CLAUDE_CODE_OAUTH_TOKEN) -- alternatively, paste a token from claude setup-token; takes precedence when both credentials are set
• API Key (ANTHROPIC_API_KEY) -- direct key from console.anthropic.com
• Test button -- runs a quick sandbox connectivity check to verify your credentials work. If the test detects an invalid or expired token and OAuth is available, a Sign in again button appears inline.

Codex configuration: similarly, use the Sign in with OpenAI button for OAuth or paste an API key manually.

The sign-in buttons are hidden when a custom base URL is configured (custom endpoints don't use standard OAuth). On first launch with no credentials for any provider, a prompt guides you to set up credentials.

All changes are written to ~/.wallfacer/.env and take effect on the next task run. Leave token fields blank to preserve the existing value.

Container Images

The Container Images section at the top of Settings > Sandbox shows whether each sandbox image (Claude and Codex) is cached locally. Images are pulled automatically on first task run, but you can also manage them manually:

• Pull -- Download a missing image from the registry (~1 GB).
• Re-pull -- Update a cached image to the latest version.
• Pull progress streams live in the settings panel with a phase summary (resolving, downloading layers, writing manifest) and a layer counter.

You can also check image status from the command line with wallfacer doctor.

Key Environment Variables

All configuration lives in ~/.wallfacer/.env (auto-generated on first run). The server re-reads this file before each container launch, so changes take effect on the next task without a server restart.

CLI Basics

wallfacer run                           # Start server, restore last workspace group
wallfacer run -addr :9090 -no-browser   # Custom port, no browser
wallfacer status                        # Print board state to terminal
wallfacer status -watch                 # Live-updating board state
wallfacer doctor                        # Check prerequisites and config

📐 Spec Mode

See Designing Specs for the full spec mode guide.

💬 Planning Chat

See Exploring Ideas for the full planning chat guide.

⌨️ Keyboard Shortcuts

🔧 Advanced Topics

⚡ Execution Settings

Parallel Tasks -- Set the maximum number of tasks that run concurrently in the In Progress column (1--20). Corresponds to WALLFACER_MAX_PARALLEL.

Archived Tasks -- Number of archived task items to load per scroll page (1--200). Corresponds to WALLFACER_ARCHIVED_TASKS_PER_PAGE.

Oversight Interval -- Minutes between periodic oversight summary generation while a task is running (0--120). Setting this to 0 means oversight is only generated when the task reaches a terminal state. Corresponds to WALLFACER_OVERSIGHT_INTERVAL.

Auto Push -- Enable automatic git push after a task's commit pipeline completes. When enabled, an additional threshold field appears: push only triggers when the workspace is at least N commits ahead of upstream. Corresponds to WALLFACER_AUTO_PUSH and WALLFACER_AUTO_PUSH_THRESHOLD.

Brainstorm -- Enable the brainstorm (ideation) agent and set its recurrence interval. Options range from "immediately" to "every 24h". The brainstorm agent analyses repositories and proposes tasks tagged idea-agent. A "Run now" button triggers an immediate brainstorm.

Task Titles -- Select a batch limit (5, 10, 25, 50, or All) and click "Generate Missing" to auto-generate titles for untitled tasks using a lightweight model call.

Trace Oversight -- Select a batch limit and click "Generate Missing" to generate oversight summaries for tasks that lack them.

Codex Sandbox Configuration

Codex configuration:

• API Key (OPENAI_API_KEY) -- optional when host ~/.codex/auth.json is available
• Base URL (OPENAI_BASE_URL) -- optional custom OpenAI-compatible endpoint
• Default Model (CODEX_DEFAULT_MODEL) -- model for Codex tasks
• Title Model (CODEX_TITLE_MODEL) -- falls back to the Codex default model
• Test button -- runs a Codex connectivity check

📦 Sandbox Routing

Global Sandbox Routing -- Select the default sandbox type and override the sandbox for individual activities: Implementation, Testing, Refinement, Title generation, Oversight summary, Commit message, and Idea agent. Each dropdown offers the available sandbox types (claude, codex) or "default".

Wallfacer supports two sandbox types:

• Claude -- runs Claude Code CLI inside an Ubuntu-based container (wallfacer:latest). Requires either CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY.
• Codex -- runs OpenAI Codex CLI inside a companion image (wallfacer-codex:latest). Requires OPENAI_API_KEY or host ~/.codex/auth.json.

Each task can be assigned a specific sandbox type when created or edited. The task-level sandbox selection overrides the global default for that task's implementation run.

Different agent activities can be routed to different sandbox types. For example, you could run implementation tasks on Claude but use Codex for title generation. Configure this in Settings > Sandbox > Global Sandbox Routing or via the WALLFACER_SANDBOX_* environment variables.

The seven configurable activities are:

1. Implementation -- the main task execution
2. Testing -- test verification agent
3. Refinement -- prompt refinement agent
4. Title generation -- automatic task title generation
5. Oversight summary -- trace oversight analysis
6. Commit message -- commit message generation
7. Idea agent -- brainstorm/ideation agent

When an activity-specific override is not set, it falls back to WALLFACER_DEFAULT_SANDBOX. When that is also unset, the sandbox is determined by the task's own sandbox field or the server default (Claude).

Route specific agent activities to different sandbox types (claude or codex):

🖥️ Container Resource Limits

Limit the CPU and memory available to each task container via WALLFACER_CONTAINER_CPUS and WALLFACER_CONTAINER_MEMORY. These correspond to the --cpus and --memory flags of podman run / docker run. Leave empty for no limit.

• Container CPUs (WALLFACER_CONTAINER_CPUS) -- e.g. 2.0; leave empty for no limit
• Container Memory (WALLFACER_CONTAINER_MEMORY) -- e.g. 4g; leave empty for no limit

Fast Mode

When WALLFACER_SANDBOX_FAST is true (the default), Wallfacer passes fast-mode hints to the sandbox agent. Set to false to disable.

Enable /fast -- Toggle fast-mode sandbox hints (WALLFACER_SANDBOX_FAST).

📋 Full Environment Variables Reference

All configuration lives in ~/.wallfacer/.env (auto-generated on first run). The server re-reads this file before each container launch, so changes take effect on the next task without a server restart.

Authentication

Models

OpenAI Codex

* If host auth cache is unavailable, OPENAI_API_KEY plus a successful Test (Codex) is required.

Concurrency

Container

Automation

Data & Pagination

Security

📝 System Prompt Templates

Wallfacer uses eight built-in Go template files to instruct agent activities:

Viewing and Editing

Open Settings > Workspace > System Prompt Templates > Manage to view all templates. Each template shows whether a user override exists. Click a template name to view its content and edit it.

Overrides are validated as Go templates before saving. If the template is invalid, the save is rejected with a parse error message.

Override Storage

User overrides are stored as .tmpl files in ~/.wallfacer/prompts/. For example, overriding the title template creates ~/.wallfacer/prompts/title.tmpl.

Restoring Defaults

Delete a user override via the template editor or the API (DELETE /api/system-prompts/{name}) to restore the embedded default.

Workspace Instructions (AGENTS.md)

What AGENTS.md Is

Each unique set of workspaces gets its own AGENTS.md file stored in ~/.wallfacer/instructions/. This file is mounted read-only into every task container at /workspace/AGENTS.md, where the agent picks it up automatically as context.

How Fingerprinting Works

The instructions file is identified by a SHA-256 hash of the sorted, absolute workspace paths. This means switching to workspaces ~/a and ~/b (in any order) shares the same instructions file, while ~/a, ~/b, and ~/c together gets a separate one.

Initial Generation

On first run with a new workspace set, Wallfacer creates the AGENTS.md from:

1. A built-in default template with general agent guidance.
2. A reference list of per-repository AGENTS.md (or legacy CLAUDE.md) file paths so agents can read them on demand.

Editing

Open Settings > Workspace > AGENTS.md > Edit to modify the instructions in the web UI. Changes are saved to the fingerprinted file in ~/.wallfacer/instructions/.

Re-Initializing

Click Re-init (or call POST /api/instructions/reinit) to regenerate the instructions from the default template and current repository files, discarding any manual edits.

Prompt Templates

Prompt templates are reusable named prompt fragments for common task patterns.

Creating a Template

Open Settings > Workspace > Prompt Templates > Manage. Enter a name and body, then save. Templates are stored in ~/.wallfacer/templates.json.

Using Templates

When creating a new task, select a template from the template picker to insert its body into the prompt field. You can then edit the inserted text before submitting.

Managing Templates

From the template manager, you can view all templates sorted by creation date and delete templates you no longer need.

🖥️ CLI Reference

wallfacer run

Start the task board server and open the web UI.

wallfacer run [flags] [workspace...]

Positional arguments:

• workspace -- directories to mount in the sandbox (default: current directory)

Flags:

Container runtime auto-detection order: /opt/podman/bin/podman, then podman on $PATH, then docker on $PATH.

wallfacer status

Print the current board state to the terminal.

wallfacer status [flags]

Examples:

wallfacer status                  # Snapshot of current state
wallfacer status -watch           # Live-updating view
wallfacer status -json            # Machine-readable JSON output
wallfacer status -addr :9090      # Connect to a different server

wallfacer doctor

Check prerequisites and configuration. Displays config paths, then verifies credentials, container runtime (including responsiveness), sandbox images, and Git.

wallfacer doctor

Output uses [ok] for passing checks, [!] for issues that need fixing, and [ ] for optional items that are not configured. Credential values are masked.

wallfacer exec

Attach an interactive shell to a running task container, or open a shell in a new sandbox container.

wallfacer exec <task-id-prefix> [-- command...]
wallfacer exec --sandbox <claude|codex> [-- command...]

• <task-id-prefix> -- the first 8 or more hex characters of the task UUID (shown on task cards)
• --sandbox -- open a fresh sandbox container with the current directory mounted, without attaching to an existing task
• command -- command to run inside the container (default: bash; falls back to sh if bash is unavailable)

Examples:

wallfacer exec a1b2c3d4              # Attach to running task container
wallfacer exec a1b2c3d4 -- sh       # Use sh instead of bash
wallfacer exec --sandbox claude      # Open shell in a new Claude sandbox
wallfacer exec --sandbox codex       # Open shell in a new Codex sandbox

🛡️ Security

Server API Key Authentication

Set WALLFACER_SERVER_API_KEY to require bearer-token authentication on all API requests. When configured, every request must include the header:

Authorization: Bearer <your-api-key>

SSE (Server-Sent Events) endpoints accept the token as a ?token= query parameter instead, since EventSource does not support custom headers.

The root page (GET /) is exempt from authentication to allow loading the UI, which then uses the token for subsequent API calls.

CSRF Protection

Wallfacer validates the Origin or Referer header on all state-changing requests (POST, PUT, PATCH, DELETE). The header host must match the server's listen address. Requests without either header (e.g., from non-browser clients like curl) are allowed through.

SSRF Hardening

Custom API base URLs (ANTHROPIC_BASE_URL, OPENAI_BASE_URL) are validated before being persisted:

• Only HTTPS URLs are accepted
• Bare IP addresses are rejected
• Single-label hostnames (e.g., localhost) are rejected
• Hostnames that resolve to private, loopback, or link-local IP addresses are rejected

Request Body Size Limits

Request bodies are limited to prevent abuse:

🗑️ Trash Management

View soft-deleted tasks that are within the retention window (default: 7 days, controlled by WALLFACER_TOMBSTONE_RETENTION_DAYS). Each entry shows the task prompt and deletion timestamp. You can:

• Restore a task to return it to its pre-deletion state
• Wait for the retention window to expire for automatic permanent removal

Access via Settings > Trash.

About

Displays version information, the project link (github.com/changkun/wallfacer), and license details.

Access via Settings > About.

📂 Workspace Settings

Active Workspaces -- Lists the directories currently mounted into task containers. Click Change to open the workspace picker and select different directories.

Saved Workspace Groups -- Previously used workspace combinations are saved automatically. Switch back to any saved group without rebuilding the folder set.

See Also

• Getting Started -- initial setup and first task
• Usage Guide -- task creation, feedback, autopilot, and results
• Circuit Breakers -- container launch failure protection
• Refinement & Ideation -- prompt refinement and brainstorm agents
• Architecture -- system design for contributors