Install

Signed installers, Homebrew, and bootstrap scripts for macOS, Windows, and Linux.

Private maintainer document. The public quick start is in README.md and skilakmesh.com/download. This file defines what maintainers must prove before those instructions are marketed as ready.

Skilak Mesh has one public native release with platform-specific signed bytes. No GitHub login or access to the private repositories is allowed during an end user install.

Supported install routes

Unsupported CPU or OS combinations must stop with an explicit error. The release currently has no Linux arm64 package, 32-bit package, Windows arm64 package, or macOS version older than 13.

The stable bootstrap scripts are byte-for-byte copies of the sealed release inputs. They select immutable artifacts below:

https://downloads.skilakmesh.com/releases/vMAJOR.MINOR.PATCH/

They never download release bytes from the private core repository or SkilakLabs/releases.

What installation does

All native routes install one versioned program tree, a stable smesh launcher, an install receipt, and a per-user automatic-start definition. Installation does not accept legal documents, choose a policy, connect an AI client, or send a provider request. Those actions belong to guided first run.

The installers:

• validate the current account and reject unsafe path/symlink/reparse-point layouts;
• verify the selected release hash before activation; offline installs also verify the platform checksum manifest’s Sigstore provenance;
• install only in the current user’s supported locations;
• preserve an existing version when its bytes match and refuse unrecognized contents rather than deleting them;
• install the background-service definition but do not silently route an AI client; and
• write a receipt used for safe upgrade and uninstall.

On Windows, that receipt records the verified SHA-256 of the installed PowerShell uninstaller as ownership metadata. It contains no secret or user data; the hash lets cleanup distinguish the installer-owned file from an unrelated or modified script before removal.

The POSIX installer never edits .zshrc, .bashrc, or another shell startup file. If its launcher directory is absent from PATH, it explains the exact directory. A noninteractive install to the default directory completes and prints the exact launcher command; an explicitly chosen custom launcher directory still requires confirmation. The installer never claims that a fresh terminal can resolve smesh when it cannot.

Canonical per-user layout

User configuration is separate from program files:

• macOS and Linux: ~/.config/skilakmesh
• Windows: %APPDATA%\SkilakMesh

Runtime data is also separate:

• macOS: ~/Library/Application Support/SkilakMesh
• Linux native package: ~/.local/share/SkilakMesh
• Windows: %LOCALAPPDATA%\SkilakMesh

Uninstall preserves configuration, terms acceptance, secrets, and audit data unless --purge-user-data is explicitly selected.

macOS

Homebrew

brew install skilaklabs/tap/smesh
smesh init

The formula chooses the arm64 or x86-64 CLI archive using Homebrew’s measured architecture and verifies the immutable SHA-256 before installation. It does not build the private source tree.

Before removing the formula, restore client routes and stop/unregister the service while the program files still exist:

smesh uninstall --keep-program-files
brew uninstall smesh

To remove retained user data as well:

smesh uninstall --keep-program-files --purge-user-data
brew uninstall smesh

DMG

1. Download the architecture-specific DMG from https://skilakmesh.com/download.
2. Open it and drag Skilak Mesh to Applications.
3. Eject the disk image.
4. Open the installed application, not the copy on the mounted DMG.

The installed app is not supposed to do nothing. On first launch it opens the guided setup in Terminal. After setup it presents a small protection/status UI, service recovery actions, and a command-line-tool action. If it is launched from the DMG or another unsupported location, it asks the user to install it in Applications first.

The DMG does not silently create /usr/local/bin/smesh. After the first successful guided setup, the app offers Command-Line Tools… immediately; you can choose Copy Install Command and run the copied administrator command in Terminal. The same action remains available from the protection panel. Until it succeeds, typing smesh may correctly produce command not found; smesh doctor reports that the installed CLI is not reachable by name.

The install.sh macOS route is CLI-only and does not install the app bundle. Use it only when that tradeoff is intentional.

macOS can display a Login Items approval. The item must identify the signed Skilak Mesh app, not a generic env, bash, or unidentified-developer item. Guided setup waits for approval and must report a clear recovery action if macOS does not enable it.

Windows

Public PowerShell bootstrap

From a normal per-user PowerShell session:

irm https://skilakmesh.com/install.ps1 | iex

The finalized bootstrap downloads the immutable setup EXE, verifies its SHA-256, verifies the exact expected Authenticode publisher and timestamp, then runs the setup route. It refuses an unsigned setup, a wrong publisher, a changed digest, an unsupported architecture, or an unfinalized release identity.

The installer asks before adding the per-user launcher directory to PATH. Open a new terminal after a PATH change and require:

smesh version

Setup EXE

The download page exposes the same signed setup EXE. Its signature must show the expected Skilak publisher rather than Unknown publisher. It installs the same native tree, launcher, scheduled task, receipt, and Installed Apps entry as the PowerShell route.

Task registration requires a logged-in desktop user. The direct installer accepts -SkipServiceRegistration only together with -SourceDirectory for an offline headless package check. Online installs reject skip mode, and the offline check is not a substitute for release acceptance on a Windows desktop or VM.

Use Installed Apps > Skilak Mesh > Uninstall or the installed uninstaller. The final acceptance check must prove the program root, scheduled task, launcher/PATH entry owned by the installer, and Installed Apps record are all removed. A second uninstall must be harmless.

Linux

curl -fsSL https://skilakmesh.com/install.sh | sh

The shared script requires Linux x86-64. For an online install it downloads the versioned archive and verifies the immutable SHA-256 embedded when that exact bootstrap was sealed. The release also publishes the build record, Linux checksum manifest, and Sigstore bundle; --source-dir offline installs require and verify that complete set. The public release baseline is Ubuntu 24.04 with glibc 2.39; a newer or different distribution is not supported merely because the archive happens to start there.

If ~/.local/bin is not on PATH, review the printed instruction and add it through the user’s normal shell configuration. The installer itself does not make that edit.

The service is a systemd user service. Login/session behavior must be tested with the actual supported Linux environment; a passing archive self-check alone does not prove background startup.

Guided first run

For a CLI installation, run:

smesh init

For the DMG, opening the installed app starts the same guided flow in Terminal. The guided flow is designed to:

1. show the product identity and legal documents with their website links;
2. require one combined acceptance only after the user reviews those documents;
3. explain personal and evaluation usage in plain language and refuse commercial setup without an entitlement;
4. choose a protection profile and attachment behavior;
5. list only client integrations actually detected and supported;
6. preview the selected client changes;
7. save configuration and legal acknowledgement;
8. start and health-check the per-user background service;
9. connect only the clients the user selected; and
10. report exactly what is installed, configured, routed, running, and still untested.

The normal guided flow starts the service itself. smesh start is a recovery and later control, not something a successful first-run user should have to guess.

After success it must say that Skilak Mesh runs in the background, starts after login, and continues after Terminal closes. Verify independently:

smesh status
smesh client list

Fully quit and reopen each connected client so it loads the saved route. Setup does not send a live provider request, so it must not claim live protection until traffic has actually been observed.

Usage choices and legal acceptance

• Personal/individual means the checked-in license’s permitted personal use by a natural person.
• Evaluation means non-production evaluation, development, testing, or research within the checked-in grant.
• Commercial/organization production requires a separate entitlement and must not be enabled by choosing a CLI word.

These descriptions summarize the current checked-in documents; LICENSE and a signed commercial agreement are authoritative. The BUSL-versus-BSL launch decision is still pending owner/counsel approval. Do not change the license or terms as an installation shortcut.

Noninteractive setup deliberately has no generic legal --yes. It requires explicit document identifiers and an allowed usage class. That route is for a reviewed managed deployment, not for bypassing guided acceptance.

Client coverage

Automatic configuration currently supports:

• Claude Code CLI; and
• Codex CLI and integrations that use the same Codex configuration.

Detection of a desktop application is not proof it can be routed. Installing Skilak Mesh does not automatically protect ChatGPT Desktop, Claude Desktop, Gemini, AnythingLLM, a browser, or an arbitrary AI application. See docs/AI-FLOW-COVERAGE.md and docs/SETUP-PER-CLIENT.md for the exact current matrix.

To pause routed clients before maintenance:

smesh client pause

Resume only after the gateway is healthy:

smesh status
smesh client resume

Never stop the local service while clients are still saved to its loopback URL. That leaves those clients pointing at a closed port.

Status, logs, and service control

smesh status
smesh doctor
smesh logs
smesh start
smesh stop

The native public install has no required web dashboard. smesh logs and the macOS app’s protection/status panel are the supported local views. The optional enterprise dashboard in the source tree is a separate deployment surface and must not be promised by the native installer.

Operational logs and audit records are local and payload-free by design. Do not paste a real credential into a provider session to test blocking; use only the documented synthetic acceptance fixtures.

Upgrade and uninstall

Installing a higher released version stages a new versioned tree and moves the stable launcher only after verification. Do not overwrite a version directory in place and do not use --activate-only unless that exact version already has a verified receipt.

Before uninstall, pause or disconnect managed clients so their original routes can be restored while the program still exists:

smesh client pause
smesh uninstall --yes

To remove retained configuration, acceptance, secrets, and audit data:

smesh uninstall --purge-user-data --yes

Homebrew uses the --keep-program-files sequence described above. Windows may also be removed through Installed Apps. After any route, require a clean second uninstall and verify that no managed client still points to 127.0.0.1:51737.

Hosted release acceptance

The tag promoter downloads the public, versioned bytes—not the Actions artifact copy—and performs these clean checks before it updates the public source/tap and stable aliases:

• Linux: install, native identity, containment, enforcement, uninstall, and residue checks on ubuntu-24.04.
• Windows: finalized install.ps1, signed setup, identity, containment, enforcement, uninstall, and registry residue checks on windows-2025.
• macOS arm64 and Intel: platform-selected CLI install and uninstall, then the exact architecture DMG app/controller checks.
• Homebrew arm64 and Intel: install the sealed formula, execute the native CLI, perform service-aware uninstall, and remove the formula.

Those checks prove the hosted routes and clean runners. They do not prove the complete user experience on the owner’s machines.

Physical launch acceptance

Do not market a release until all three available environments pass. Record the OS version, architecture, install route, elapsed timings, and result without recording secrets or personal data.

Every platform

1. Start with no GitHub authentication and no previous Skilak Mesh program, service, receipt, launcher, or client route.
2. Install using the first-screen public command or DMG/EXE.
3. Open a new terminal and prove smesh version works without a full app-bundle path.
4. Complete guided setup, read the linked legal documents, choose personal or evaluation use, and connect only a testable supported client.
5. Require smesh status to report healthy and automatic startup enabled.
6. Quit and reopen the connected client. Run an operator-owned, credential- isolated benign request and compare end-to-end latency with the same client direct. Unexpected multi-second proxy overhead is a release blocker.
7. Use documented fake secret fixtures to prove a block and a normal benign prompt to prove allowed traffic. Record the rule/result, not the payload.
8. Pause and resume client routing; require a safe direct interval and exact restoration.
9. Restart the computer, sign in, close Terminal, and prove the service becomes healthy without another init or manual start.
10. Upgrade or reinstall the same version and prove idempotence.
11. Uninstall, verify client restoration and all program/service/launcher residue, then run uninstall a second time.

Live provider checks are operator-owned. Automated or agent-run validation must keep provider aliases on closed or captured loopback endpoints.

MacBook additions

• Test the correct DMG for the Mac’s measured architecture.
• Confirm the mounted DMG has branded artwork, product icon, drag arrow, and Applications target.
• Confirm the installed app icon is branded.
• Double-click the installed app before setup and require guided setup to open; after setup require the protection/status panel.
• Confirm the Login Item names the signed product and is not shown as env, bash, or an unidentified developer.
• Test Homebrew separately from the DMG.

Windows VM additions

• Confirm Explorer and the setup UI show the expected publisher.
• Confirm SmartScreen does not report an unknown publisher.
• Verify both the setup EXE and install.ps1 routes.
• Confirm the Installed Apps entry, scheduled task, PATH ownership, restart behavior, and complete uninstall residue.

Linux machine additions

• Confirm the actual distribution and glibc baseline are supported.
• Confirm the systemd user unit survives logout/login as documented for that environment.
• Confirm the launcher is available in a fresh login shell.

Any failure remains a release blocker. Fix it in the private core repository, create a new sealed candidate, and release a higher version; never replace a published version’s bytes.

Source file: INSTALL.md in SkilakLabs/mesh.