Workspace Architecture

AgentV evaluations that use workspace.repos clone repositories directly from their source (git URL or local path) into a workspace directory. Workspace pooling (enabled by default) eliminates repeated clone costs by reusing materialized workspaces across runs.

Eval setup lifecycle

Each evaluation run proceeds through these phases:

eval start
  |
  v
+---------------------------+
| 1. Pool / workspace setup |  Acquire pool slot or create temp workspace
+---------------------------+
  |
  v
+---------------------------+
| 2. Template copy          |  workspace.template dir -> workspace/
+---------------------------+
  |
  v
+---------------------------+
| 3. Repo materialization   |  For each workspace.repos entry:
|    a. git clone (source)  |    - clone directly from source URL or local path
|    b. git checkout <ref>  |    - check out the specified ref
+---------------------------+
  |
  v
+---------------------------+
| 4. before_all hook        |  workspace.before_all script executes
+---------------------------+
  |
  v
+---------------------------+
| 5. Test loop              |  For each test case:
|    before_each -> run ->  |    agent executes -> capture changes -> after_each
+---------------------------+
  |
  v
+---------------------------+
| 6. after_all / cleanup    |  workspace.after_all -> workspace cleanup
+---------------------------+

With workspace pooling (the default), steps 2-3 only happen on the first run. Subsequent runs reset the pool slot in-place, skipping clone and checkout entirely.

Windows performance guidance

Drive choice affects checkout time

On Windows, the drive type materially affects file-write throughput during checkout:

Drive type	Example path	Checkout time (large repo)	Notes
Standard NTFS (C:)	C:\Users\<user>\.agentv	~184s	Normal Defender/AV interception
Dev Drive (D:)	D:\Users\<user>\.agentv	~119s	~35% faster, lower AV overhead

Windows Dev Drive uses the Resilient File System (ReFS) with a performance mode that reduces antivirus filter overhead for developer workloads. If you evaluate large repos frequently, relocating ~/.agentv to a Dev Drive volume can meaningfully reduce per-run setup time.

To relocate the agentv home directory, set HOME or USERPROFILE to point to the Dev Drive path before running agentv eval:

$env:USERPROFILE = "D:\Users\$env:USERNAME"
agentv eval evals/my-eval.yaml

Long-path support for relocated home directories

When HOME or USERPROFILE is redirected to another drive, the Git global config (~/.gitconfig) also moves. If core.longpaths=true is not set in the new profile location, git checkout can fail with:

error: unable to create file <path>: Filename too long

Set it globally in the redirected home:

git config --global core.longpaths true

Or add it to the repo-level config after clone (this runs automatically if your before_all script includes it):

git config core.longpaths true

Troubleshooting: eval appears stuck at startup

When evaluating large repos, the eval run may appear to hang before the agent starts. This is typically the checkout phase materializing files on the first run.

Enable verbose logging

agentv eval evals/my-eval.yaml --verbose

Verbose mode logs each setup phase with timestamps. Look for:

[workspace] Creating shared workspace...
[workspace] Materializing repo ./repo...
[workspace] Checkout complete (182000ms)
[workspace] Running before_all script...
[workspace] Setup complete, starting test loop

If the log stalls at checkout for minutes, the working-tree write is the bottleneck — not a hang. With pooling enabled, this only happens on the first run.

Common causes and fixes

Symptom	Likely cause	Fix
Stuck at checkout for 2+ minutes	Large repo file materialization (first run)	Expected for 100k+ files; use Dev Drive on Windows. Subsequent runs use pool.
Filename too long during checkout	Missing core.longpaths	git config --global core.longpaths true
Slow every run despite pooling	Pool not matching (config drift)	Check with agentv workspace list; ensure workspace config is stable
Before_all timeout	Setup script exceeds default 60s	Increase timeout_ms in workspace config

Workspace pooling

Workspace pooling is enabled by default for shared workspaces with repos. The first run materializes from scratch. Subsequent runs reset the existing workspace in-place (git reset --hard + git clean -fd) — typically reducing setup from minutes to seconds.

To disable pooling for a run:

agentv eval evals/my-eval.yaml --no-pool

See the Workspace Pool guide for details on pool configuration, clean modes, concurrency, and drift detection.