popagent

public

Latest change ddf199fba7f32b2da46ff651b553c4a91238f246 - Document BifrOSt agent integration by Ólafur Búi Ólafsson

# 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).

## 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. The local `titan/qwen3.5-4b` route uses a llama.cpp chat template that accepts only one leading system message, so Popagent combines Mastra's consecutive leading system instructions for that model only. 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. Other models retain their original multi-system-message request shape.

## 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