AgenticLUP

Always-on monitoring agent with a HUD. Tell it what to watch, and it searches, schedules, and reports back — all visible in a real-time browser dashboard.

Built on Agno and FastAPI.

Features

• Browser HUD — real-time timeline of events, chat, and scheduled task status
• Scheduled monitoring — create recurring tasks via chat (e.g. "check HackerNews for AI news every 6 hours")
• Web search — DuckDuckGo out of the box (no key needed), or Exa for deep research
• LLM flexibility — works with OpenRouter (Claude, GPT, etc.) or local Ollama models
• Setup wizard — configure everything from the browser on first launch, no config files required

Quick Start

One-line install

The fastest way to get running. The script auto-detects Docker or Python and does everything for you.

Mac / Linux:

curl -fsSL https://raw.githubusercontent.com/Zalmotek/AgenticLup/main/get.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/Zalmotek/AgenticLup/main/get.ps1 | iex

What it does: clones the repo, builds via Docker (preferred) or installs natively with Python + uv, starts the server, and opens the HUD in your browser. If the AgenticLup/ directory already exists, it pulls the latest instead of re-cloning.

To use a different port: PORT=8080 curl -fsSL ... | bash

Docker (manual)

If you prefer to run the Docker commands yourself:

Docker Compose (recommended)

git clone https://github.com/Zalmotek/AgenticLup.git
cd AgenticLup
docker compose up -d

Open http://localhost:7777 — the setup wizard will walk you through configuring your LLM and search provider.

To change the port:

PORT=8080 docker compose up -d

Data (settings, database) is persisted in a Docker volume (agenticlup-data), so it survives container restarts and rebuilds.

Docker Run (no Compose)

docker build -t agenticlup .
docker run -d \
  -p 7777:7777 \
  -v agenticlup-data:/data \
  --name agenticlup \
  --restart unless-stopped \
  agenticlup

Pre-configure with environment variables

You can skip the setup wizard by passing API keys as environment variables:

docker run -d \
  -p 7777:7777 \
  -v agenticlup-data:/data \
  -e OPENROUTER_API_KEY=sk-or-... \
  -e SEARCH_PROVIDER=duckduckgo \
  -e HUD_PASSWORD=mysecretpassword \
  agenticlup

Or with Compose, uncomment the relevant lines in docker-compose.yml.

Local Development

Requires Python 3.11+ and uv.

# Install dependencies
./install.sh

# Start the server
./start.sh

Open http://localhost:7777. The setup wizard will appear on first launch.

Configuration

All settings can be managed from the browser's Settings panel. Environment variables are available for Docker and CI/CD use.

Setting	Env Variable	Description
LLM Provider	LLM_PROVIDER	openrouter or ollama (auto-detected from keys)
OpenRouter API Key	OPENROUTER_API_KEY	Key from openrouter.ai
OpenRouter Model	OPENROUTER_MODEL	Default: anthropic/claude-sonnet-4
Ollama Host	OLLAMA_HOST	e.g. http://localhost:11434
Ollama Model	OLLAMA_MODEL	Default: llama3
Search Provider	SEARCH_PROVIDER	duckduckgo (default, no key) or exa
Exa API Key	EXA_API_KEY	Key from exa.ai (only needed if using Exa)
HUD Password	HUD_PASSWORD	Protect the dashboard with a password
Port	PORT	Default: 7777
Database	DATABASE_URL	PostgreSQL URL. Omit for SQLite (default)

Troubleshooting

Port already in use Change the port: PORT=8080 docker compose up -d, or stop whatever is using port 7777.

Ollama not reachable from Docker Inside a Docker container, localhost refers to the container itself, not your host machine. Use http://host.docker.internal:11434 as the Ollama host in the setup wizard (works on Docker Desktop for Mac/Windows). On Linux, add --add-host=host.docker.internal:host-gateway to your docker run command or add this to docker-compose.yml:

extra_hosts:
  - "host.docker.internal:host-gateway"

Setup wizard won't appear / settings not saving Make sure the Docker volume is mounted (-v agenticlup-data:/data). Without it, settings are lost on restart.

Container shows "unhealthy" Check logs with docker logs agenticlup. Common causes: missing Python dependencies (rebuild with docker compose build --no-cache) or port mismatch.

Architecture

Browser HUD (static JS)
    |
    v
FastAPI + AgentOS
    |
    +-- /api/chat          -> Agent.run(prompt) -> SSE events
    +-- /api/schedules     -> Agno ScheduleManager (CRUD)
    +-- /api/scheduled-run -> Bridge for scheduler executor
    +-- /api/events        -> Timeline events (SSE stream)
    +-- /api/status        -> Health & stats
    +-- /api/settings      -> Runtime config
    |
    +-- Agno SchedulePoller (background)
           polls due schedules -> HTTP POST /api/scheduled-run
           -> Agent.run(prompt) -> emit event -> SSE -> HUD

License

Apache 2.0 — see LICENSE.