Work with agents / Local workspaces
Put workspaces on a copy-on-write disk
Your disk has no copy-on-write, so each new workspace is a full copy of your files, which is slow and fills your disk. src ws init can make a disk image with copy-on-write and put your workspaces on it, so each new workspace is a clone again.
5 min read
This happens on Windows with NTFS, on Linux with ext4, and on a Mac disk that is not APFS. You make the image once for each computer.
Note
While the pool of ready workspaces is on, which is the default, you do not need the image. src ws create takes a ready workspace, and on Windows it was no faster on a Dev Drive than on NTFS. So src ws init offers no image then, and says that src ws init --yes creates one. To get the question, turn the pool off with src ws init --spares 0.
You need:
- On Windows: Windows 11 24H2 or later (build 26100). Older builds make no block clones in copies.
- On Linux:
mkfs.btrfsormkfs.xfs. If you have neither, installbtrfs-progs.
If Windows is older, or Linux has neither tool, src stops before it changes anything.
1. Run init in a terminal
src ws init
srclists the drives of your computer, with the free space of each drive and whether its file system has copy-on-write. Pick the drive for your workspaces.srcmakes a real clone test on that drive. If the test works, you are done.- If the test fails and the pool is off,
srctells you what it will create, and asks you first:
This disk has no copy-on-write. I will create a growing CoW disk image at C:\Users\you\.src-ws-disk\workspaces.vhdx and mount it at C:\Users\you\.src-ws-disk\mount. This needs admin rights once.
- Create a dynamic VHDX at C:\Users\you\.src-ws-disk\workspaces.vhdx. It starts small and grows up to 100 GiB.
- Format it as a Dev Drive (ReFS), where Windows makes each copy a block clone.
- Mount it at C:\Users\you\.src-ws-disk\mount, and give you full rights on its .src-ws folder.
- Add the scheduled task "TanStack Source ws disk", which attaches the image again when you log on.
- src runs these steps as admin, with one UAC prompt. It writes no script file.
Create the disk image? (default: no) [y/n]
2. Say yes
Type y. src creates the image, tests a clone on it again, and moves the workspaces of the repository there.
What src creates depends on your OS:
| OS | What src creates | Admin rights |
|---|---|---|
| Windows 11 24H2 or later | A dynamic VHDX formatted as a Dev Drive (ReFS), and a scheduled task that attaches it when you log on. | One UAC prompt |
| Linux | A sparse file formatted as btrfs, or as XFS with reflinks when only mkfs.xfs is there. A line in /etc/fstab (loop,nofail) mounts it after a restart. | One sudo password |
| macOS, on a disk that is not APFS | An APFS sparse image, made with hdiutil, and a LaunchAgent that attaches it when you log in. | None |
Note
The tests of src check each plan: the scripts and commands, their order, the sizes, the quotes around paths, and the question. The tests never run the admin steps. Those steps run only on your computer, after you say yes.
Done
Your workspaces are on a disk with copy-on-write, and each new workspace is a clone that uses almost no disk space.
Where the files go
- The image goes in
~/.src-ws-diskwhen your home folder is on the chosen drive. Else it goes in<drive>/.src-ws-disk. - The image is mounted at
~/.src-ws-disk/mount. The workspaces go in~/.src-ws-disk/mount/.src-ws/<repository folder>. srcwrites no setup script to disk. It gives the admin steps to PowerShell orsudoon the command line, so no other program can change them before they run.- The Windows logon task runs one command, which attaches the image. The command is in the task itself, not in a file.
- Your checkpoints stay in the data folder of
src, outside the image.
When you run src ws init --yes in another repository on the same drive, src finds the attached image and uses it. It asks for no admin rights again.
To change the size, add --image-size <GiB>. The default is 100. A Dev Drive needs 50 GB, so on Windows the smallest size is 50.
pnpm on the image
pnpm links its packages from its store, but only from a store on the same volume. Your global store is on another disk. So on the image, src gives pnpm a store of its own: the pnpm-store folder in the .caches folder of the repository. It sets the store through npm_config_store_dir for pnpm 10 and pnpm_config_store_dir for pnpm 11. The first workspace fills the store, and the next workspaces link from it.
Choose plain copies
If you answer no, src creates nothing and records that you chose plain copies. You can also choose them on purpose:
src ws init --plain-copy
src ws list then says that new workspaces are plain copies. To change your choice, run src ws init again.
Run init in a script
A script has no terminal, so src ws init asks nothing there:
- Without
--yes, it creates nothing. With the pool off, it says how to set up an image. - With
--yes, it prints what it will do, then creates the image on the drive of the repository. - With
--drive <folder>, it uses the drive of that folder. The workspaces go in<folder>/.src-ws/<repository folder>.
src ws init --yes --drive D:\ --image-size 200
See the status
src ws init --storage-status
Workspaces of app go in C:\Users\you\.src-ws-disk\mount\.src-ws\app
Copy-on-write: yes (the volume is ReFS on Windows build 26100, where each copy is a block clone)
Disk image: C:\Users\you\.src-ws-disk\workspaces.vhdx (Dev Drive VHDX, grows up to 100 GiB)
Size used: 4.20 GiB
Mounted at: C:\Users\you\.src-ws-disk\mount (attached)
It also prints the steps to remove the image. src ws init prints the lines of the image too, when your workspaces are on one.
After a restart
The task, the fstab line or the LaunchAgent attaches the image again. If the image is not attached, each src ws command stops and prints one command that attaches it:
| OS | Command |
|---|---|
| Windows | schtasks /Run /TN "TanStack Source ws disk" |
| Linux | sudo mount ~/.src-ws-disk/mount |
| macOS | hdiutil attach <image> -mountpoint ~/.src-ws-disk/mount -nobrowse |
Remove the image
- Close each workspace on the image:
src ws close <name>. - Run
src ws init --spares 0, thensrc ws prepare. This deletes the ready workspaces on the image. - Run
src ws init --storage-status, and do the remove steps that it prints. On Windows, run them in PowerShell as admin. - Run
src ws init --drive <folder> --spares 2to put the workspaces on another drive, with a pool of 2 again.