Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.
Release runbook
Do not publish a signed Akeru Bot build until qualified legal counsel approves the current Terms of Use and Privacy Policy versions in
packages/contracts/src/settings.ts.
For Akeru Bot maintainers.
Pull requests and stable releases
Every ordinary pull request commits a release decision. Run pnpm changeset for a shipped change,
select one product package, choose patch, minor, or major, and write a concise user-facing
summary. Use pnpm changeset --empty for documentation, tests, refactors, and internal tooling.
The four product packages (akeru-bot, desktop, web, and contracts) are a fixed group and always
receive the same version. Packages without versions remain outside the release train.
After changes reach main, the Version packages workflow runs pnpm release:version, force-pushes
the result to changeset-release/main, and creates or refreshes one Version Packages pull request
with gh. Changesets combines the pending release levels, updates all four manifests and
changelogs, and consumes the changeset files. The pull request body lists the new changelog section
of every package that changed. Merging this pull request is the deliberate stable release button. That merge
starts the native builds, verifies every artifact, creates the vX.Y.Z tag, and creates the stable
GitHub Release. Ordinary feature merges do not release immediately, and this flow does not publish
the akeru-bot npm package. CI rejects stable-version edits from every PR except the authenticated,
repository-owned Changesets PR.
Before merging the Version Packages pull request, refresh the bundled model catalog with
node apps/server/scripts/sync-model-catalog.ts and commit any change. Running servers fetch
models.dev on their own; the bundle only covers first launch and offline environments.
Releases from before the catalog still read apps/server/src/provider/model-manifest.json from
main to decide which models are current. When a model release changes the current lineup, update
that file's currentModels lists to match the new catalog in the same commit.
Nightly releases
GitHub Actions checks main at minute 17 every three hours. If main has not advanced since the
latest successful nightly, the workflow exits without building. Otherwise it creates a semver
prerelease version containing the workflow run, retry number, and commit SHA, then builds the same
macOS arm64, Windows x64, and Linux x64 desktop artifacts. The GitHub Release is marked as a
prerelease and latest=false, so installers and update checks that follow the latest stable release
do not switch to nightly builds. Nightlies neither edit committed package versions nor consume
stable changesets. A failed run creates no release; a rerun uses a new collision-safe version.
Manual smoke build
.github/workflows/release-smoke.yml validates release inputs without publishing or releasing
anything. Dispatch it from GitHub Actions with a version such as 0.0.0-smoke.0.
What it checks
- Public dependencies install from the committed lockfile. No dependency may resolve through a local path outside the repository.
- The release configuration passes
scripts/release-smoke.ts. - macOS builds one arm64 DMG with the
dev.leodoes.akerubundle identifier. - Unsigned macOS builds use a sealed ad-hoc signature. The workflow verifies the signature and the
dev.leodoes.akeruidentifier. - Signed macOS builds use a Developer ID Application certificate. Electron-builder submits and staples the app before it packages the DMG. The workflow submits and staples the DMG separately.
- Signed apps include the Electron hardened-runtime and microphone entitlements. The workflow
validates the notarization tickets, then runs
codesignandspctl. - Windows builds one unsigned x64 NSIS installer.
- Linux builds one unsigned x64 AppImage.
- The CLI build includes the web client, then completes a package publish dry-run.
- The marketing site passes its type check and production build.
Each desktop job uploads its artifact to the workflow run for seven days. The workflow does not create tags, create GitHub releases, publish npm packages, deploy a site, update AUR, or send release announcements.
Runner setup
CI and release workflows run through GitHub Actions. Tenki provides Linux runners. GitHub provides
the Apple Silicon macOS and Windows runners. The Tenki Runner GitHub App must have access to
opencoredev/akeru-bot.
- Linux uses the 4-vCPU
tenki-standard-medium-4c-8grunner. - Windows uses the GitHub-hosted
windows-2025runner. - macOS uses the GitHub-hosted Apple Silicon
macos-15runner.
macOS secrets
The stable release fails before building when the macOS secrets are absent, so an unsigned DMG can never publish as the latest stable release. Scheduled nightlies still build the sealed, ad-hoc-signed fallback without secrets. A partial secret configuration stops every channel.
Add these GitHub Actions secrets to publish a Developer ID signed and notarized DMG:
MACOS_CERTIFICATE_P12contains the base64-encoded.p12export of the Developer ID Application certificate and its private key.MACOS_CERTIFICATE_PASSWORDcontains the.p12export password.MACOS_SIGNING_IDENTITYcontains the full certificate identity. It must start withDeveloper ID Application:.APPSTORE_API_KEY_P8contains the App Store Connect API private key text.APPSTORE_API_KEY_IDcontains the API key ID.APPSTORE_ISSUER_IDcontains the App Store Connect issuer ID.
The workflow writes the API private key to the temporary runner directory. It imports the certificate into an ephemeral keychain. Neither file enters an uploaded artifact.
Local checks
Run the focused checks before using the manual workflow:
vp install --frozen-lockfile
vp run check:public-dependencies
vp test run scripts/check-public-dependencies.test.ts scripts/resolve-previous-release-tag.test.ts
vp run release:smoke
vp run build:desktop
vp run --filter @akeru/marketing typecheck
vp run --filter @akeru/marketing build
Run the CLI package dry-run after the server build has produced apps/server/dist/client:
vp run --filter akeru-bot build
node apps/server/scripts/cli.ts publish --dry-run --app-version 0.0.0-smoke.0 --verbose
Do not use the smoke workflow as a release procedure. Merge the Version Packages pull request for a stable release, or let the scheduled workflow create a nightly.