Repository navigation
WebUI
The WebUI is the browser face of CompileGateway: a React + Fluent UI single page app that the daemon serves from its own HTTP port, and that can do everything the CLI can do except the machine-facing features listed near the end of this page.
- It is one page app built with Vite from
webui-srcintowebui/dist, and that output is embedded into the binary at compile time (rust-embed,src/server.rs). There is nonode_modulesand no web server to install at runtime: the daemon servesGET /and the static assets itself. - Open
http://<host>:<port>/. That is the address the daemon prints at startup and reports inGET /api/status; withport: 0the operating system picks a free port and writes the real one toruntime.json. - The same daemon, the same API. CLI and MCP talk to the exact same endpoints, so a job started from this page behaves like one started anywhere else — including the project lock and the job record.
- The page language follows the server:
config.json'slanguage(auto/zh-Hans/en-US) decides which string table the WebUI loads, and changing it on the Settings page re-renders the whole page. - Operations are icon buttons with tooltips; where a label exists in the string table it is quoted below exactly as it appears in the UI.
- The left sidebar has five entries:
Status,Settings,Clients,Build types, andWorkflows. Inside the instance view a horizontal strip of client chips does the same job without going back to the list. - The sidebar footer shows the version and the URL this page was loaded from, plus
Sign outwhen it applies. - While the first
/api/statuscall is in flight the page shows only a spinner. If that call fails there is no partial page: it showsFailed to load: {msg}. - Navigation, tabs and the client strip keep their text labels; action buttons are icon-only with a tooltip, so hovering is how you read them.
| Where the request comes from | What happens |
|---|---|
Loopback (127.0.0.1, ::1) |
Always allowed, even when credentials are set — no login page. |
| Another device, no credentials configured | Allowed as well; lan / wan do not force credentials. |
| Another device, credentials configured | The login page appears: Username, Password, OK. A successful POST /api/login sets the session cookie (HttpOnly, 12 hours). |
| Same source IP logging in too often |
429; the page shows Too many attempts, retry in {s}s.
|
| Changing credentials from another device | The Username / Password inputs are disabled with the hint Credentials can only be changed from this machine (127.0.0.1). |
-
lanvswan.Listen modelanbinds only127.0.0.1, so only this machine can reach the page.wanbinds0.0.0.0, so other devices can usehost-ip:port. -
The
wanwarning is persistent. Withwanand no credentials, a yellow banner titledSecurity warningstays at the top of every page until credentials are set. The API reports the same condition aswarning: "wanWithoutAuth"in/api/status. -
Login throttling is per source IP.
Login rate-limit interval (seconds)(auth.loginIntervalSeconds) is the minimum gap between two attempts from one IP;0disables it, the value is capped at 86400. - There is no "forgot password" flow. Credentials can only be changed from loopback, so a different device can never take the daemon over by resetting them.
-
The page always loads; the data does not. The static assets (
/, the JS bundle, the stylesheet) are deliberately unauthenticated — the login page itself has to load — while every/api/*call is checked, so an unauthenticated visitor sees the shell and no content at all. -
Behind a reverse proxy the daemon only ever sees the proxy's address, so all external users share one throttle bucket and credentials can no longer be changed from outside (that refusal is
authLocalOnly, and it is by design). ForwardX-Forwarded-Proto: httpsso the session cookie is issued asSecure; the daemon does not trustX-Forwarded-For. See Configuration and logs. - The page keeps almost no state: reloading it re-reads
/api/status,/api/config,/api/clientsand/api/projects, and any/api/*call answered with401sends the browser back to the login gate. -
Sign outappears in the sidebar footer only for a non-loopback, authenticated request.
Read-only summary of the running daemon. Every value comes from /api/status:
| Row | What it shows |
|---|---|
Version |
App name and version. |
URL |
The address this WebUI is served on. |
Port |
The bound port. |
Listen mode |
lan — this machine only (localhost / 127.0.0.1) or wan — reachable by other devices (host-ip:port). |
Language |
auto, zh-Hans or en-US. |
Credentials |
The username plus set, or not set. |
Other devices |
yes / no — whether this request came from somewhere other than loopback. |
MCP (AI agent) |
The live endpoint plus N tools, or Enabled in the config, but not listening (the port may be taken)., or Off.
|
Config file |
Where config.json lives. |
The page itself has no buttons and no lists: projects, tasks and job history live under Clients → a client → Projects.
Clients manages the SSH targets (clients.json, next to config.json).
-
Search matches
name / ip / port / tag, partially and with regular expressions; an invalid pattern falls back to plain containment. -
View mode is a card list with no action buttons. Clicking a card opens that client's instance view (
Click a card to open this instance). -
Editputs every client into edit mode at once. In that mode the toolbar becomesAdd client+ search +Done;Donecommits every addition, change and deletion in one pass. - Per-client fields:
Name,IP address,Port(default 22),Auth,Tags,Base directory, plus the host lock toggleOne job per client at a time (hostLock)to strictly serialize jobs targeting this physical client. -
Authis eitherPassword(username + password) orKey file(username + path, withChoose…/Select private keyopening a file picker on the daemon machine) plusKey passphrase. -
Secrets are write-only. The API never returns a password or passphrase, so an empty field means "leave the stored value" (
leave empty to keep it).DeleteasksDelete this client?and drops the card from the draft; the removal is only persisted whenDonesubmits the whole set. -
Tagsis free-form: each tag has a close button and there is aNew tagadd button. -
Test(connections) and the host key are not on this page. They live in the instance view, because a test really opens an SSH session and its output belongs to that machine's log.
Opening a client leads to its instance view: a strip of client chips at the top (switch machines without going back to the list), the client name and host:port · auth, a Test button, and Back to list. Below it are four tabs.
- Connection facts:
IP address,Port,Auth,Tags,Host key. -
Base directory— the root for sources and artifacts on that machine.Save and verifyreally connects and runsmkdir -ppluspwd: on success the resolved absolute path is stored and shown underRemote path, on failure nothing is written and the remote error is shown as-is. -
Stored host key (TOFU). The fingerprint recorded on the first successful connection is shown; a later mismatch rejects the connection until you decide.
-
Forget itclears the record, so the next connection is treated as first trust again. -
Import from known_hostspicks aknown_hostsfile on the daemon machine and claims the matching key without connecting first.@revokedentries, CA entries, and a host with several different keys are refused with an explanation. -
Export known_hosts lineproduces one standard line you can append to~/.ssh/known_hosts; it needs the stored public key text, otherwise the page says only the fingerprint is available. - When
Testhits a mismatch, a dialog titledHost key changedshows the stored and the presented fingerprint side by side and offersTrust this new fingerprint. Trusting is a deliberate decision, not a retry.
-
-
Check the target machineruns the whole environment probe over one SSH session (90 s timeout). Until then the page only reads the server-side cache and saysNever checked yet. Use the button above to connect once. - Results are grouped by platform (
xcode,gradle,flutter,dart,rust,common), each item with its version ormissing, pluspresent, version unreadablewhen a tool exists but will not report a version. A group with nothing found is markedall missing. -
Diskshows available and total space, used percentage and mount point. -
Xcode installationslists every/Applications/Xcode*.appwith its own version and build, the licence badge (Licence accepted/Licence not accepted), and thebuilds with DEVELOPER_DIR=<dir>line that a build task can pass per run instead of touching the target's globalxcode-select.
- A terminal-style pane of this client's log domain. The pane is fixed dark on purpose; it is a log surface, not a normal card.
-
Log rangeswitches betweenLive(Last 4000 in memory, refreshed every 1.5s, polled as an increment) and a day of the on-disk history (YYYY-MM-DDfiles, columns time / source / log domain). - Source checkboxes start at
All sourcespluswebui,cliandmcp, and pick up any other source that actually appears; hiding lines reportsN hidden. -
Testresults, build output and security-relevant host-key changes all land here.
Projects lists the source folders registered against this client: Name, Host folder and Remote path per card, plus a second line with Excludes, Last sync (or never synced) and a third with Artifact and Built at (or never built). Import project folder opens the daemon-side folder picker (GET /api/browse) and registers the chosen directory; removing a registration deletes no files.
Card actions, all icon buttons with a tooltip:
| Action | What it does |
|---|---|
Add build task |
Opens the task dialog for a new task. |
Project file tree |
Read-only tree of the client side and the host side. |
Push source |
Sends the source tree over tar/SSH; the confirmation has Clean the remote directory first (overwrite) (default off, which means "overwrite same names, keep extra remote files"). |
Pull |
Brings the remote directory back to the host-managed folder. |
Export archive |
Pack-and-download dialog (below). |
Delete |
Removes the registration only. |
-
File tree. The dialog has
Client/Hosttabs,Up, a clickable breadcrumb androot. Each row can copy its relative path (Copy the relative path (paste it into a file task)); files open a controlled preview (binaries report size and time only, long text is truncated), symlinks are badgedsymlink, andCreate a file task from this pathstarts acopy/move/delete/exporttask pre-filled with the current directory. Paths are relative to the project root;..and absolute paths are rejected at save time. -
Export archive. The dialog lists
Existing archiveswith size and time and aDownloadlink each, showsDirectory(the hostexports/folder), and below it builds a new archive: aClient/Hostradio pair,Path to pack(defaults to the last build artifact),Output file name(empty means<project>-<unix timestamp>.zip), thenStart export. -
Job status bar. While a job holds the project, the card shows a spinner, the kind badge, the title,
Running for {s}s, and a cancel button (Cancel job, confirmed withCancel this job? The remote command will lose its connection.). Starting another job for the same project is refused by the daemon (projectBusy) until this one finishes. -
Result banner. When the job ends, the card shows the outcome (
Build finished,Build failed,Cancelled, with the exit code), the noteThe build output was written to this client's Logs tab., and — for multi-step work — one line per step. If a step failed, a button labelledRetry from step Nretries from that step using the input snapshot recorded in the job. -
Build tasks. Each row shows the task name, its kind badge (Build,Push,Pull,Copy,Move,Delete,Export), aSigned/Unsignedbadge for builds, and the kind's key fields (for builds: manifest, variables and artifact path; for file tasks:From→Toand the overwrite flag). Row actions:Run build,Preview command(a dialog titledCommand that will runwithCopy),Add to a batch,Edit JSON(Edit JSONopens the raw task object, equivalent tocgw tasks save --body),Edit build task, andDelete. Destructive kinds ask for confirmation with the concrete path first (This is a delete task: <path> will be removed for good.and similar formoveand overwritingcopy). -
The task dialog covers all seven kinds: pick the kind first, then only the relevant fields appear —
From,To,Path to delete,SourceswithAdd source,Path(relative,no .. and no absolute paths),Output file name,Signing(Signed/Unsigned),Artifact path,Artifact list, andWhich Xcode to use.Pick from the file treefills a path from the project tree. -
Batches. A batch is an ordered list of task references. The row shows the name,N stepsand the chain of task names; actions areRun batch,Edit batch,Edit JSONandDelete. The batch dialog offersName,Add step,Move up,Move down; steps run in order, any failure stops the batch and later steps are recorded as skipped. Step-level variables (steps[].variables) can only be written throughEdit JSON. -
Recent jobs. Below the cards, the last few jobs of this client with kind, state (Running,Finished,Failed,Cancelled), elapsed time, message, and a retry button when there is a failed step to resume from.
Build types is the manifest editor; each manifest is one build type, stored as manifest/<id>.json.
-
Reload from diskis the only manual refresh in the WebUI, and it exists because those files are yours: if you edit a JSON in an editor, pull it with git or let another tool write it, the daemon cannot see that. Reloading re-reads the directory and reports what was added, changed or removed. -
Restore missing templatesappears only when a built-in template is missing from disk and writes back only the missing ones; your edited files are never touched. -
New manifestasks forFile name (id) of the new manifestand writes a starter template. Reusing an existing id asks first (This build type already exists). - Each card shows display name, platform, the
shippedbadge for built-in names,id,include.paths,Steps,Artifact,CacheandVariables; invalid files show their validation errors on the card. - Actions:
Edit manifest(raw JSON textarea withFormat,Cancel,Save; the daemon validates before saving and lists every problem),Export JSON(browser download of<id>.json) andDelete manifest. -
Detect. The input at the top takes a host directory and
Detectreports which build types match, listing theMatched:paths and anyMissing:ones. All of a manifest'sinclude.pathsmust exist for it to match.
Workflows provides centralized visual management and parameterized application of cross-project workflow presets (workflows/<id>.json):
- Preset catalog: Cards display preset name, ID badge, description, input count, task count, and the execution step chain.
-
Preset actions:
-
New workflow: Provide a preset ID to create a new pipeline from a starter skeleton. -
Reload from disk: Re-readworkflows/directory from disk to pick up external file changes. -
Restore missing templates: Automatically re-seed deleted built-in official templates. -
Edit JSON: Raw JSON textarea with auto-formatting and server-side validation. -
Export JSON: Download<id>.jsondirectly in the browser. -
Delete workflow: Prompt for confirmation and delete the file from disk (does not affect previously applied projects).
-
-
Apply to project (Apply)dialog:- Select target project from dropdown list.
- Dynamic parameter inputs: Automatically populated based on template's declared
variables(marking required inputs and prefilling defaults). - Pre-flight preview: Previews created tasks, target batch ID (
wf-<preset id>), and any name conflicts in the target project. - Overwrite toggle: Check
Overwrite conflicting tasks and workflowsto safely replace existing definitions. - Click
Confirm apply: Submits the request and immediately generates the tasks and batch workflow in the target project.
The card at the top holds the general settings:
| Field | Notes |
|---|---|
Port |
0 = pick a free port automatically. A fixed port that is busy is an error, not a retry. |
Language |
auto / zh-Hans / en-US; the page follows it. |
Listen mode |
lan or wan; marked restart required. |
Login rate-limit interval (seconds) |
0 = no limit, capped at 86400. |
Log retention (days) |
Daily rolling files older than this are deleted; default 7, capped at 3650. |
Log directory |
Read-only: where the daily files live. |
Extra host directories |
One absolute path per line. Browsing, project registration and build-type detection share this list. |
One job per client at a time |
The host lock, off by default. When on, another project on the same client gets hostBusy instead of running in parallel. |
Username, Password, Clear the stored password
|
Credentials; disabled unless the request came from loopback. |
-
Savereports eitherSaved.orSaved. Port and listen mode changes take effect after a restart. - The
MCP (AI agent)card is separate because it behaves differently:Enable MCP,MCP listen mode,MCP port, a read-onlyCurrently liverow, andGive this URL to your clientwithCopy URL. It listens on its own port (default 3994,0= pick one), independently of the WebUI port, andMCP changes apply immediately — no restart.A port that cannot be bound is reported right away and the previously working port keeps serving. - Warnings shown here: the
MCPwan-without-credentials note, a note when the default MCP port had to give way, and the persistentwansecurity banner from the top of the page.
The desktop binary compilegateway is a separate terminal-style window: a log pane on top and an input box below, plus diag <name> to open one extra window per client. That pane is the local, always-available view of what this process is doing — it also has to work when the HTTP server never came up (a busy port), which is exactly when you need to read the log. The WebUI's Logs tab is the remote view of the same daemon over HTTP: it is scoped to one client, it can switch from the live tail to any day of the on-disk history, and it can filter by source. Use the window to see "is the service even running", and the Logs tab to inspect one target machine's build output after the fact. Configuration and logs covers the files themselves.
One capability is intentionally CLI / HTTP / MCP only, because it is for machines rather than for clicking:
-
JSON Schema access.
cgw schema [name]andGET /api/schema/{name}return draft-07 schemas formanifest,task,batch,client,projectandworkflow, plus the MCP resourcescgw://schema/<name>. There is no schema viewer page.
Two related facts worth knowing:
- The
manifest/andworkflows/directories have no file watcher;Reload from diskon either page is the explicit refresh, equivalent tocgw manifests refreshandcgw workflows refresh. - Native pickers are daemon-side:
Choose…,Import project folderandImport from known_hostsall list files on the machine running the daemon (/api/browse,/api/dialog/pick-file,/api/dialog/pick-folder), not on the device showing the page.
| Goal | Where to go |
|---|---|
| See version, port, listen mode, credential state, MCP address | Status |
| Add, change or remove an SSH target | Clients |
| Find out whether a target can build this project at all |
Clients → client → Environment
|
| Watch a build or a sync scroll by |
Clients → client → Logs
|
| Set the root directory a target uses | client → Status → Base directory
|
| Re-claim a host key after rebuilding a VM | client → Status → Trust this new fingerprint / Import from known_hosts
|
| Push source, pull artifacts, run one task | client → Projects → project card |
| Run several tasks in order and resume after a failure | project card → Batches, Run batch, Retry from step N
|
| Produce a zip and download it | project card → Export archive
|
| Edit a build command template | Build types |
| Inspect, edit and apply cross-project workflow presets | Workflows |
| Change port, language, credentials, throttling, retention, allowed directories, host lock | Settings |
| Point an AI client at the daemon |
Settings → MCP (AI agent) → Give this URL to your client
|
| Get a JSON Schema | Not here — CLI or the HTTP API |
| Setting | When it takes effect |
|---|---|
Port, Listen mode
|
After restarting the program. |
Language |
Immediately — the whole page follows the server value. |
Username, Password, Clear the stored password
|
Immediately, from loopback only. |
Login rate-limit interval (seconds) |
Immediately; re-read on every login attempt. |
Log retention (days) |
Immediately. |
Extra host directories |
Immediately. |
One job per client at a time |
Immediately. |
MCP (AI agent) group, including its port |
Immediately; the daemon rebinds at once. |
-
Where the log source
webuicomes from. Every request the page makes carriesX-Client: webui, and the daemon records that as the log line's source and as the job'ssource. Sowebuiappears in theLogstab's source checkboxes (they are seeded withwebui,cliandmcpand pick up anything else that shows up), in thesourcecolumn when you read history, and in thesourcefield of every job this page started. The page itself writes no log lines — the label comes from the request header. - Narrow instead of scrolling: the live pane keeps the last 4000 entries in memory, history is read one day at a time, and each stored line also carries a log domain (
global,client,project,job) that the CLI exposes as--scope. - If a page stays solid-colour or unclickable, it is almost always a Fluent portal mounting over the shell; Troubleshooting has the details.
← Home