balaur

Install Balaur

Balaur runs host-native as a terminal-first Pi package:

balaur opens the live Pi terminal.
~/balaur/pi is registered as a local Pi package: extensions, skills, and theme load from the repo.
llama-apu serves the local model on 127.0.0.1:8082.
The private vault lives outside the repo at $VAULT_PATH (default ~/.local/share/balaur).

There is intentionally no core HTTP gateway / balaur-agent user service. Future channels should be Pi extensions attached to a long-lived terminal/tmux session.

Quick start

git clone https://github.com/alexradunet/balaur.git ~/balaur
cd ~/balaur
./install.sh
balaur

Then run:

make doctor

What `install.sh` does

installs base packages (git, make, curl, certs, openssl),
installs Bun in ~/.bun,
clones/updates this repo,
creates .env from .env.example if missing,
creates/migrates the private vault outside the repo,
runs cd pi && bun install,
installs the balaur command,
sets up the local llama.cpp model unless BALAUR_SKIP_LOCAL=1,
runs scripts/seed-pi-config.sh.

Important files

File	Purpose
`.env`	local config and secrets; never committed
`pi/models.json`	Pi provider config for `llama-apu`
`pi/AGENTS.md`, `pi/SYSTEM.md`	Balaur identity and operating rules
`pi/extensions/`	memory/vault/UI extensions
`pi/skills/`	Pi-native skills
`pi/themes/balaur.json`	terminal theme
`scripts/seed-pi-config.sh`	copies config into `~/.pi/agent` and registers the local Pi package

`.env` essentials

Variable	Meaning
`TZ`	timezone
`VAULT_PATH`	private Markdown vault; default `~/.local/share/balaur`
`BALAUR_USER_NAME`	name shown in the terminal avatar panel
`BALAUR_AVATAR_MODE`	`badge`, `avatar`, or `both`
`BALAUR_AVATAR_BACKEND`	`auto`, `image`, or `ansi`
`BALAUR_MODEL_HF`	optional GGUF override for setup-local-llm
`BALAUR_LLM_CTX`	local model context window; default 131072
`BALAUR_PRIVATE_PROVIDER`	local provider; normally `llama-apu`
`BALAUR_PRIVATE_MODEL`	model alias written by setup-local-llm
`LLAMA_LOCAL_KEY`	local model API key written by setup-local-llm
`BALAUR_GITHUB_TOKEN`	optional PAT for Balaur self-maintenance pushes

Local model

./install.sh runs scripts/setup-local-llm.sh by default. It builds/configures llama.cpp and installs the llama-apu system unit on 127.0.0.1:8082.

Check it:

curl -s http://127.0.0.1:8082/health

The system unit needs sudo to inspect/manage:

sudo systemctl status llama-apu
sudo journalctl -u llama-apu -f

Balaur should not run those sudo commands itself; the operator runs them when needed.

Pi terminal

Start:

balaur

Useful commands inside Pi:

/reload      # reload extensions, skills, prompts, theme
/model       # switch model; frontier models are manual/opt-in
/login       # sign in to a frontier provider, if wanted
/skill:doctor

Health check

make doctor

Doctor checks tooling, dependencies, tests, the local model, and Pi terminal config.

Self-maintenance

bun test
git add -A && git commit -m "…" && git push
bash scripts/seed-pi-config.sh

Then run /reload in the terminal. Full guide: SELF_MAINTENANCE.md.

Future channels

When channels return, prefer a Pi extension that runs inside a permanent terminal/tmux session and uses Pi’s session APIs. That keeps one model indicator, one memory context, and one live session.

This site is open source. Improve this page.