---
title: Workspace Architecture
description: How AgentV clones and materializes working trees for eval runs, with performance guidance for large repos.
sidebar:
  order: 7
---

AgentV evaluations that use `workspace.repos` clone repositories directly from their source (git URL or local path) into a workspace directory. [Workspace pooling](/docs/guides/workspace-pool/) (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](https://learn.microsoft.com/en-us/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`:

```powershell
$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:

```bash
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):

```bash
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

```bash
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:

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

See the [Workspace Pool](/docs/guides/workspace-pool/) guide for details on pool configuration, clean modes, concurrency, and drift detection.
