[laudney]

What this changes

tensorfold serve --config FILE.toml reads serve flags from a TOML file. The file becomes flags ahead of the command line's and the existing table and parser read the result, so the command line wins and every flag keeps its one validation.

	main	This branch
A launch of 10 to 20 flags	a shell script or a recipe page	tensorfold serve --config glm.toml
One setting for one run	edit the script	--config glm.toml --port 9000: the command line wins
A mistyped or unserved setting	n/a	exit 2 before a model loads: glm.toml line 7: unknown key 'prot'
A value the flag refuses	the flag's message	the flag's own message with the file and line: glm.toml line 3: argument --port: invalid port: '99999'
A repeatable flag on the command line	n/a	replaces the file's whole list (--api-key new leaves no file key in force)
Relative paths in the file	n/a	start at the file's folder
A file that group or other users can write, or a link	n/a	refused; the file is opened once, checked on that handle and read from it (macOS and Linux)
A file that sets api-key and that others can read	n/a	refused with the line; chmod 600 or api-key-file
A command without --config	parsed	the same argv slice reaches the parser, pinned by a test
capabilities --json	no --config	lists --config
TensorFold Web extra flags	n/a	refuses --config, since a file could set what Settings manages

The points from #2882, each as built:

Point	Built
Parser	toml_flat.zig, written here, no outside code: strings, decimal integers and floats, booleans, arrays of strings. Tables, dotted keys, inline tables, nested arrays, multi-line strings, dates, 0x/0o/0b integers and a byte order mark are refused by name with the line. Every file it accepts is valid TOML 1.0 with the same meaning.
Keys	A flag's long name, - or _. A pair of switches has one key, the positive one: thinking = false; no-thinking is refused with the form to write. A switch with no positive twin keeps its name (no-drafts = true). A repeated key, an unknown key, an unserved flag or a wrong type is refused with file and line. A switch takes only true or false.
Precedence	Command line over file over defaults. A second --config is refused. A relative path starts at the file's folder for the flags the table marks as paths (Flag.path); model and drafter can be a repo id, so only ./ and ../ values are placed beside the file. The page says so.
Safety	Opened once with no link followed (auth.openKeys), checked on the handle and read from it. mode & 0o022, or not a regular file: refused. A file that sets api-key with mode & 0o044: refused with the line. A path flag refuses ~. The startup log prints the file and a count, never a value.
No change without it	expand returns the very slice it was given; the argument walk refuses nothing unless a --config is present.
Tests	Each refusal is checked with its line; the command line overrides a file value; one file with value, repeatable and switch flags parses to the same Args and engine request as the flags typed by hand.

• Issue: Fixes serve: read flags from a config file (--config FILE.toml), as vLLM and SGLang do #2882.
• Stacked on: main. server: the last --compact-at wins (auto then a fraction kept auto) #2883 landed as 100e4a084; this branch now holds only its own six commits, 21a96990c..63f62789b.
• atc overlap --json: run 2026-11-11 09:43 UTC before the rebase: complete: false (the snapshot's limits); conflicts in CHANGELOG.md only, except Implement GLP control vectors with a fused Metal kernel for Qwen3.8-27B #1835 (open since October), which also adds a serve flag row in README.md, cli.zig and main.zig. After the rebase GitHub reports the branch mergeable.

Checks on this head

• Head commit: 63f6278, rebased on main ab78aef (the same six commits as Ash's 01b94ec, without the landed server: the last --compact-at wins (auto then a fraction kept auto) #2883; each file's change is byte-equal)
• Lean checker, python3 tools/zig/lean_check.py, on the base and on this head: 341 and 341, 0 new (tools/pr_check.py --base upstream/main --pr 2885: 0 errors). cli.zig is 594 of 600 lines.
• Tests run, with the command and pass, fail and skip counts:
  • zig build test-serve-flags-host test-server-cpu on this head: 1393 pass, 5 skip, 0 fail of 1398 (the server suite 1359 pass and 5 skip; the filtered step 34 pass).
  • pytest web/tests/test_native.py web/tests/test_review_fixes.py on this head: 43 pass.
  • Web: pytest 456 pass, 1 skip, 1 fail. The failure is test_stand_in_reports_build_version_not_an_old_path_binary, which also fails without this change on my host (an older tensorfold on PATH). The new check_extra case fails without the native.py change. ruff check clean.
  • zig fmt --check build.zig zig and git diff --check: clean.
  • The built Linux tensorfold-native, each exit 2: port = 99999 (line 3, the flag's message), api-key in a mode 0644 file, recall-dir = "~/r", a symlinked file. A mode 0600 file with api-key = ["old"] under --api-key new logs config: conf/good.toml (3 options), places model = "./weights" at conf/weights and reaches the hub's refusal for a model that is not cached.
  • The accepted and refused reader texts were compared with Python's tomllib; it agrees on each.
• CI: to be read on this head after it runs.
• Not run, and why: zig build test test-golden in full, and the macOS and Windows builds. I have no Mac; the fchmodat mode is now @intCast as your Mac run showed, and the missing-file test expects OpenFailed on Windows, where auth.openKeys reports that.

Receipt

n/a: the change reads a file into serve flags before the existing parser. It reaches no kernel, token path or arithmetic, and a command without --config passes the same argv to the parser.

• New switch? --config FILE.toml; no default (off); accepts one path that ends in .toml; no profile row, since it sets no environment switch.

Checklist

• The title and description match the head commit, including the receipt and the stack.
• New tests fail before the change, pass after it, and skip cleanly without their dependency.
• Comments and docstrings are one line. No measurements or history in the source.
• No personal data, machine names, internal hosts or local paths in the diff or its commits. No AI attribution lines.

[laudney]

Marked ready for review. One dependency to keep in view when you queue it:

Depends on	#2883 (the --compact-at fix), which you approved and queued behind 1.2.7
Why	A file's compact-at = "auto" under a command-line --compact-at 0.5 needs the last value to win. The equivalence test here checks that case, so this branch fails without #2883.
What this branch carries	#2883's two commits (219616700, 990329332) as its first two, then its own d1e8e800c..bddbcd747
Landing order	#2883 first, then this one

After #2883 lands I rebase this branch onto main, so that it holds only its own commits, and I refresh the checks on the new head. Against current main (7d97cc656) the only merge conflict is CHANGELOG.md, where both sides add an Unreleased line; cli.zig stays at 593 lines in the merged tree.

If you prefer to land both as one, this branch already contains #2883 in full and #2883 can be closed in its favour.

[ashhart]

Thanks @laudney, this is careful work. The reader is tight, the refusals read well, and the argv pin is exactly what we wanted. On relative paths, (a) is right: only ./ and ../ are placed beside the file, so a repo id never changes meaning. A few things before it lands:

1. macOS build: cli_config_test.zig:247 and :252 pass a u32 mode to fchmodat, but mode_t is u16 on macOS, so the server tests don't compile there. With @intCast(mode), all 33 pass on a Mac.
2. Rebase: both this and server: the last --compact-at wins (auto then a fraction kept auto) #2883 conflict with main in CHANGELOG.md, so CI hasn't run yet.
3. A refused value should name its line. port = 99999 prints the flag's message and the file, but not its line. Checking each file entry with the flag's own check before merging would give glm.toml line 7: argument --port: invalid port: '99999'. For example, the file loop could share parse's loop body. Refusals that involve two flags can keep the current note.
4. A repeatable flag on the command line should replace the file's list. Today --api-key new leaves the file's old key working, and the same goes for allowed-host and allowed-origin.
5. Read the file you checked: open it once, check the open handle and read from it, as --api-key-file does (auth.zig:92). When the file sets api-key, also refuse it if other users can read it, as that flag does.
6. ~ in a path: no shell expands it, so recall-dir = "~/recall" makes a folder named ~ in the working directory. Please refuse it by line, or expand ~/ as the model value already does, and update the docs.
7. Please drop the vLLM/SGLang paragraph from docs/serve-config.md. The page should describe our file only.

It lands after the 1.2.7 release, so there's no rush.

• Synthena (Ash's Agent)

[laudney]

Thanks for the review. All seven points are in head 0beaab475, rebased on main 7d97cc656 on top of the rebased #2883 (907a9d61b).

#	Request	Change	Check
1	macOS: u32 mode to fchmodat	@intCast(mode) at each call	compiles on Linux; your Mac run is the proof for macOS
2	Rebase	both branches on 7d97cc656; the only conflict was CHANGELOG.md	GitHub reports #2883 mergeable
3	A refused value names its line	The per-flag part of parse's loop is now cli.one; each file value runs it before the merge. Three single-flag checks that ran after the loop (--idle-unload range, --name-priority form, host and origin counts) moved to cli_late.zig in the same order, and a file entry runs them too. Two-flag refusals keep the note.	glm.toml line 3: argument --port: invalid port: '99999'; tests for port, backend, temperature, a bad host inside a list, compact-at, idle-unload, name-priority and 65 hosts
4	A repeatable flag on the command line replaces the file's list	done for every repeatable flag; the file's list is still checked first, so a bad entry cannot hide	--api-key new over api-key = ["old", "older"] leaves one key; same for allowed-host; a list the command line does not name stays
5	Read the file you checked	auth.openKeys (no link followed), mode checked on the handle, read through auth.readKeys. A file that sets api-key is refused while group or others can read it, with the line.	tests for modes 0664/0646/0666, a folder, a link, and api-key at 0644/0640/0604 against 0600
6	~ in a path	a path flag refuses it by line; model and drafter keep the hub's ~/	line 2: --recall-dir: no shell expands ~ in a config file; write the whole path
7	Drop the vLLM/SGLang paragraph	removed; the page describes our file only	n/a

parse gives the same result and message for every argv I could construct after the extraction; the choices check now runs inside cli.one, after checks that only concern flags without choices. cli.zig went from 593 to 589 lines.

On this head: zig build test-serve-flags-host test-server-cpu 1358 pass, 5 skip, 0 fail; lean 386 on base and head. The description has the full list.

[ashhart]

Thanks @laudney, all seven are in on 0beaab475 and each one reads right. Each file value now goes through the flag's own check with its line. A command-line list replaces the file's. The file is checked and read through one handle. A readable file holding api-key is refused. ~ is refused by line for path flags. And the page now describes only our file. No further asks on the code.

On the relative-path question in #2882: (a), as you built it. Only ./ and ../ values for model and drafter are placed beside the file, so a repo id keeps one meaning wherever the file lives.

For the order: #2883 lands right after today's release, then please rebase this onto main so it holds only its own commits. CI hasn't started on 0beaab475 (no runs at all on this head), so that push gives us the first full run. Once it's green, it's queued to land.

• Synthena (Ash's Agent)

[ashhart]

@laudney, rebased onto today's main on top of the rebased #2883 and force-pushed (01b94ecf83). One real conflict: main added a --profile exception to the invalid-choice check in server/cli.zig, and this PR moved that check into one(), so the exception now lives in one() and --config values follow it too. 8/8 steps, 1,373/1,380 tests (7 skipped). We couldn't run web/tests/test_native.py here; CI runs it. Queued to land after #2883.

• Synthena (Ash's Agent)

[laudney]

Thanks for the rebase. I leave both branches as you pushed them. Two checks on 01b94ecf8 from a Linux host, for the part you could not run:

Check	Result
pytest web/tests/test_native.py web/tests/test_review_fixes.py	43 pass, 0 fail
zig build test-serve-flags-host	34 pass, 0 fail

The --profile exception inside one() reads right: a file's profile value now gets that flag's own refusal with its line, as a typed one does.

[laudney]

#2883 landed, so as you asked I rebased this onto main (ab78aef90) with only its own six commits: head 63f62789b. The rebase dropped the landed parent and applied cleanly; each file's change is byte-equal to your 01b94ecf8, including the --profile exception in one(). On this head: zig build test-serve-flags-host test-server-cpu 1393 pass, 5 skip, 0 fail; web/tests/test_native.py and test_review_fixes.py 43 pass; lean 341 on base and head. The title no longer says stacked.

[laudney]

python (3.11) fails on this PR because of a stale file on main, not because of this change:

File on main	Version
build.zig.zon	1.2.8 (it was 1.2.7 in the merge ref CI tested)
web/tensorfold_web/data/native-version.json	1.2.4

test_stand_in_reports_build_version_not_an_old_path_binary compares the two. Only web/ui/scripts/sync-theme.mjs (the UI dev/build scripts) writes the stamp, and the release bumps since 1.2.4 did not run it. The TensorFold Web workflow runs only for changes under web/**, so main last ran it on 11-07, when the two agreed. This PR changes web/tensorfold_web/native.py, which is why the job runs here. It failed the same way on your 01b94ecf8. python (3.12) was cancelled by the matrix after the 3.11 failure.

Choices, preferred first:

1. Re-stamp on main with the release bump ({"version":"1.2.8"}), and later bumps write it too. This removes the cause for every PR that touches web/. Then a re-run of this job passes with no change here.
2. I add one commit here that writes {"version":"1.2.8"}. This unblocks server: serve --config FILE.toml reads flags from a file #2885 now, but the next release bump makes the stamp stale again.

I will do (2) if you prefer it.

[ashhart]

Thank you @laudney. This is merged into main with your commits under your own name, so you're listed as a TensorFold contributor. It ships in the next release, credited to you in the changelog and the release notes.