Beaver App Instance

This branch contains a standalone Beaver app instance for an external orchestrator to deploy.

The app instance is a single Docker image that runs:

• Next.js frontend
• FastAPI backend
• Nginx reverse proxy

Authentication is delegated to Keycloak. This repository does not maintain local user registration, passwords, per-user instance routing, or deployment orchestration.

Runtime Contract

The external orchestrator is responsible for:

• Building or pulling the app image
• Providing a mounted Beaver home directory
• Providing config.json
• Choosing the public host and port
• Registering the public callback URL and post-logout callback URL in Keycloak
• Managing lifecycle, routing, TLS, and scaling

The app instance exposes container port 8080:

/      frontend
/api   backend API
/ws    backend WebSocket

Keycloak

Default IdP settings:

issuer:    https://keycloak.bwgdi.com/realms/beaver
client_id: beaver-agnet

For the current plain-IP deployment, register these values in Keycloak:

web_origin:   http://172.19.0.245:18080
redirect_uri: http://172.19.0.245:18080/auth/callback
post_logout_redirect_uri: http://172.19.0.245:18080/logout/callback

The app validates Keycloak JWT issuer, signature, expiry, audience/azp, and nonce where applicable. The Keycloak sub claim is used as the application user ID.

Build

cd app-instance
docker build -t beaver/app-instance:keycloak-login .

Run Locally

cd app-instance
./run-standalone.sh --build --replace

The script prints the web_origin, redirect_uri, and post_logout_redirect_uri values that must be configured in Keycloak.

Useful Paths

• app-instance/ - app image, frontend, backend, runtime helper script, app tests
• skills/ - reusable skill content retained for product/runtime packaging
• agents/ - agent registry retained for runtime packaging
• docs/ - product and architecture documentation
• AGENTS.md - local coding-agent instructions

See app-instance/README.md for the app-specific contract and environment variables.