popagent

public

Latest change 4565eb356975518dfc0202eab29b56dff51e8f71 - add deterministic agent health validation by AkurAI Build

# 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](https://bun.sh/)
- Docker with Compose
- Reachable 9Router and OpenAI-compatible embedding services
- Linux with systemd for managed deployment

## Setup

```bash
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

```bash
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`](AGENTS.md).

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

```bash
./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:

```bash
./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