Menu
AkurAI-Build
publicLatest change 69219af856501f06cf1fd77336bc54a34e1cca42 - Checkpoint WIP + rustfmt + AkurAI Build CI/CD pipeline by Ólafur Búi Ólafsson
---
name: akurai-build
description: Operates the Titan-hosted AkurAI Build Git and CI/CD system through its maintained deploy script and Model Context Protocol tool set. Use for hosted repository migration/synchronization, repository registration, pipeline runs, logs, artifacts, promotions, health, deployment, rollback, Nginx-vhost setup, and release publishing.
compatibility: Requires SSH alias titan; production is reached through the AkurAI-VPN mesh.
license: MIT
---
# AkurAI Build operations
Read `../../../deploy.md` before every task. Check this skill and `deploy.sh help` before running anything. Repository, pipeline, run, artifact, and promotion operations go through the `akurai-build` MCP tool set, not shell commands. Direct shell/SSH/system commands are read-only probes only; after a successful probe, add the operation and a focused check to the MCP tool set or deploy script and update this skill before reusing it.
Canonical source is `~/Projects/AkurAI-Build` on Titan. Production is `https://akurai-build.olibuijr.com`; EC2 Nginx proxies through AkurAI-VPN to Titan `100.88.0.9:3210`.
Use only the maintained entrypoint. It forwards to Titan when invoked elsewhere and automatically verifies source-tree synchronization before source-changing/checking commands:
```sh
~/Projects/AkurAI-Build/deploy.sh sync
~/Projects/AkurAI-Build/deploy.sh edge-probe
~/Projects/AkurAI-Build/deploy.sh mesh-recover # restart Titan and EC2 VPN nodes, then verify private upstream
~/Projects/AkurAI-Build/deploy.sh http-smoke
~/Projects/AkurAI-Build/deploy.sh probe
~/Projects/AkurAI-Build/deploy.sh status-local
~/Projects/AkurAI-Build/deploy.sh status
~/Projects/AkurAI-Build/deploy.sh logs 100
~/Projects/AkurAI-Build/deploy.sh format
~/Projects/AkurAI-Build/deploy.sh clean-build # only for pre-fix corrupt/stale Cargo artifacts
~/Projects/AkurAI-Build/deploy.sh recover-checks # only after a timed-out/stale check
~/Projects/AkurAI-Build/deploy.sh check
~/Projects/AkurAI-Build/deploy.sh binfmt
~/Projects/AkurAI-Build/deploy.sh docker-smoke
~/Projects/AkurAI-Build/deploy.sh build-info
~/Projects/AkurAI-Build/deploy.sh deploy-local
~/Projects/AkurAI-Build/deploy.sh deploy
~/Projects/AkurAI-Build/deploy.sh rollback
```
Do not replace these with ad-hoc `ssh`, `systemctl`, `docker`, Nginx, certificate, package-manager, Git publication, database, artifact, or filesystem mutation commands. Never edit installed/runtime files manually.
## MCP tool set — registered live in OMP (2026-07-15)
Repository, pipeline, run, artifact, and promotion operations are MCP tools served over stdio (JSON-RPC `2025-06-18`) by `~/Projects/AkurAI-Build/deploy.sh mcp`. This session's `~/.omp/agent/mcp.json` registers it as the `akurai-build` server:
```json
"akurai-build": { "type": "stdio", "command": "/home/olafurbui/Projects/AkurAI-Build/deploy.sh", "args": ["mcp"], "timeout": 30000 }
```
Call tools directly as `mcp__akurai_build_akurai_<name>` (e.g. `mcp__akurai_build_akurai_repo_list`) — no manual JSON-RPC piping through `deploy.sh mcp` needed for normal use; that raw stdio invocation remains useful only when debugging the server itself or verifying a fresh build exposes a tool correctly (see "Debugging the MCP server" below). The registered instance already serves the full read/write tool set (confirmed live 2026-07-15: `akurai_repo_list`, `akurai_repo_remove`, etc. all work without manually exporting `AKURAI_ALLOW_NATIVE`) — unlike a bare `deploy.sh mcp` invocation from a plain shell, which defaults to 4 read-only tools (`akurai_repositories`/`akurai_runs`/`akurai_run`/`akurai_workers`) unless `AKURAI_ALLOW_NATIVE=1` is set in that shell's environment first. OMP's registration evidently supplies (or doesn't need) that flag; do not assume a manual `deploy.sh mcp` shell probe has write access without setting it explicitly.
**Inconsistent with the rest of the fleet:** `akurai-notes`, `akurai-passvault`, `akurai-tasks`, and `hindsight-memory` are all `type: "http"` in `mcp.json`; `akurai-build` is the only `type: "stdio"` entry. An HTTP `/mcp` endpoint for AkurAI-Build (mirroring the other three) was scoped but never built as of 2026-07-14 — the stdio registration works today and needs no immediate fix, but if AkurAI-Build's process-per-call stdio model becomes a bottleneck or a deploy target needs to reach it over the network, building the HTTP wrapper is the known next step.
Call `tools/list` for the live schema. Tool set (20 tools, confirmed live 2026-07-15):
```
akurai_doctor controller diagnostics: database readiness, git, docker
akurai_repo_list query repositories by text/visibility
akurai_repo_add register an external repository by URL
akurai_repo_host mirror + host from a trusted Titan checkout
akurai_repo_sync sync a hosted mirror from its trusted checkout
akurai_repo_rename rename a registered repository
akurai_repo_remove unregister + delete mirror; cascades runs/artifacts (destructive)
akurai_repo_visibility set private/public dashboard visibility
akurai_repo_branches list remote branch heads via git ls-remote
akurai_repo_tree browse a repository's file tree at a ref/sub-path
akurai_init write a minimal .akurai.yml template to a path
akurai_run_queue queue a pipeline run, optionally waiting
akurai_runs query runs across repositories with filters
akurai_run_show read one run: jobs, artifacts, deployments
akurai_run_wait poll a run until terminal/approval-required
akurai_run_logs job logs for a run, optionally failed-only
akurai_run_retry queue the same immutable revision as a prior run
akurai_run_promote approve/resume a protected environment (production-impacting)
akurai_artifact_get copy a build artifact to a Titan path
akurai_workers Titan worker status, capacity, heartbeat
```
Every tool returns its JSON payload as the sole `content` text entry, or `isError: true` with a message; MCP never exposes protected secrets. Require persisted `status == "succeeded"` before claiming a build or deployment succeeded; `waiting` requires an explicit `akurai_run_promote`, and `queued`/`running` are incomplete. `akurai_runs`' `repo`/`status`/`trigger` filters accept a string, comma-separated values, or an array. `akurai_repo_remove` and `akurai_run_promote` are consequential — confirm intent before calling them.
`akurai_repo_host` is the only supported migration from an external remote into AkurAI Build Git: it creates a complete bare mirror below the protected data root, enables authenticated Smart HTTP writes, and updates the CI registration only after the mirror succeeds. `akurai_repo_sync` publishes later changes from the trusted Titan checkout. The clone URL is `https://akurai-build.olibuijr.com/git/<name>.git`; Smart HTTP requires the protected API bearer token through a credential helper or maintained command — never place it in a URL, command argument, source file, Markdown, or logs.
`akurai_repo_remove` unregisters a repository and deletes its hosted bare mirror
(`~/.local/share/akurai-build/hosted/<name>.git`), cascading to that repository's runs,
jobs, logs, and artifacts. It is destructive and irreversible; confirm the name first with
`akurai_repo_list`. Repositories registered by URL (no local mirror) are unregistered without a
mirror deletion.
### Debugging the MCP server
If an expected tool errors `unknown tool: <name>`, check two things before assuming it doesn't exist: (1) tool NAMES differ by mode — a bare shell invocation of `deploy.sh mcp` without `AKURAI_ALLOW_NATIVE=1` serves the 4-tool read-only set (`akurai_repositories`/`akurai_runs`/`akurai_run`/`akurai_workers`), calling a write-mode name like `akurai_repo_list` against it fails with "unknown tool"; (2) the installed binary (`~/.local/lib/akurai-build/akurai`, run by `deploy.sh serve`/`deploy.sh mcp`) can lag behind current source in `~/Projects/AkurAI-Build` — a tool documented in this skill but missing from a live `tools/list` may mean the binary needs `deploy.sh build` + `deploy.sh deploy-local` before it's actually present. Manual stdio probe for either check:
```sh
cd ~/Projects/AkurAI-Build
export AKURAI_ALLOW_NATIVE=1 # only needed for a manual shell probe, not for the OMP-registered server
{ echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}'
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
} | timeout 15 ./deploy.sh mcp
```
## Source lifecycle
```sh
~/Projects/AkurAI-Build/deploy.sh lock
~/Projects/AkurAI-Build/deploy.sh publish "concise change summary"
~/Projects/AkurAI-Build/deploy.sh deploy
~/Projects/AkurAI-Build/deploy.sh vhost
```
Service deploys have a bounded readiness wait. Checks have hard process-group timeouts so a deadlock is killed and fails closed. `publish` maintains the repository-local GitHub author identity, checks, commits, and pushes GitHub `olibuijr/AkurAI-Build`; `deploy` checks again, builds, retains the previous binary, migrates transactionally, installs the skill, and restarts the hardened service.
## IDP / OIDC setup
AkurAI Build authenticates through the AkurAI IDP at `auth.olibuijr.com`.
Provision the OIDC client once through the maintained EC2 CLI:
```sh
~/.local/bin/akurai-ec2 provision-oidc-client "AkurAI Build" \
https://akurai-build.olibuijr.com/auth/callback \
--scopes "openid profile email groups" \
--grant-types "authorization_code refresh_token" \
--first-party
```
This writes `AKURAI_BUILD_IDP_CLIENT_ID`, `AKURAI_BUILD_IDP_CLIENT_SECRET`,
and related vars to `~/.config/akurai-build/env` (mode 0600). The service
reads them at startup via the `IdpConfig::from_env` path in `src/auth.rs`.
Required env vars (set by provisioning):
- `AKURAI_BUILD_IDP_ISSUER` (default `https://auth.olibuijr.com`)
- `AKURAI_BUILD_IDP_CLIENT_ID`
- `AKURAI_BUILD_IDP_CLIENT_SECRET`
- `AKURAI_BUILD_IDP_REDIRECT`
- `AKURAI_BUILD_ADMIN_EMAILS` (comma-separated list of admin email addresses)
The provision script at `scripts/provision-oidc-client.sh` is a legacy
standalone copy; prefer the `akurai-ec2 provision-oidc-client` CLI command.
Secrets belong only in protected files under `~/.config/akurai-build/` or as `AKURAI_SECRET_<NAME>` entries in its mode-0600 environment file. Never retrieve, echo, log, pass, or store their values in commands, Markdown, Git, or SQLite. Native jobs require a trusted repository and an explicit production opt-in; prefer restricted Docker jobs.