AkurAI Build
Sign in with AkurAI ID
Menu

popagent

public
f945e80459ae4cea6dcf1b5ea47188af1ee6aae1 209 commits 2 branches 0 tags
AkurAI Build Let autonomy come back after it has been switched off f945e80
.agents Add popagent settings-patch and document agent step-budget mechanics — patches Provide devices in contained workspaces — searxng Initial popagent baseline — src Let autonomy come back after it has been switched off — workspace Initial popagent baseline — .akurai.yml Add repository changelog page 684 .env.example Queue local model requests 2049 .gitignore Release 1.0.50: task list slimming, remediation auto-requeue, research handoff synthesis 155 AGENTS.md Create follow-up tasks autonomously from completed scheduled reports 1623 AGENTS_AGENT.md Stop learning from runs that ran out of steps, and sweep every checkout 38881 AGENTS_BROWSER.md Add native BifrOSt Navigator browser provider with per-browser status LEDs 6540 AGENTS_BUILD.md Add model routing policy, companyStatus tool, Markdown channel output, compact Runtime settings 2370 AGENTS_CHANNELS.md feat: add per-task agent communication 6431 AGENTS_DOCUMENTATION.md Make Popagent Docs canonical 4719 AGENTS_HOOKS.md Remediate failed background tasks 6942 AGENTS_MEMORY.md feat: add per-task agent communication 8175 AGENTS_MODELS.md Fail model gateway requests fast when no response arrives within 90s 4724 AGENTS_OBSERVABILITY.md feat: trace autonomous handoff stages 3516 AGENTS_RULES.md Let autonomy come back after it has been switched off 11652 AGENTS_TASKS.md Respect the autonomy pause in follow-ups and refresh scheduled workspaces 2364 AGENTS_UI.md Release 1.0.50: task list slimming, remediation auto-requeue, research handoff synthesis 18241 bun.lock Add native BifrOSt Navigator browser provider with per-browser status LEDs 206296 bunfig.toml Add governed AkurAI Build maintenance 199 CHANGELOG.md Let autonomy come back after it has been switched off 30072 deploy.sh Keep successful changelog gate nonzero-safe 18223 docker-compose.yml Add workspace documentation RAG 1466 LICENSE Add safe autonomous deployment and complete project guidance 1078 package.json Stop learning from runs that ran out of steps, and sweep every checkout 1473 popagent Add popagent settings-patch and document agent step-budget mechanics 14156 README.md add deterministic agent health validation 5549 tsconfig.json Add governed AkurAI Build maintenance 786
README.md

popagent

A single-user agent workspace with a Mastra backend and assistant-ui frontend, served by Bun. Models use a local OpenAI-compatible 9Router gateway; documentation embeddings may use a dedicated LAN service; search uses local SearXNG; durable state uses PostgreSQL.

Requirements

  • Bun
  • Docker with Compose
  • Reachable 9Router and OpenAI-compatible embedding services
  • Linux with systemd for managed deployment

Setup

cp .env.example .env
chmod 600 .env
# Replace every placeholder and generate POPAGENT_SECRET_KEY as documented.
git clone https://akurai-build.olibuijr.com/git/popagent.git workspace/popagent
docker compose up -d --wait
bun install --frozen-lockfile
bun run dev

The application defaults to http://127.0.0.1:5180. Set POPAGENT_API_KEY before exposing it beyond a trusted machine. Runtime data, credentials, repositories, recordings, and deployment backups are ignored by Git.

Project documentation is private PostgreSQL data organized as workspace-scoped folders and Markdown files. The documentation UI provides editing, GFM preview, semantic search, and manual reindexing; page bodies are not written into registered Git repositories. Production uses the 192.168.1.10 LAN embedding service rather than Tailnet 100.x addresses.

Agents whose persisted role grants browser access can also operate the user's visible local BifrOSt Navigator through its protected Unix MCP socket. interactive roles may use mutating operations; read-only roles are restricted to inspection. Popagent never starts or owns the desktop browser, and trusted self-update receives no BifrOSt capability.

Development

bun test <file>       # narrow loop
bunx tsc --noEmit
bun test              # complete suite

Storage tests require disposable PostgreSQL. Live model and documentation-index scenarios require their configured gateway services; browser and search integration require their local services. Agent-specific architecture and verification rules begin in AGENTS.md.

Local code intelligence is workspace-contained and incrementally refreshed on each request:

./popagent code-context <workspace> "<repository question>"
./popagent symbol-context <workspace> <symbol> [file]
./popagent change-impact <workspace> '{"paths":["src/server.ts"]}'

It uses the configured LAN embedding endpoint and keeps derived Tree-sitter, BM25, vector, and call-graph state in the checkout's ignored .codebase-index/. LSP remains authoritative for typed references and renames.

Deployment

AkurAI Build hosts the public Git repository. Publication and deployment are deliberately separate:

./deploy.sh privacy-check
./deploy.sh publish   # privacy scan, then push committed main
./deploy.sh deploy    # full isolated suite, candidate readiness, brief service restart

On Midget, deploy verifies that the commit is published and triggers Titan over SSH. On Titan, it refuses dirty or divergent work, ensures the ignored workspace/popagent agent checkout exists, starts required services, provisions disposable test databases, runs the full suite, validates a candidate, backs up databases for SQL changes, installs a user systemd service (or a system service under sudo), monitors health, and rolls back a failed restart. Override remote details with POPAGENT_DEPLOY_HOST, POPAGENT_DEPLOY_PATH, and POPAGENT_GIT_REMOTE.

For authenticated publication, inject POPAGENT_GIT_USERNAME and POPAGENT_GIT_TOKEN only for that command. The script does not persist them. Titan's .env remains host-local and is never synchronized through Git.

Model compatibility

Popagent accepts model IDs from the live 9Router catalog. Titan's persisted default and orchistrator model are cx/gpt-5.6-luna-max: Luna handles intensive orchestration, complex reasoning, and instructions for delegated work. The researcher, implementer, and reviewer profiles use titan/ornith-1.0-9b-mtp-q4_k_m for token-heavy local coding work. This Ornith-1.0-9B MTP Q4_K_M llama.cpp route is configured for 131,072 tokens; 9Router advertises the conservative 128,000-token application limit. OmniRoute must import the llama.cpp /models catalog before a changed local alias appears in GET /api/models.

Slow local inference can take longer than Bun's default request timeout; the server allows up to 255 seconds of stream inactivity before disconnecting.

If a local model produces no response, confirm it appears in GET /api/models, check the Popagent and 9Router logs for an upstream error, and retry with a short prompt and sufficient completion budget. Ornith reasons by default, so very small max_tokens values can be consumed before final-answer content is emitted.

Security

  • Never commit .env, credentials, runtime data, database dumps, browser profiles, recordings, or workspace repositories.
  • Documentation and retrieved repository content are untrusted reference material.
  • Browser navigation is constrained by persisted host policy, DNS checks, and workspace isolation.
  • Live BifrOSt access uses the role's persisted browser access class and the browser's own capability authorization; Popagent does not weaken either boundary.
  • Application secrets are encrypted in PostgreSQL with POPAGENT_SECRET_KEY, provisioned through Settings, and exposed to agents only as origin-bound browser-use metadata.

See .env.example and the linked AGENTS_*.md domain files for current configuration and contracts.

License

MIT