Repository navigation
Clients and Environment
A client is one SSH target machine — usually the macOS build box that CompileGateway pushes sources to and builds on.
A client is exactly one SSH target: an address, a port, credentials, free-form tags, and one base directory on that machine. Every project names exactly one client; many projects may share one. The client is the machine used by push, pull, build, copy, move, delete and export.
The daemon stores the list in clients.json, next to config.json:
{
"id": "c-4f2a91b0c3d8",
"name": "mac-mini",
"host": "192.168.1.20",
"port": 22,
"auth": {
"method": "key",
"username": "builder",
"password": "",
"keyPath": "C:/Users/me/.ssh/id_ed25519",
"passphrase": ""
},
"tags": ["ios", "office"],
"baseDir": "~/CompileGateway",
"baseDirResolved": "/Users/builder/CompileGateway",
"hostKey": "SHA256:9f3c1p...",
"hostKeyLine": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI...",
"hostLock": false
}id is generated by the daemon: c- followed by 12 hex characters. hostKeyLine may be empty; it
is filled once a connection has seen the host public key, or after importing one.
| Field | Meaning |
|---|---|
id |
Daemon-generated identifier (c-…); used by every CLI command and API path. |
name |
Display name. Defaults to the host when you add a client without --name. |
host |
Hostname or IP address of the target machine. Required. |
port |
SSH port. Default 22. |
auth.method |
password or key. Default password. |
auth.username |
SSH user name. If empty, the daemon falls back to its own USERNAME / USER environment variable. |
auth.password |
Password used when method is password. |
auth.keyPath |
Private key file used when method is key. The daemon reads it, so the path is on the daemon's machine. |
auth.passphrase |
Passphrase for the private key. ssh-keygen encrypts keys by default, so this is needed often. |
tags |
Free-form device tags; the WebUI search box covers name / IP / port / tags. |
baseDir |
Base directory on the target machine. Default ~/CompileGateway. |
baseDirResolved |
Absolute path the remote pwd returned the last time the base directory was verified. Written by verification, not typed by hand. |
hostKey |
Recorded host key fingerprint (SHA256:…). Empty means "never connected". |
hostKeyLine |
The host's raw public key line (ssh-ed25519 AAAA…), kept so trust can be exported as known_hosts. It is a cache of hostKey and is dropped when the fingerprint changes. |
hostLock |
Host-level mutual exclusion switch for this specific client machine. When true, jobs targeted to this physical host run strictly serially (either global or per-client hostLock triggers exclusion). Default false. |
Secrets are write-only. password and passphrase live on the daemon machine in
clients.json, but the API never returns them; client records expose only hasPassword and
hasPassphrase, enough for the WebUI to show that a secret exists. On save, an omitted
password / passphrase means "keep the stored value" and an empty string means "clear it", so a
blank field in the edit form is not a change. The raw host key line is not a secret, but the client
record reports it as hasKeyLine; the line itself comes from the known_hosts export endpoint.
auth.method |
What it sends | Notes |
|---|---|---|
password |
username + password
|
Fails with "no password given" when the password field is empty. |
key |
username + a private key file |
Optional passphrase unlocks the key; signing uses SHA-256. |
Formats that are confirmed to load:
- OpenSSH native keys (
BEGIN OPENSSH PRIVATE KEY, encrypted or not), PKCS#1 (BEGIN RSA PRIVATE KEY), PKCS#8 (BEGIN PRIVATE KEY, plus the encryptedBEGIN ENCRYPTED PRIVATE KEYform), and SEC1 (BEGIN EC PRIVATE KEY); - traditional PEM encryption with
DEK-Info: AES-128-CBC, which is whatssh-keygen -m PEM -N <pass>produces; - PuTTY
.ppkv2 and v3 formats (validated against the PuTTY specification); - keys with CRLF line endings (copied through Windows editors), encrypted or not.
Traditional PEM encryption with any other cipher (AES-192-CBC, AES-256-CBC, DES-EDE3-CBC) is
rejected, and the error says so with a conversion command (openssl pkcs8 -topk8) instead of a
misleading "wrong passphrase". A passphrase-protected key opened without a passphrase says "this
key looks passphrase-protected, fill in the key passphrase"; a wrong passphrase says so too.
The test really opens an SSH session, runs echo CGW_OK, and checks the marker came back. Connect,
handshake and authentication share a 20-second budget; the test itself gives up after 15 seconds.
cgw clients test mac-mini
cgw clients test mac-mini --jsonWebUI: open the client's instance view and use the test connection button; --json on the CLI
gives the whole object below.
| Field | Meaning |
|---|---|
ok |
Whether the whole test succeeded. |
message |
Human-readable result, e.g. connected: builder@192.168.1.20:22, or the failure reason. |
output |
The remote command's combined stdout/stderr (the CGW_OK echo), for eyeballing. |
hostKey |
The fingerprint seen this connection. On first success the daemon records it and its public key line on the client. |
presentedKey |
On a mismatch, the fingerprint the peer actually presented. |
mismatch |
true when the failure was a fingerprint mismatch rather than a network or credential problem. |
The first successful connection records the host key's SHA-256 fingerprint (hostKey) and its raw
public key line (hostKeyLine); every later connection must present the same fingerprint, and a
different one aborts the connection with:
host public key fingerprint does not match the recorded one, connection refused. previous: … current: …
When a remote host is re-provisioned, reinstalled, or replaced, its host key changes. CompileGateway blocks connection attempts by default to guard against man-in-the-middle attacks, while surfacing the newly presented key (presentedKey) and mismatch: true so the administrator can make an informed decision:
-
trust the new key —
cgw clients hostkey mac-mini --trust SHA256:…records the presented fingerprint and replaces the old one; -
clear the record —
cgw clients hostkey mac-mini --forget; the next connection counts as a first connection again; -
just look —
cgw clients hostkey mac-miniprints the recorded value.
Anything that is not shaped like SHA256:… is rejected before a write. Trusting and clearing both
write a WARN line into that instance's log, because letting a mismatch through waives
man-in-the-middle protection once.
In the WebUI the same choice appears when the test button hits a mismatch: a confirmation dialog shows the recorded fingerprint and the presented one side by side. The instance status page also shows the recorded fingerprint and offers a clear button.
You can pin the key before the first connection, or carry the trust elsewhere:
# from a file the CLI can read (the file may be on the user's machine), or from stdin
cgw clients hostkey mac-mini --import ./known_hosts
ssh-keyscan -p 2222 192.168.1.20 | cgw clients hostkey mac-mini --import -
# one standard known_hosts line, ready to append to ~/.ssh/known_hosts
cgw clients hostkey mac-mini --exportImport follows OpenSSH known_hosts rules: comma-separated patterns, * / ? globs, ! negation,
[host]:port entries, and hashed |1|salt|hash hostnames compared with HMAC-SHA1. Hostnames
compare case-insensitively; entries without a port apply to port 22 only, so on a custom port the
import says why nothing matched instead of failing silently.
Export needs the raw public key line. With only a fingerprint recorded it returns a commented line plus a warning: a fingerprint is a one-way digest, so one more connection is needed for the standard form. The WebUI has both buttons on the instance status page (its file picker browses the daemon's machine).
| Rejected | Why |
|---|---|
A match on an @revoked entry |
That key is explicitly revoked and is never accepted as a host key. |
A match on an @cert-authority entry |
That is a CA that signs host certificates, not a host key; host certificates are unsupported. |
| More than one different key matching the client | The tool does not guess; it lists the candidate fingerprints for you to choose from. |
Replacing an existing different recorded key without --force
|
A silent swap is exactly what TOFU prevents. |
Unknown @… markers, SSH1-era RSA1 lines, unparsable keys |
Reported as line N: reason and skipped; they never become a trusted key. |
Each client has one base directory: the root for sources and artifacts on the target machine. The
default is ~/CompileGateway. It exists so CompileGateway never works directly in the user's home
directory, because a clean push deletes and recreates its target and therefore needs a root of
its own.
Setting it verifies it for real:
cgw basedir mac-mini '~/CompileGateway'
cgw basedir mac-mini '/Users/builder/builds' --no-verifyThe daemon connects and runs mkdir -p <dir> && cd <dir> && pwd (20-second budget):
-
success — the path is saved and the absolute path echoed by
pwdis stored asbaseDirResolved; - failure — nothing is written, so an unreachable directory is never stored, and the remote error is shown as-is;
-
--no-verifyskips the connection and stores the value as typed.
~-prefixed paths are passed unquoted (quoting would stop the shell expanding ~); paths with
spaces or special characters are wrapped in single quotes. The WebUI instance status page holds
the same value and verifies the same way.
A registered project's remote root is <baseDir>/<slug>, where the slug comes from the project
name (Spice Compose → spice-compose). With the default base directory, a project named app
lives at ~/CompileGateway/app on the target. Changing the base directory moves where new project
directories are created; existing remote directories are not moved.
The instance Environment tab answers "can this machine build this project at all". One run probes 11 tools plus an Xcode inventory, grouped by platform:
| Group | Probes |
|---|---|
xcode |
Xcode (xcodebuild -version), CocoaPods (pod --version), Homebrew (brew --version) |
gradle |
JDK (java -version), Gradle (gradle --version) |
flutter |
Flutter (flutter --version) |
dart |
Dart (dart --version) |
rust |
Cargo (cargo --version), rustc (rustc --version) |
common |
rsync (rsync --version), XcodeBuildMCP (xcodebuildmcp --help) |
One run also collects:
-
uname -s, which identifies the platform and decides whether the Xcode part runs at all; - the disk situation from
df -Pk "$HOME"(total / used / available / mount point / ratio); - the Xcode inventory — only on
Darwin, the script walks/Applications/Xcode*.appand runsxcodebuild -versiononce per instance through that instance's ownDEVELOPER_DIR, so each install reports its own version and build number; - the Xcode licence status, from
xcodebuild -license status.
All of it is one POSIX shell script in a single SSH session, with a ###cgw:<id> marker before
each section that the daemon splits on locally. Every probe is guarded by command -v and prints
__CGW_MISSING__ when the tool is absent, so one missing tool never fails the whole run. The
script has a 90-second timeout.
Results are grouped by platform; a group where nothing was found is still shown, marked
unavailable, so you can see what is missing. The report also carries os, elapsedMs,
checkedAt, each probe's raw output, and a message like 8 / 11 tools ready.
cgw env mac-mini # run detection (up to 90 seconds)
cgw env mac-mini --cached # read the cached report only
cgw env --script # print the script that would run; connects to nothingWebUI: the instance Environment tab reads the cache; the detect button performs the run. Per client, the cache lives in the daemon's memory and is not written to disk, so a daemon restart loses it. The Xcode picker in the task editor reads that same cache instead of connecting again.
CompileGateway never changes the target machine's global xcode-select. Instead, a build task
carries an xcodePath field holding the .app path; when the command is rendered it becomes an
export DEVELOPER_DIR=… placed after the cd into the remote directory and before every build
step, so all steps inherit it:
cd ~/CompileGateway/app && export DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer && ./gradlew … && xcodebuild …
The path is escaped as a single value, so /Volumes/My Disk/Xcode.app stays safe. An empty
xcodePath means "use whatever the target machine has globally selected". The task editor lists
the available instances from the environment cache, so running detection once is what makes the
picker useful.
| Symptom | Likely cause | What to do |
|---|---|---|
cannot connect <host>:<port> - … / connection refused |
No sshd on that port, wrong address, or a firewall. | Check host / port; try ssh -p <port> <user>@<host> from the daemon machine. |
connection or authentication timed out (20s), the peer may not have completed the SSH handshake |
Something accepts TCP but never finishes the SSH handshake. | Verify you are pointing at an SSH server, not another service on port 22. |
authentication failed: the server rejected the credentials of user … |
Wrong user or password, or the server refuses public-key auth for that account. | Check auth.username / auth.password; confirm the target's sshd_config allows the method. |
host public key fingerprint does not match … |
The target's host key changed (rebuilt VM, reinstall, new machine) — or real interception. | Compare the fingerprints, then trust the new one (cgw clients hostkey <id> --trust SHA256:…) or clear the record (--forget). |
failed to read key: looks like a passphrase-protected private key, fill in the "key passphrase" |
ssh-keygen encrypted the key and auth.passphrase is empty. |
Fill in auth.passphrase (cgw clients edit <id> --key-passphrase …). |
failed to read key: the key passphrase is wrong |
The passphrase does not decrypt this file. | Re-check it; for traditional PEM with AES-256/192 or DES-EDE3, convert with openssl pkcs8 -topk8. |
failed to read key: <path> - <error> / no key file selected
|
The daemon cannot read the path: empty, typo, owned by another user, or denied by an ACL. This is a pure-Rust SSH client, so OpenSSH's "unprotected private key" permission check does not apply. | Use a path the daemon process can read; the file must be on the daemon machine, not on the target. |
| Base directory save fails and nothing is stored | The verification mkdir -p && cd && pwd failed (no permission, typo, read-only volume). |
Read the remote error, fix path or permissions, save again; --no-verify stores it unchecked. |
-
CLI — every client command, exit codes and
--jsonoutput. - WebUI — the client list, instance view, environment tab and both host-key buttons.
- Troubleshooting — error codes and cross-cutting symptoms.
← Home