Snail.MCP.BuildBridge¶
Builds, tests and Docker work of a working copy on another Mac over ssh, with the results brought back: the MacBook
stays the place code is written, the host does the heavy work. Nothing of the server's is installed on the host — ssh,
rsync and the toolchains are all it needs — and everything the server makes there lives under one root,
~/.s3l-build, which can be erased whole.
Three ideas carry it:
- The host holds no original. A workspace on the host is a copy of this machine's working copy, its outputs and caches rebuild themselves, a job's log was already answered. So nothing on the host needs keeping, a sweep erases, and the root can go at any time.
- A delivery, not a push. The working copy is mirrored as it stands, uncommitted changes included, with its
.gitand without what git ignores or a build makes again. Only what changed goes over the wire; build outputs already on the host stay, so a build there is incremental. - Look, decide, act. A sweep is planned and shown first under a
planId, kept ten minutes, and only that plan is carried out. What the server did not make, it does not touch.
Its tools: docs/reference/tools, written from the server itself. Built on
Snail.Sdk: the rules, the dotnet tool package, publishing into ~/.s3l-mcp, the
shared workflows.
dotnet publish src -c Release -r osx-arm64 -p:SnailMcpInstall=true # ~/.s3l-mcp/Snail.MCP.BuildBridge/current
Tools¶
| Tool | What it does |
|---|---|
build_hosts |
The hosts and what each can do right now: reachable, its toolchains with versions, its room. Changes nothing. |
build_provision |
Makes a host ready as a job: the root and its folders, the SDK and workloads under the root, the feeds, XcodeGen, the JDK and the Android SDK with its NDK, the images of the container kinds; names what a person installs or accepts — Xcode, OrbStack, Rosetta, sleep, the Android licences. |
build_run |
Delivers the copy and runs dotnet, xcodebuild, docker, npm or the repository's gradlew in its workspace as a job — or dotnet inside the host's Linux or Android image, or a script of the repository; answers the exit code, what the tests said, the log. |
build_logs |
The end of a run's log on this machine, while it runs or after. |
build_fetch |
Named paths of a workspace brought back: test results, a simulator bundle, a package. |
build_cancel |
Stops a running job, on the host too. |
build_sync |
A delivery on its own, or with dryRun what one would send. |
build_clean |
A sweep of a scope, planned and shown first, carried out by its planId. |
build_diagnose |
The server's state: version, hosts, the programs it works through, its folders. |
Every answer is JSON with an ok flag; a failure carries error, a hint when there is something to do, and is
flagged isError. A job answers within its wait with the result, or with the running job, whose resource
job://buildbridge/<kind>/<id> carries the result once it ends; a job that failed or was cancelled within the wait
answers as a failure that still carries its report. A run or a provisioning that could not happen — no working copy,
a host that does not answer, a delivery that broke off — ends its job failed with the error, a hint when there is
something to do, and the type of what stopped it; a build that ran and failed is a job that succeeded, its result saying
success false with the exit code and the log.
type is the word a program branches on, never the words of error:
type |
when |
|---|---|
arguments |
a word the call gave cannot be taken: a kind, a scope, a package, a variable, a fetch of nothing, a script not named, a workspace sweep with no copy |
outside |
a log out of the jobs folder, links followed; a script or a fetched path out of the workspace |
noPath |
build_logs with a blank log |
absent |
a log, a script or the gradle wrapper that is not there |
timeout |
a provisioning that ran past its time |
noHosts |
no host is configured |
noSuchHost |
a host the settings do not name |
noSuchJob |
a job this server does not know |
noSuchPlan |
a sweep plan never shown, carried out already, or shown too long ago |
unreachable |
a host that did not answer over ssh |
noToolchain |
a host without the toolchain the build needs: Xcode, Docker, the Android SDK, dotnet |
notACopy |
a path outside any git working copy |
notInstalled |
a program this machine lacks: git, rsync, ssh, mutagen |
noSecret |
a secret the keychain did not give |
noHome |
a host that did not say where its home is, so no container can be given the workspace |
notDelivered |
a copy that did not reach the host, by rsync or a Mutagen session |
notCollected |
paths that were not brought back |
notProvisioned |
a provisioning that broke off before it said what it saw to |
notSupplied |
packages, an SDK or workloads the host could not install |
noSimulator |
a simulator that could not be cloned |
notGenerated |
a project xcodegen did not generate |
notSurveyed |
a host that could not be surveyed for a sweep |
internal |
a failure nobody foresaw — the SDK's word |
A run¶
- The copy a path lies in is read as git sees it: root, repository, branch, commit, whether it is a linked worktree.
- The host is probed: reachable, and with the toolchain the kind needs —
dotnet,xcode,dockerfor thedockerandlinuxkinds, the Android toolchain under the root forgradleandandroid, which falls back todockerand the Android image; ascriptasks for nothing in advance. What a build needs beyond the host's comes with the build, not from the settings: the Android SDK packagesneedsnames —["platforms;android-37"]— are put under the root throughsdkmanagerbefore anything runs, and stay; anandroidbuild that fails for want of a platform, which XA5207 names, or of workloads, which NETSDK1147 names, gets them and runs again, once; the .NET SDK the copy'sglobal.jsonnames goes under the root when none there meets it under itsrollForwardrule; agradlebuild fetches the platforms, build tools and NDK its project names on its own, the licences being accepted. The settings only seed a new host. - When the host has less room than the settings allow, the caches are swept first.
- The copy is mirrored into
~/.s3l-build/workspaces/<repository>/<branch>/<repository>with rsync:.gitgoes along, what git ignores andbin,obj,artifacts,TestResults,node_modulesdo not; a tracked file deleted here is deleted there; outputs already there stay. A linked worktree goes without its.git, which would name nothing on the host. The copy's folder is named as the repository is, so a tool that reads a name from the root folder — git, Snail.Sdk's conformance — sees the same name there as here. A marker beside it,.s3l-build.json, is what proves the workspace the server's. The feeds the settings name are mirrored underfeeds/, each again only once it changed on this machine or an hour passed. WithSyncset tomutagen, a Mutagen session keeps the workspace mirrored as the copy changes — one-way, with the same ignores — and a run only waits for it to catch up. - The command runs in the workspace, its output streamed to a log under
~/.s3l-mcp-buildbridge/jobs/, whichbuild_logsreads. One workspace takes one run at a time; a second waits its turn. A run stopped from this side — cancelled, or past its time — is stopped on the host too. xcodebuildkeeps its derived data under the root, and each destination naming a simulator by name gets a clone of it for the run alone,snail-build-<word>, deleted when the run ends: name two destinations to test on an iPhone and an iPad in one run, side by side, asxcodebuildruns them. A project with aproject.ymlbeside it is generated on the host byxcodegenfirst: a generated project is what git ignores, so it never travels, and the spec does.docker buildanddocker runcarry the labelsnail.owner=buildbridge/<repository>/<branch>, which Snail.MCP.CleanUp reads; a compose stand is the projects3l-<repository>-<branch>.- the
androidkind runsdotneton the host, with the JDK, the Android SDK and its NDK under the root named throughJAVA_HOME,ANDROID_HOMEandANDROID_NDK_HOME, which dotnet's Android targets read;gradleruns the repository'sgradlewfrom its root the same way, with Gradle's own files undergradle/of the root;npmrunsnpmwith the root's Node —ci,test,run build,exec -- playwright install— for the tests of a site or an interface. - the command's environment carries what
environmentassigns,NAME=valuewords for what is no secret, and the secrets the settings name for the repository. A secret lives inconfig.jsonor in this machine's keychain and reaches the host's shell on its standard input, for the run alone: never a tool's argument, a job, the log or a file on the host;build_diagnosesays which names a run gets, never their values. A container run gets them by name,-e NAME, from that shell. - the
linuxkind runsdotnetinside the host'ss3l-build-dotnetimage, with the workspace mounted at/work, the root's packages at/root/.nuget/packagesand the feeds at/feeds, named by a NuGet configuration provisioning wrote undercontainers/: Linux targets, Native AOT for Linux and tests on Linux. A host without the Android toolchain takes anandroidrun the same way, in itss3l-build-androidimage whenImagesnames it — amd64, since the Android SDK's tools for Linux come for that architecture, and so under emulation on an Apple Silicon host, slowly by design. - the
scriptkind runs a script of the repository as it is —["tools/native/build-xcframework.sh", "Debug"]— through its own shebang, with the root's dotnet on its path: for what a build needs that no one program says, such as a core packed into a framework before anxcoderun. It must be executable, as git keeps it, and lie inside the copy. - The log is read for what the tests said, in the words of VSTest or of the testing platform.
- The repository's workspaces not built for 14 days, Xcode's derived data in its copies nothing wrote into for 7 days and test bundles there for 30 — a branch built every day is never stale, and what its builds leave in its copy is no delivery's to remove — derived data of workspaces that are gone, and the build cache not used for 6 hours are swept.
The host¶
A Mac with Remote Login on and this machine's key in its authorized_keys; ssh <address> from a terminal shows
what is wrong when a probe does not reach it. On it:
- Xcode of the same version as here, opened once, its licence accepted — for anything under Apple;
- OrbStack, started — for anything under Docker;
- a user logged in at the console, and the machine kept awake: simulators need the session, and a sleeping host takes no builds;
- Rosetta, on Apple Silicon: build tools still ship as x64 —
protocof Grpc.Tools among them — and installing it means agreeing to Apple's licence, whichbuild_provisiononly points at:softwareupdate --install-rosetta --agree-to-license; - the Android SDK licences accepted, once:
build_provisionputs the JDK and the command-line tools under the root and stops there with the command,sdkmanager --licenseswith the root's JDK and SDK named, which only a person runs; provisioned again, it installs the packages the settings name; - nothing else:
build_provisioninstalls the .NET SDK the settings name under~/.s3l-build/dotnetwith its workloads, keeps packages under~/.s3l-build/nuget, adds the mirrored feeds to the host's NuGet sources, and builds the images the settings name from the Dockerfiles under deploy/images, which it writes under~/.s3l-build/images— once; an image already there is kept, and a sweep of stale images leaves them alone. Where Xcode is, it also puts XcodeGen under~/.s3l-build/xcodegen, from the release zip the settings name, checked against its SHA-256 — rather than Homebrew, which would want a password. Node goes under the root the same way, from the release tarball the settings name intonode/, pointed at bynode/current, with npm's cache undernpm/and Playwright's browsers underplaywright/. The Android toolchain goes under the root the same way: a Temurin JDK intojdk/, pointed at byjdk/current, and the command-line tools intoandroid/, each from the release the settings name and checked against its SHA-256;sdkmanagerthen installs the packages the settings name — the platform tools, the platforms, the build tools and the NDK — intoandroid/, checking what it fetches itself. Every host of this server is Apple Silicon, which is all the JDK is fetched for. Gradle is not installed: a repository's wrapper fetches the Gradle it names, intogradle/under the root.
The account's login shell does not matter: every script runs in /bin/sh, with /usr/local/bin, /opt/homebrew/bin
and ~/.orbstack/bin on its path, which a non-interactive shell would not look in.
A host that is this machine — localhost — is worked without ssh, straight into a shell: what the tests use.
Settings¶
~/.config/s3l-mcp-buildbridge/config.json, under the SNAIL_MCP_BUILDBRIDGE_ variables, which win:
{
"Hosts": [
{ "Name": "mini", "Address": "orldev@mini.local" }
],
"SdkVersion": "10.0.302",
"Workloads": ["maui-ios", "maui-maccatalyst", "maui-android", "wasm-tools"],
"Feeds": [
{ "Name": "LocalPackages", "Path": "/Users/orldev/Projects/nuget" }
]
}
| Setting | Default | What it is |
|---|---|---|
Hosts |
none | Each a Name, an Address ssh is given, and a Root (~/.s3l-build); the first is the one a call that names none gets. |
SdkVersion |
10.0.302 |
The .NET SDK provisioning installs under the root; empty leaves the host's own dotnet. |
Workloads |
the MAUI set | The workloads that SDK gets. |
Feeds |
none | NuGet feeds of this machine mirrored to the host and added to its sources by name. |
Images |
dotnet |
The images provisioning builds for the container kinds; android names the Android image, for a host without the toolchain; an empty list builds none. |
HasAndroid, JdkVersion, JdkSha256 |
true, 21.0.13+9, its SHA-256 |
Whether provisioning puts the Android toolchain under the root, which Temurin release, and the checksum its macOS arm64 tarball must match; an empty checksum checks nothing. |
HasNode, NodeVersion, NodeSha256 |
true, 26.13.0, its SHA-256 |
Whether provisioning puts Node under the root, which release, and the checksum its macOS arm64 tarball must match; an empty checksum checks nothing. |
Secrets |
none | Each a Name, a Value or the Keychain service of a generic password on this machine (one of the two), and a Repository whose runs get it, every repository when empty. |
AndroidToolsBuild, AndroidToolsSha256, AndroidPackages |
11076708, its SHA-256, the platform tools, platforms 36 and 35, build tools 36.0.0, NDK r28c |
The build of the command-line tools, the checksum its macOS zip must match, and the packages sdkmanager installs, as it names them. |
HasXcodeGen, XcodeGenVersion, XcodeGenSha256 |
true, 2.46.0, its SHA-256 |
Whether provisioning puts XcodeGen under the root of a host that has Xcode, which release, and the checksum its zip must match; an empty checksum checks nothing. |
Sync |
rsync |
What carries a copy: rsync, a mirror before every run, or mutagen, a session per workspace that keeps it mirrored; Mutagen names the program. |
Excludes |
bin obj artifacts TestResults BenchmarkDotNet.Artifacts node_modules .DS_Store |
Folders a delivery never sends. |
TransferSeconds, RunSeconds, ProbeSeconds |
600, 3600, 20 | How long a delivery, a run, a probe may take. |
WorkspaceDays, JobDays, ImageDays, BuildCacheHours, OutputDays, ResultDays |
14, 30, 7, 6, 7, 30 | The ages a sweep goes by; ResultDays is for test bundles, what a test run found. |
SessionsAwake |
30 | The most Mutagen sessions kept awake at once, each holding one of the 42 connections a Mac's sshd has; a delivery that makes one more pauses the one used longest ago. Zero or less sets no limit. |
ProbeKeepSeconds |
60 | Seconds a host's answer to a probe is gone by before a run probes it again; build_hosts always probes. Zero or less probes before every run. |
SshShareMinutes |
30 | Minutes the connection to a host stays open after its last command, every command to that host going over it (ControlMaster, its socket ~/.ssh/s3l-<hash>): a step is one more session on it, not one more handshake the host's sshd may turn away. Zero or less opens a connection for each command. |
SessionIdleMinutes |
30 | Minutes a workspace may go without a delivery or a build before its Mutagen session is paused, holding no connection to the host; the next delivery resumes it. Zero or less never pauses one. |
SweepMinutes |
10 | Minutes between two sweeps after a run of one repository on one host: a run within them ends without surveying the host. Zero or less sweeps after every run. |
CachesSweepHours |
24 | Hours between two sweeps of the whole caches scope carried out by themselves after a run. Zero or less leaves that scope to build_clean and to a host short of room. |
IdleTimeoutMinutes |
60 | Minutes without an MCP message after which the server stops, unless a job is running: a client lost without closing its input leaves no process behind. Zero or less never stops it. |
LowDiskGigabytes |
20 | Free gigabytes on a host below which a run sweeps the caches first. |
A setting the server cannot use stops it at the start, in one line on stderr and exit code 1, that names the variable,
its key in the settings file, the value and what it can be — a host's under its index, SNAIL_MCP_BUILDBRIDGE_HOSTS__0__ADDRESS:
SNAIL_MCP_BUILDBRIDGE_RUN_SECONDS (or RunSeconds in the settings file) is '0'; it is a number of seconds above zero.
What is swept, and when¶
A sweep after a run goes by ages alone and measures no sizes, and runs once in SweepMinutes for a repository on a
host. Once in CachesSweepHours the sweep after a run is the whole caches scope, every repository's, so a host is
kept tidy without anyone asking; a host met for the first time waits those hours out. everything is never carried
out by itself: it removes every workspace, and the next build of each starts from nothing. build_clean surveys with
sizes, shows its plan and carries out only what it showed.
| What | Proof it is the server's | Goes when |
|---|---|---|
| a workspace | its marker | not built for WorkspaceDays, after a run of its repository; its scope asked for; caches, everything |
| derived data | named for a workspace | its workspace is gone; everything |
| images a run made | the label snail.owner |
older than ImageDays in caches; all in everything |
| the images of the container kinds | the label snail.image |
everything only |
| Xcode's derived data inside a copy | inside a workspace with its marker | nothing written into it for OutputDays, after a run of its repository; caches |
a test bundle (.xcresult) inside a copy |
inside a workspace with its marker | nothing written into it for ResultDays, after a run of its repository; caches |
| the build cache | shared | entries not used for BuildCacheHours, after every run and in caches; all in everything |
| the packages, Gradle's files, npm's cache and Playwright's browsers under the root | under the root | everything only |
| an SDK under the root | under the root | no settings and no workspace's global.json name it; caches |
| build tools and NDKs | under the root | older than the newest, unless the settings name them; caches |
| toolchain images the settings do not name | the label snail.image and the tag |
caches |
| logs on this machine | under the server's data folder | older than JobDays |
| a Mutagen session whose copy is gone from this machine | the label s3l.shape and the name |
after every run; caches, everything |
| the connection of a Mutagen session whose workspace is left alone | the label s3l.shape and the name |
paused, not removed, once the workspace went SessionIdleMinutes without a delivery or a build, after every run; its next delivery resumes it |
The SDK under the root stays: a sweep never costs a download. To start over, erase ~/.s3l-build and provision again.
A Mutagen session goes with its workspace; mutagen sync list on this machine shows the ones there are, named
s3l-<repository>-<branch>-<host>.
When the host turns connections away¶
A Mac's sshd is started by launchd for each connection and takes forty-two handshakes at a time; MaxStartups and
PerSourcePenalties in sshd_config belong to a listening daemon and do nothing there. Every Mutagen session holds a
connection and reconnects when the host's sshd restarts — switching Remote Login off and on does it — so fifty sessions
reconnecting at once get Connection closed by … port 22 before the greeting, and so does anything else that connects
in that minute. Sessions that are awake can also hold all forty-two connections, and then the host closes every new
one until some let go. Five things keep a run out of it: no more than SessionsAwake sessions are awake at once; when the host turns a probe away, every session of this
server is paused and the probe is made again; sessions of workspaces left alone are paused after a run, so the
connections held are those of the copies being worked on; every short command of this server goes over one shared connection and builds over three more of theirs; and a
command turned away before the greeting — it never started — is run again after 2, 5 and 10 seconds.
Run it¶
Add it to an MCP client — Claude Code's ~/.claude.json:
{
"mcpServers": {
"s3l-mcp-buildbridge": { "command": "/Users/<you>/.s3l-mcp/Snail.MCP.BuildBridge/current/Snail.MCP.BuildBridge" }
}
}
or install the tool — dotnet tool install -g Snail.MCP.BuildBridge, or dnx Snail.MCP.BuildBridge --yes without
installing — and use s3l-mcp-buildbridge as the command: on macOS and Linux it is the native program. Windows is
not served: the server works through /bin/sh, ssh and rsync, so no win-x64 package is made.