Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion fork-kit/common/machine.example.json
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@
},
"pc-agents": {
"organization": "Example home lab",
"t3Version": "0.0.30",
"t3Version": "0.1.9",
"t3ReleaseBaseUrl": "https://github.com/example/t3code/releases/download",
"port": 3773,
"maxRuntimeMode": "full-access",
Expand Down
2 changes: 1 addition & 1 deletion fork-kit/desk/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -115,7 +115,7 @@ distro (`-Distro`, default `fork-desk`, Ubuntu 24.04, installed with `--version
leaves a mark in `%LOCALAPPDATA%\fork-desk`, so the next run asks no takeover question, and a broken one names
`wsl --unregister DISTRO`); `.wslconfig`'s `[wsl2]` memory cap (`-MemoryGB`, default
three quarters of the RAM, at most the RAM less 6 GB, never under 4 GB; one that leaves Windows under 2 GB is
refused), swap (`-SwapGB`, 4), NAT and DNS tunnelling, for every WSL distro (read and written as UTF-8 without a
refused; it is the least cap: a higher one already there, raised by hand, is kept), swap (`-SwapGB`, 4), NAT and DNS tunnelling, for every WSL distro (read and written as UTF-8 without a
BOM; a dated copy of the old file is kept, other keys and sections stay; an old `networkingMode` or `dnsTunneling`
line under `[experimental]`, the form before WSL 2.0 that can still win over `[wsl2]`, is removed, and the check
FAILs while one is there; the question lists each change, old -> new, and the file is written only when it lists one,
Expand Down
41 changes: 41 additions & 0 deletions fork-kit/desk/tests/windows.test.py
Original file line number Diff line number Diff line change
Expand Up @@ -362,6 +362,47 @@ def test_wslconfig_merge_removes_old_experimental_networking_keys(self):
'[experimental] dnsTunneling=false: removed', 'changed=True', 'left=sparseVhd', 'after=0'):
self.assertIn(line, r.stdout)

@unittest.skipUnless(shutil.which('pwsh'), 'pwsh is not installed')
def test_a_memory_cap_at_or_above_the_minimum_is_kept(self):
"""-MemoryGB is the least cap: one a person raised (more agents or jobs in WSL) is neither lowered nor a FAIL,
nor a `wsl --shutdown` on every run (the live check's cap is the one kept)."""
d = tempfile.mkdtemp(prefix='desk-wslconfig-test-')
self.addCleanup(shutil.rmtree, d, True)
path = os.path.join(d, '.wslconfig')
script = os.path.join(d, 'memory.ps1')
with open(script, 'w', encoding='ascii') as f:
f.write(wslconfig_part() + '\n$want = [ordered]@{ memory = (WantMemory $args[0] 8); swap = "4GB" }\n'
'"want=$($want.memory) kb=$(CapKb $want.memory)"\n'
'"notes=$(@(Changes (Read-WslConfig $args[0]) $want) -join \'|\')"\n'
'$null = Merge-WslConfig $args[0] $want\n$cfg = Wsl2Keys (Read-WslConfig $args[0])\n'
'"check=$(@($want.Keys | Where-Object { $cfg[$_] -ne $want[$_] }).Count)"\n')
for old, want, kb, note in (('memory=26GB', '26GB', 27262976, ''), # raised: kept, no change, no FAIL
('memory = 30720mb', '30720mb', 31457280, ''),
('memory=8GB', '8GB', 8388608, ''),
('memory=9G', '9G', 9437184, ''),
('memory=4GB', '8GB', 8388608, '[wsl2] memory: 4GB -> 8GB'), # below: raised
('memory=8191MB', '8GB', 8388608, '[wsl2] memory: 8191MB -> 8GB'),
('memory=lots', '8GB', 8388608, '[wsl2] memory: lots -> 8GB'),
('', '8GB', 8388608, '[wsl2] memory: (not set) -> 8GB')):
with self.subTest(old):
with open(path, 'w', encoding='utf-8', newline='\n') as f:
f.write(f'[wsl2]\n{old}\nswap=4GB\n')
r = subprocess.run(['pwsh', '-NoProfile', '-NonInteractive', '-File', script, path],
capture_output=True, text=True, timeout=120, stdin=subprocess.DEVNULL)
self.assertEqual(r.returncode, 0, r.stdout + r.stderr)
self.assertIn(f'want={want} kb={kb}\n', r.stdout)
self.assertIn(f'notes={note and " " + note}\n', r.stdout) # a note is indented
self.assertIn('check=0\n', r.stdout)
if not note:
self.assertEqual(slurp(path), f'[wsl2]\n{old}\nswap=4GB\n') # left alone

def test_the_minimum_memory_cap_decides_through_wantmemory(self):
src = text().decode('ascii')
body = src[src.index('try {'):]
self.assertIn('$want = [ordered]@{ memory = (WantMemory $WslConfig $MemoryGB);', body)
self.assertIn('("WANT_KB=$(CapKb $want.memory)`n" + $Live)', body) # the cap kept, not -MemoryGB
self.assertNotIn('$MemoryGB * 1048576', body)

def test_wslconfig_is_utf8_without_a_bom_never_ascii(self):
src = text().decode('ascii')
self.assertNotRegex(src, r'(?i)-Encoding\s+ascii')
Expand Down
17 changes: 15 additions & 2 deletions fork-kit/desk/windows/start-desk.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@
# (fork-kit/desk/README.md, "Windows"). Run it in a normal Windows PowerShell window (not as administrator):
# powershell -ExecutionPolicy Bypass -File start-desk.ps1 -Repo OWNER/REPO -Sha RELEASE_SHA -MachineFile machine.json
# [-FleetConfig fork-fleet.json] [-Distro fork-desk] [-MemoryGB N] [-SwapGB 4] [-Uninstall]
# -MemoryGB is the least [wsl2] memory cap: a higher one already in .wslconfig is kept.
# It prints this PC's facts and asks before it changes anything. Safe to run again: every step checks what is there.
# Steps: the distro (Ubuntu 24.04); .wslconfig's [wsl2] memory cap and NAT (a dated copy of the old file is kept;
# other keys stay); the distro's own settings (the WSL walls: no interop, no Windows PATH or drives, its own
Expand Down Expand Up @@ -161,6 +162,18 @@ function Merge-WslConfig([string]$path, $want, [scriptblock]$before = {}) { #
Move-Item -LiteralPath "$path.new" $path -Force
$true
}
# A [wsl2] memory= value in kB (8GB, 8192MB, 8G; no unit: bytes), or -1 when it is not a size
function CapKb([string]$v) {
if ($v -notmatch '^\s*([0-9]{1,13})\s*([KMGT]?)B?\s*$') { return [long]-1 }
[long][math]::Min(1e15, [math]::Floor([double]$Matches[1] * [math]::Pow(1024, ' KMGT'.IndexOf($Matches[2].ToUpper())) / 1024))
}
# The memory cap to want: at least $gb GB. A higher one already in .wslconfig (a person raised it) is kept as it is
# written, so it is neither lowered nor a FAIL, and the live check holds WSL to it.
function WantMemory([string]$path, [int]$gb) {
$have = (Wsl2Keys (Read-WslConfig $path))['memory']
if ($have -and (CapKb $have) -ge [long]$gb * 1048576) { return $have }
"${gb}GB"
}
function WslVersion([string[]]$lines, [string]$name) { # the WSL version of one distro in `wsl -l -v`; 0: not there
foreach ($l in $lines) {
$f = @(($l.Trim([char]0, ' ', '*', "`t") -replace [char]0, '') -split '\s+')
Expand Down Expand Up @@ -211,7 +224,7 @@ try {
$ours = Test-Path -LiteralPath $Made
if ($have -and -not $ours) { wsl.exe -d $Distro -u root --cd / -- test -e /etc/fork-kit/desk-distro; $ours = $LASTEXITCODE -eq 0 }

$want = [ordered]@{ memory = "${MemoryGB}GB"; swap = "${SwapGB}GB"; networkingMode = 'nat'; dnsTunneling = 'true'; guiApplications = 'false' }
$want = [ordered]@{ memory = (WantMemory $WslConfig $MemoryGB); swap = "${SwapGB}GB"; networkingMode = 'nat'; dnsTunneling = 'true'; guiApplications = 'false' }
$changes = @(Changes (Read-WslConfig $WslConfig) $want)
Write-Host ''
Write-Host "Next: the distro $Distro; .wslconfig (for ALL your WSL distros; a dated copy is kept):" -ForegroundColor Yellow
Expand Down Expand Up @@ -250,7 +263,7 @@ try {
$changed
Remove-Item -LiteralPath $Made -ErrorAction SilentlyContinue # the distro's own mark is there now
# The live state decides, not only what this run changed: a run stopped before its shutdown restarts next time
$live = @(InDistro 'the running settings' ("WANT_KB=$([long]$MemoryGB * 1048576)`n" + $Live))
$live = @(InDistro 'the running settings' ("WANT_KB=$(CapKb $want.memory)`n" + $Live))
$up = [double]((wsl.exe -d $Distro -u root --cd / -- cat /proc/uptime) -split ' ')[0]
if ((Test-Path $WslConfig) -and ((Get-Date) - (Get-Item -LiteralPath $WslConfig).LastWriteTime).TotalSeconds -lt $up) {
$live += 'restart: .wslconfig is newer than the running WSL'
Expand Down
41 changes: 30 additions & 11 deletions fork-kit/pc-agents/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ The kit reads the `pc-agents` section of the machine file `/etc/fork-kit/machine
"version": 1,
"pc-agents": {
"organization": "Example home lab",
"t3Version": "0.0.30",
"t3Version": "0.1.9",
"t3ReleaseBaseUrl": "https://github.com/example/t3code/releases/download",
"port": 3773,
"maxRuntimeMode": "full-access",
Expand All @@ -72,7 +72,7 @@ The kit reads the `pc-agents` section of the machine file `/etc/fork-kit/machine
| Key | What |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `organization` | the name the managed policy shows in T3's settings |
| `t3Version` | the exact T3 version to run (the same as the T3 that links to this PC); installed with `scripts/install.sh` |
| `t3Version` | the exact T3 version (the linking T3's), 0.1.7 or newer (see below); installed with `scripts/install.sh` |
| `t3ReleaseBaseUrl` | where that version's release files are (`T3CODE_RELEASE_BASE_URL` of `scripts/install.sh`) |
| `port` | T3's port (`T3CODE_PORT`); the Tailscale ACL opens it to the linking T3 only |
| `agentUid` | the `agent` user's uid (default 1100; not 1000, the first user of every other distro, see Limits) |
Expand All @@ -85,6 +85,9 @@ The kit reads the `pc-agents` section of the machine file `/etc/fork-kit/machine
| `peers` | the linking T3's Tailscale address(es) (CIDR list, 1 to 16): the only private addresses the unit talks to |
| `tailscaleTag` | the tag this PC's Tailscale node gets (`tag:name`) |

`t3Version` must be 0.1.7 or newer: older releases have no managed policy, so they would run with none of the kit's
locks and with updates on. Setup and `check` refuse them, naming the key. (`t3 pair`, step 10, came earlier.)

Every T3 setting can be locked through `lockedSettings`, the fork's own settings (`agentSlots`, `usagePacingGate`,
`usagePacing`, `waitFor`, ...) too: the managed policy locks any key of the server settings, upstream's or the fork's
(`apps/server/src/policy/managedSettings.ts`), and a test proves it for the fork's keys. Lock one field per dotted
Expand Down Expand Up @@ -143,10 +146,19 @@ Commands are for Windows PowerShell unless a step says otherwise. `<distro>` is
If Claude says it cannot read its managed settings on `/mnt/c` (`EACCES`), choose "Continue without these
settings": that is Windows' folder, which the walls hide on purpose. Then restart T3, which looks for providers
only when it starts: `wsl -d <distro> -u root -- systemctl restart t3code-agents` (its start runs the check first).
Every agent of this T3 runs as `agent`, in the one home, so a tool installed there once is every agent's: install a
project's toolchain (Node, its package manager) the same way, through `as-agent`, before the first agent needs it.
Setup installs the system libraries they need (`libatomic1`, without which Node does not start, and `unzip`).
8. **Log in to GitHub as the agent:** install `gh` (as root, from GitHub CLI's docs), then
`wsl -d <distro> -u root -- /opt/pc-agents/current/sbin/pc-agents as-agent -- gh auth login --with-token` and paste
a fine-grained token for the agents' repos into that window only. It waits without a prompt: paste the token,
press Enter, then Ctrl+D.
press Enter, then Ctrl+D. Then give the agent a git identity (its commits fail without one):
`wsl -d <distro> -u root -- /opt/pc-agents/current/sbin/pc-agents as-agent -- git config --global user.name '<name>'`
and
`wsl -d <distro> -u root -- /opt/pc-agents/current/sbin/pc-agents as-agent -- git config --global user.email '<email>'`,
with a name of your choice and an address that is no one's private one, for example the token account's noreply
address (`<id>+<login>@users.noreply.github.com`, shown in its GitHub email settings). Run again, they only set
the same values again.
9. **Keep the distro running:** WSL stops a distro soon after its last window closes, and does not start one when
Windows starts. A logon task of your own (no administrator needed) keeps this one running while you are logged
in. In PowerShell, as yourself (the same task as the desk starter's, `fork-kit/desk/windows/start-desk.ps1`):
Expand All @@ -161,14 +173,18 @@ Commands are for Windows PowerShell unless a step says otherwise. `<distro>` is
10. **Pair, then link from the other T3:** this PC's T3 is walled from the Windows host on purpose, so a browser on
this PC cannot open it, nor make a pairing code there. Make the code from the command line (PowerShell):
`wsl -d <distro> -u root -- /opt/pc-agents/current/sbin/pc-agents pair`. It runs T3's own `t3 pair` as the
agent under the walls, the T3 the unit runs (`/opt/pc-agents/t3/runtime/versions/<t3Version>/t3`), and prints a
token that expires in 5 minutes (`pc-agents pair --ttl 15m` for longer); the address it prints is the distro's
own, not one to link. A kit without `pair` (older than this step): the same through
`pc-agents as-agent -- /opt/pc-agents/t3/runtime/versions/<t3Version>/t3 pair` (an upgrade leaves the old
version's folder there, so name yours). In the other T3: Settings → Environments → Linked environments → Link,
with this PC's tailnet DNS name (MagicDNS: `http://<name>.<tailnet>.ts.net:<port>`; `tailscale status` there
shows the name), the token, and **Full access**. Not its tailnet IP address: T3 refuses to link a plain-http IP
address.
agent under the walls, the T3 of `t3Version` that the unit starts
(`/opt/pc-agents/t3/runtime/versions/<t3Version>/t3`; when setup has not installed that one yet, it says so: run
step 3 again), and prints a token that expires in 5 minutes; for longer:
`wsl -d <distro> -u root -- /opt/pc-agents/current/sbin/pc-agents pair --ttl 15m`. The token stays in this
PowerShell window's scrollback, usable by anyone who sees it until it is used or expires: give a long `--ttl` only
knowingly, and close the window once linked. The address it prints is the distro's own, not one to link. A kit
without `pair` (older than this step):
`wsl -d <distro> -u root -- /opt/pc-agents/current/sbin/pc-agents as-agent -- /opt/pc-agents/t3/runtime/versions/<t3Version>/t3 pair`
(an upgrade leaves the old version's folder there, so name yours). In the other T3: Settings → Environments →
Linked environments → Link, with this PC's tailnet DNS name (MagicDNS: `http://<name>.<tailnet>.ts.net:<port>`;
`tailscale status` there shows the name), the token, and **Full access**. Not its tailnet IP address: T3 refuses
to link a plain-http IP address.

Run step 3 again for a new release or a changed machine file (and steps 4 and 5 if it asks); T3 restarts only when
something changed. To remove everything: `wsl --unregister <distro>`.
Expand Down Expand Up @@ -213,6 +229,9 @@ allowed (connection tracking).
`SIGHUP` (a closed window) stop setup the same way, the running download's whole group too.
- **Start limit:** a rerun within 10 minutes of five failed starts still starts T3 (`systemctl reset-failed` first).
- **An older kit's distro:** an `agent` made with a login shell gets `/usr/sbin/nologin` (`usermod`), once.
- **Packages:** setup installs `nftables`, `libatomic1` and `unzip` when `dpkg` does not list one as installed (a
distro set up by an older kit gets the two new ones at its next run; no T3 restart for them). A package install
stopped half-way is finished first (`dpkg --configure -a`); a failed one stops setup, naming the command to run.
- **A distro that is not fresh:** refused before anything is written, with the reasons: another login user, an
`agent` with another uid or in another group, a file the kit would write that it did not write (or that was
edited since, for example a hand-written `wsl.conf` or `policy.json`), a cron, at or ssh unit where the kit masks
Expand Down
10 changes: 9 additions & 1 deletion fork-kit/pc-agents/lib/pc_agents.py
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,12 @@
# off through limits.updates (all versions; the server's self-update refuses), not the newer automaticUpdates.
KIT_SETTINGS = {'linkedEnvironmentsEnabled': True}
VERSION = re.compile(r'(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(-[0-9A-Za-z.-]+)?')
# The oldest T3 that applies a managed policy (0.1.7; `t3 pair` is older): an older one would run with none of the
# kit's locks, updates on, and quietly. Its pre-releases count as it.
OLDEST_T3 = (0, 1, 7)
# Debian packages setup installs when missing: the agent firewall's nft; libatomic1, which Node (and so most agent
# tools) needs to start, while the agent has no sudo to install it; unzip, which install steps of packages use.
PACKAGES = ('nftables', 'libatomic1', 'unzip')
HEAD = '# pc-agents kit: written by `pc-agents setup`; an edit is refused at its next run and fails the walls check\n'

# What the kit runs from a release: source path -> (path in the version folder, mode). The walls are the merged
Expand Down Expand Up @@ -72,7 +78,9 @@ def is_ip_list(value, net, glob=False, most=64):
SPEC = {
'organization': (str, machine_file.REQUIRED,
lambda v: None if v.strip() and len(v) <= 80 else '1 to 80 characters, not blank'),
't3Version': (str, machine_file.REQUIRED, lambda v: None if VERSION.fullmatch(v) else 'an exact version, no v'),
't3Version': (str, machine_file.REQUIRED, lambda v: 'an exact version, no v' if not VERSION.fullmatch(v) else
None if tuple(map(int, VERSION.fullmatch(v).groups()[:3])) >= OLDEST_T3 else
'%d.%d.%d or newer (the first T3 with the managed policy)' % OLDEST_T3),
't3ReleaseBaseUrl': (str, machine_file.REQUIRED,
lambda v: None if re.fullmatch(r'https://[A-Za-z0-9./_-]+', v) else 'an https URL'),
'port': (int, machine_file.REQUIRED, lambda v: None if 1024 <= v <= 65535 else '1024 to 65535'),
Expand Down
Loading
Loading