Marathon

An installable Electron app for running JavaScript and TypeScript snippets locally.

Commands

• npm install
• npm run dev
• npm run dist

npm run dist builds the renderer with Vite and creates installable artifacts in release/.

The GitHub Releases tab can be the only download surface. Once a tagged workflow finishes, users can download the compiled macOS, Windows, and Linux artifacts directly from the Releases page.

You can still use this release flow without Apple Developer enrollment or Windows signing certificates. In that case, GitHub Releases will still get downloadable build artifacts, but macOS and Windows users will see stronger OS trust warnings because those builds are unsigned or unnotarized.

What You Need Right Now

To have downloadable executable files appear in the GitHub Releases tab, you only need:

1. Push this repository to GitHub.
2. Make sure GitHub Actions is enabled for the repo.
3. Push a version tag, for example:
   • git tag v0.1.0
   • git push origin v0.1.0
4. Wait for the workflow in release.yml to finish.
5. Open the GitHub Releases page and download the generated artifacts.

That is enough to get:

• macOS .dmg and .zip
• Windows .exe
• Linux .AppImage and .deb
• SHA256SUMS-<platform>.txt checksum files

No Apple Developer account is required for that basic release flow.

Tradeoffs Without Apple Enrollment

If you are not enrolled in the Apple Developer Program yet:

• macOS builds will not be Developer ID signed.
• macOS builds will not be notarized.
• Users will see Gatekeeper warnings when opening the app.
• Some users may need to right-click the app and choose Open, or allow it manually in System Settings.
• The app will feel less trustworthy to end users than a notarized build.

If you also do not have a Windows signing certificate:

• Windows builds will still be downloadable.
• Users will see SmartScreen or publisher warnings before opening the installer.

Linux is the least affected:

• Linux artifacts can still be released normally.
• Linux distribution usually does not depend on the same signing and notarization flow as macOS and Windows.

Security model

• User code runs in a dedicated Web Worker, not in the Electron main process.
• The Electron window uses contextIsolation, sandbox, and nodeIntegration: false.
• The app denies all permission prompts.
• The app blocks in-app navigation, popups, and webview attachment.
• Outbound network requests are blocked for packaged builds and disabled inside the code runner.
• The sandbox disables fetch, XMLHttpRequest, WebSocket, EventSource, nested workers, importScripts, and persistent browser storage APIs.
• The runner enforces a 5 second execution timeout, source size and line limits, transpiled output limits, timer caps, and output limits to reduce abuse and accidental lockups.
• If the renderer hangs or crashes, the Electron window reloads or recreates itself instead of leaving the app dead.

Public release checklist

1. Build each platform on its native OS, or use CI runners for macOS, Windows, and Linux.
2. Review the generated icon assets in build/ before publishing.
3. Optional but recommended: sign the app:
   • macOS: Apple Developer ID Application certificate, then notarize the .app/.dmg
   • Windows: Authenticode code signing certificate
4. Test the packaged artifacts, not just npm run dev.
5. Publish the GitHub Release artifacts.

GitHub Actions release flow

• Push a tag like v0.1.0 to trigger release.yml.
• The workflow builds on macOS, Windows, and Linux runners.
• electron-builder publishes release assets directly to GitHub Releases through GH_TOKEN.
• The macOS build signs with MACOS_CSC_LINK and MACOS_CSC_KEY_PASSWORD, then notarizes with APPLE_ID, APPLE_APP_SPECIFIC_PASSWORD, and APPLE_TEAM_ID.
• The Windows build signs with WINDOWS_CSC_LINK and WINDOWS_CSC_KEY_PASSWORD.
• Linux artifacts are built automatically, but standard Electron Linux targets are usually distributed unsigned.
• Each platform job also uploads a SHA256SUMS-<platform>.txt file to the same GitHub Release.
• If signing secrets are missing, the workflow still publishes unsigned artifacts instead of failing.

If You Add Signing Later

Once you are enrolled in the Apple Developer Program, add these GitHub repository secrets:

• MACOS_CSC_LINK
• MACOS_CSC_KEY_PASSWORD
• APPLE_ID
• APPLE_APP_SPECIFIC_PASSWORD
• APPLE_TEAM_ID

If you later buy a Windows code-signing certificate, add:

• WINDOWS_CSC_LINK
• WINDOWS_CSC_KEY_PASSWORD

After those secrets are present, the same tagged release flow will start producing signed and, on macOS, notarized builds automatically.

Required GitHub secrets

• MACOS_CSC_LINK: Base64 or file URL for the Developer ID Application certificate.
• MACOS_CSC_KEY_PASSWORD: Password for the macOS signing certificate.
• WINDOWS_CSC_LINK: Base64 or file URL for the Windows Authenticode certificate.
• WINDOWS_CSC_KEY_PASSWORD: Password for the Windows signing certificate.
• APPLE_ID: Apple ID used for notarization.
• APPLE_APP_SPECIFIC_PASSWORD: App-specific password for that Apple ID.
• APPLE_TEAM_ID: Apple Developer team identifier.

The notarization hook lives in scripts/notarize.js and the hardened runtime entitlements are in entitlements.mac.plist.

Branding

• The packaged app name is Marathon.
• The temporary release icon is generated from icon.svg into build/icon.png during npm run build.

Remaining limitations

• This is a local practice sandbox, not a secure environment for running untrusted third-party code.
• Very large TypeScript inputs can still stress the renderer before execution begins because transpilation happens in the renderer process.
• Unsigned macOS builds will trigger Gatekeeper warnings, and unsigned Windows builds will trigger SmartScreen warnings.