Skip to content

Clients and Environment

C-F0x edited this page Oct 26, 2026 · 1 revision

Clients and the target environment

A client is one SSH target machine — usually the macOS build box that CompileGateway pushes sources to and builds on.

What a client is

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 reference

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.

Authentication methods and key formats

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 encrypted BEGIN ENCRYPTED PRIVATE KEY form), and SEC1 (BEGIN EC PRIVATE KEY);
  • traditional PEM encryption with DEK-Info: AES-128-CBC, which is what ssh-keygen -m PEM -N <pass> produces;
  • PuTTY .ppk v2 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.

Testing a connection

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 --json

WebUI: 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.

Host key trust (TOFU)

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-mini prints 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.

Importing and exporting known_hosts

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 --export

Import 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).

What an import refuses

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.

Base directory

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-verify

The daemon connects and runs mkdir -p <dir> && cd <dir> && pwd (20-second budget):

  • success — the path is saved and the absolute path echoed by pwd is stored as baseDirResolved;
  • failure — nothing is written, so an unreachable directory is never stored, and the remote error is shown as-is;
  • --no-verify skips 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.

Environment detection

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*.app and runs xcodebuild -version once per instance through that instance's own DEVELOPER_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.

Caching and re-running

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 nothing

WebUI: 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.

Choosing the Xcode for a build

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.

Troubleshooting

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.

Where to look next

  • CLI — every client command, exit codes and --json output.
  • WebUI — the client list, instance view, environment tab and both host-key buttons.
  • Troubleshooting — error codes and cross-cutting symptoms.

← Home

Clone this wiki locally