Native Binary
Karandash ships as a self-contained native binary compiled with Kotlin/Native. No JVM required.
Overview
The native binary is the primary distribution target. It is compiled ahead-of-time for each platform using Kotlin/Native (LLVM backend) and requires no Java runtime.
Characteristics:
- Single executable file, no runtime dependencies
- Sub-100ms cold startup (benchmark: ~50ms on macOS ARM64)
- Supports all plugin types: native (
.dylib/.so/.dll), JavaScript (.mjsvia QuickJS), WASM (.wasmvia Chasm, compiled in), and JAR (via subprocess bridge, requires Java 17+)
Supported Platforms
| Platform | Target | File |
|---|---|---|
| macOS Apple Silicon | macosArm64 |
cli.kexe |
| macOS Intel | macosX64 |
cli.kexe |
| Linux x64 | linuxX64 |
cli.kexe |
| Windows x64 | mingwX64 |
cli.exe |
Downloading
Download the pre-built binary for your platform from the releases page.
Each release also ships SHA256SUMS; verify a download with grep ' karandash-linux-x64$' SHA256SUMS | sha256sum -c - (use shasum -a 256 -c on macOS).
macOS ARM64 (Apple Silicon)
curl -L https://github.com/appKODE/karandash/releases/latest/download/karandash-macos-arm64 \
-o karandash
chmod +x karandash
sudo mv karandash /usr/local/bin/
karandash --version
macOS x64 (Intel)
curl -L https://github.com/appKODE/karandash/releases/latest/download/karandash-macos-x64 \
-o karandash
chmod +x karandash
sudo mv karandash /usr/local/bin/
karandash --version
Linux x64
curl -L https://github.com/appKODE/karandash/releases/latest/download/karandash-linux-x64 \
-o karandash
chmod +x karandash
sudo mv karandash /usr/local/bin/
karandash --version
Windows x64
Download karandash-windows-x64.exe from the releases page and add it to your PATH.
Building from Source
Prerequisites
- JDK 17+ (required to run Gradle; not needed at runtime)
- Gradle wrapper (
./gradlew) included in the repository - macOS: Xcode Command Line Tools (
xcode-select --install) - Linux: OpenSSL headers (
sudo apt-get install libssl-dev)
All commands run from the karandash/ directory.
Build for macOS ARM64
./gradlew :cli:linkReleaseExecutableMacosArm64
Output: cli/build/bin/macosArm64/releaseExecutable/cli.kexe
Build for macOS x64
./gradlew :cli:linkReleaseExecutableMacosX64
Output: cli/build/bin/macosX64/releaseExecutable/cli.kexe
Build for Linux x64
./gradlew :cli:linkReleaseExecutableLinuxX64
Output: cli/build/bin/linuxX64/releaseExecutable/cli.kexe
Build for Windows x64
./gradlew :cli:linkReleaseExecutableMingwX64
Output: cli/build/bin/mingwX64/releaseExecutable/cli.exe
Debug builds
Add Debug instead of Release to get an unoptimized binary with debug symbols:
./gradlew :cli:linkDebugExecutableMacosArm64
# Output: cli/build/bin/macosArm64/debugExecutable/cli.kexe
Testing the Binary
# Check version
./cli/build/bin/macosArm64/releaseExecutable/cli.kexe --version
# Validate a merge request
./cli/build/bin/macosArm64/releaseExecutable/cli.kexe validate \
--platform gitlab \
--project my-group/my-repo \
--mr 42
Native Tests
# Run native tests on macOS ARM64
./gradlew macosArm64Test
# macOS x64 tests (disabled by default on Apple Silicon)
./gradlew macosX64Test -Pkarandash.tests.includeMacosX64=true
Plugin Support
The native binary supports all four plugin types. JAR plugins are loaded via a subprocess bridge that spawns a JVM process; Java 17+ must be available on PATH or JAVA_HOME.
| Plugin type | Supported | Loaded via |
|---|---|---|
Native (.dylib/.so/.dll) |
Yes | dlopen |
JavaScript (.mjs) |
Yes | QuickJS (embedded) |
WASM (.wasm) |
Yes | Chasm (pure Kotlin, compiled in) |
| JVM JAR | Yes (requires Java 17+) | subprocess bridge (JarBridgeServer) |
The macOS x64 binary runs WASM on Chasm 1.7.0 (Chasm 2.x publishes no macosX64 build); the other native binaries run Chasm 2.2.0. A 1.7.0 store cannot be interrupted: a WASM call or start function that overruns its time limit still fails at the limit and the plugin is abandoned, but its guest thread keeps running until the process exits.
CI/CD Integration
GitHub Actions
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Download Karandash
run: |
curl -L https://github.com/appKODE/karandash/releases/latest/download/karandash-linux-x64 \
-o karandash
chmod +x karandash
- name: Validate MR
run: ./karandash validate
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
GitLab CI
validate:mr:
stage: test
script:
- curl -L https://github.com/appKODE/karandash/releases/latest/download/karandash-linux-x64
-o karandash
- chmod +x karandash
- ./karandash validate
rules:
- if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
Cross-Compilation
Kotlin/Native supports limited cross-compilation. Building a Linux binary from macOS works for most cases but requires the Kotlin/Native toolchain to download sysroots automatically.
Building Windows binaries from macOS or Linux requires the MinGW toolchain:
brew install mingw-w64 # macOS
Clear the Kotlin/Native cache if cross-compilation fails:
rm -rf ~/.konan
./gradlew :cli:linkReleaseExecutableLinuxX64
Troubleshooting
"OpenSSL not found" on Linux
sudo apt-get install libssl-dev
# or on RPM-based distros:
sudo dnf install openssl-devel
"OpenSSL not found" on macOS
brew install openssl@3
export LDFLAGS="-L$(brew --prefix openssl@3)/lib"
export CPPFLAGS="-I$(brew --prefix openssl@3)/include"
./gradlew :cli:linkReleaseExecutableMacosArm64
"TLS verification failed" for a private CA or self-signed server
The macOS and Linux binaries trust their built-in CA bundle. To trust a corporate CA or a self-signed
certificate (a self-hosted GitLab, a remote extends: server, a private plugin registry), point
SSL_CERT_FILE (or CURL_CA_BUNDLE) at a PEM bundle that contains it. The file replaces the default bundle, so
include the public CAs too if you also reach public hosts:
SSL_CERT_FILE=/etc/ssl/corp-ca-bundle.pem karandash validate --pr <url>
The JVM distribution uses the Java truststore instead (-Djavax.net.ssl.trustStore=...).
Reaching a server by IP while its DNS is down
A certificate names the host, not its IP, so https://<ip>/... fails TLS verification. For a manual run,
KARANDASH_TLS_INSECURE_HOSTS lists hosts whose certificates are not checked:
KARANDASH_TLS_INSECURE_HOSTS=203.0.113.10 karandash validate --pr https://203.0.113.10/group/project/-/merge_requests/1
Only the platform client keyed for those hosts skips verification; AI providers and every other host are still
verified, and that client refuses requests and redirects to any unlisted host. Anyone on the network path can read
the unverified traffic, token included, so prefer an /etc/hosts entry (<ip> <host name>), which keeps
verification on, and never set the variable in CI. Windows ignores it.
macOS: "cannot be opened because the developer cannot be verified"
The binary downloaded from releases is not notarized. Remove the quarantine attribute:
xattr -d com.apple.quarantine /usr/local/bin/karandash
Builds from source are not affected.