GitHub - precious112/Argus: AI-native observability for production systems. Automatically understands your application from runtime data and logs. No dashboards. No manual configuration.

AI-native observability that replaces dashboards with conversation

Argus is an open-source observability platform with a built-in AI agent that monitors your infrastructure, investigates anomalies autonomously, and proposes fixes — all through a chat interface. Think Datadog + ChatGPT, self-hosted and under your control.

argus_demo_2.mp4

Why Argus

Chat, don't dashboard — Ask questions in natural language instead of writing PromQL or building Grafana panels
Autonomous investigation — AI agent auto-investigates anomalies using a ReAct loop with 18+ tools, then proposes fixes
Full-stack observability — Logs, metrics, traces, errors, and security in one place
Human-in-the-loop — The agent proposes actions; you approve before anything executes
Cost-controlled AI — Token budgets with daily/hourly limits prevent runaway LLM spending
LLM-agnostic — Works with OpenAI, Anthropic, Gemini, and Google Vertex AI — swap providers with one config change

Features

AI Agent

ReAct reasoning loop with 18+ tools for autonomous investigation. The agent reads logs, queries metrics, traces requests, correlates errors, and proposes remediation actions — all with your approval before execution.

System Monitoring

CPU, memory, disk, network metrics. Process crash detection, OOM kills, resource exhaustion alerts. Collected automatically with zero configuration.

Application Tracing

Distributed tracing with W3C trace context propagation. Automatic span creation for HTTP requests, database calls, and external dependencies. Error grouping with breadcrumb trails.

Security Scanning

Brute-force login detection, open port scanning, suspicious process identification, and file permission auditing. Security events feed directly into the AI agent for correlation.

Smart Alerting

Rules engine with Slack, email, and webhook delivery. AI-enhanced alert summaries that tell you why something matters, not just that a threshold was crossed.

Token Budget Management

Daily and hourly token limits, priority reserves for critical investigations, and a cost analytics dashboard. Stay in control of LLM spending.

Quick Start

Single Image (Recommended)

A single unified image bundles the agent server and web UI together:

docker run -d --name argus \
  -p 7600:7600 -p 3000:3000 \
  -e ARGUS_LLM__PROVIDER=openai \
  -e ARGUS_LLM__API_KEY=your-api-key-here \
  -e ARGUS_LLM__MODEL=gpt-4o \
  -e ARGUS_PUBLIC_URL=http://your-server-ip:7600 \
  -e ARGUS_HOST_ROOT=/host \
  -v argus_data:/data \
  -v /proc:/host/proc:ro \
  -v /sys:/host/sys:ro \
  -v /var/log:/host/var/log:ro \
  -v /var/run/docker.sock:/var/run/docker.sock \
  --pid=host \
  --privileged \
  --restart unless-stopped \
  ghcr.io/precious112/argus:latest

Replace your-server-ip with your server's external IP address (e.g. 104.198.209.149).

Firewall / VPC: Make sure ports 3000 and 7600 are open for TCP ingress in your cloud provider's firewall or VPC security group settings (e.g. GCP firewall rules, AWS security groups, Azure NSGs) — otherwise you won't be able to reach the UI or API from your browser.

Web UI: open http://your-server-ip:3000 in your browser
Agent API: http://your-server-ip:7600 from your browser

Note: If you only need to interact with the API from within the server itself (e.g. curl, scripts, SDK calls), you can use http://localhost:7600 directly — no firewall changes or ARGUS_PUBLIC_URL needed for that.

For Docker Compose (reads from .env file automatically):

export ARGUS_LLM_API_KEY=your-api-key-here
docker compose -f docker/docker-compose.unified.yml up -d

Variable	Default	Description
`ARGUS_LLM__PROVIDER`	`openai`	LLM provider: `openai`, `anthropic`, `gemini`, `vertex`
`ARGUS_LLM__API_KEY`	—	API key for your LLM provider — required except for `vertex`, which uses Google ADC
`ARGUS_LLM__MODEL`	`gpt-4o`	Model name
`ARGUS_LLM__VERTEX_PROJECT`	auto	`vertex` only — GCP project ID (auto-detected when running on a GCP VM)
`ARGUS_LLM__VERTEX_LOCATION`	`us-central1`	`vertex` only — Vertex region; use `global` for the newest Gemini models
`ARGUS_AI_BUDGET__HOURLY_TOKEN_LIMIT`	`500000`	Per-hour AI token cap (enforced mid-investigation; chat is never limited)
`ARGUS_PUBLIC_URL`	—	Set for remote access, e.g. `http://192.168.1.50:7600`
`ARGUS_CORS_ORIGINS`	auto	Custom CORS origins (auto-set when `ARGUS_PUBLIC_URL` is used)

Using Google Vertex AI (Gemini)

Vertex authenticates with Google Application Default Credentials (ADC), not an API key. On a GCP VM the container picks up the VM's attached service account automatically (no key file) — the service account needs roles/aiplatform.user and the VM the cloud-platform access scope. Use the same docker run as above, swapping the LLM env:

  -e ARGUS_LLM__PROVIDER=vertex \
  -e ARGUS_LLM__MODEL=gemini-2.5-flash \
  -e ARGUS_LLM__VERTEX_LOCATION=global \
  -e ARGUS_LLM__VERTEX_PROJECT=your-gcp-project \
  # (omit ARGUS_LLM__API_KEY — Vertex uses ADC)

Newer Gemini models (e.g. gemini-3.5-flash) are only served from the global location — set ARGUS_LLM__VERTEX_LOCATION=global.
Running off GCP? Mount a service-account key: add -v /path/to/key.json:/sa.json:ro -e GOOGLE_APPLICATION_CREDENTIALS=/sa.json.

User Management

After starting Argus, create your first user account:

docker exec -it argus python -m argus_agent.auth.cli create-user

This will prompt for a username and password. Or pass them directly:

docker exec -it argus python -m argus_agent.auth.cli create-user --username admin --password your-password

CLI

The Argus CLI is bundled in the Docker image. Use it to chat with the AI agent, check status, view alerts, and more — all from the terminal.

# Login (interactive prompt for username/password)
docker exec -it argus argus login

# Start an interactive chat session with the AI agent
docker exec -it argus argus

# One-off question
docker exec -it argus argus ask "What's using the most CPU right now?"

# System status
docker exec -it argus argus status

# View alerts
docker exec -it argus argus alerts

# View logs
docker exec -it argus argus logs -n 100

# List monitored processes
docker exec -it argus argus ps

# List SDK-instrumented services
docker exec -it argus argus services

# View/update LLM config
docker exec -it argus argus config
docker exec -it argus argus config set

# Logout
docker exec -it argus argus logout

If running the CLI outside the container, set the server URL:

pip install argus-cli
argus --server http://your-server-ip:7600

Alerting (Slack, Email, Webhooks)

Argus supports Slack (Bot API), email (SMTP), and generic webhooks (auto-detects Slack/Discord webhook URLs). Configure all channels from the Settings page in the Web UI — add your credentials, pick a channel, and hit test to verify.

Multi-Container Setup

Alternatively, run agent and web as separate containers:

# Set your LLM API key
export ARGUS_LLM_API_KEY=your-api-key-here

# Start Argus
docker compose up -d

# Open the web UI
open http://localhost:3000

With Example Apps

Spin up Argus alongside instrumented Python and Node.js apps that generate realistic traffic:

export ARGUS_LLM_API_KEY=your-api-key-here
docker compose --profile test up -d

Local Development

# Install all dependencies
make install

# Start the agent server (terminal 1)
make dev

# Start the web UI (terminal 2)
make dev-web

# Run tests
make test

SDK Integration

Instrument your apps in minutes with the Python and Node.js SDKs.

Python

import argus
from argus.middleware.fastapi import ArgusMiddleware

argus.init(
    server_url="http://localhost:7600",
    service_name="my-app",
    runtime_metrics=True,
    auto_instrument=True,
)

app = FastAPI()
app.add_middleware(ArgusMiddleware)

# Trace functions, capture errors, send custom events
@argus.decorators.trace("checkout")
async def checkout():
    argus.event("checkout_started", {"items": 3})
    try:
        process_payment()
    except Exception as e:
        argus.capture_exception(e)

Node.js

npm install @argus-ai/node

const Argus = require("@argus-ai/node");

Argus.init({
  serverUrl: "http://localhost:7600",
  serviceName: "my-app",
});
Argus.startRuntimeMetrics();
Argus.patchHttp();

const app = express();
app.use(Argus.argusMiddleware());

// Trace routes, capture errors, send custom events
app.get("/users", Argus.trace("get_users")((req, res) => {
  Argus.event("users_fetched", { count: results.length });
  res.json({ users: results });
}));

See the full working examples in examples/python-fastapi/ and examples/node-express/.

Architecture

                    ┌──────────────────────────┐
                    │   Web UI (Next.js) :3000  │
                    │   CLI Client (Python)     │
                    └────────┬──┬───────────────┘
                         WebSocket  REST
                             │  │
┌──────────┐   ingest   ┌───▼──▼───────────────────────┐
│ SDKs     ├───────────►│   Agent Server (FastAPI) :7600│
│ Python   │            │                               │
│ Node.js  │            │  ┌─────────┐  ┌────────────┐  │
└──────────┘            │  │ Agent   │  │ Collectors │  │
                        │  │ ReAct   │  │ Metrics    │  │
                        │  │ Loop    │  │ Logs       │  │
                        │  │ 18+Tools│  │ Security   │  │
                        │  └────┬────┘  └─────┬──────┘  │
                        │       │             │         │
                        │  ┌────▼─────────────▼──────┐  │
                        │  │  Event Bus + Alert Engine│  │
                        │  └────┬────────────────────┘  │
                        │       │                       │
                        │  ┌────▼────────────────────┐  │
                        │  │ SQLite    │  DuckDB      │  │
                        │  │ (config)  │  (time-series)│  │
                        │  └──────────┴──────────────┘  │
                        └───────────────────────────────┘

Copy argus.example.yaml to argus.yaml, or use environment variables with the ARGUS_ prefix:

export ARGUS_LLM__PROVIDER=openai      # openai, anthropic, gemini, vertex
export ARGUS_LLM__API_KEY=sk-...       # not needed for vertex (uses Google ADC)
export ARGUS_LLM__MODEL=gpt-4o
export ARGUS_DEBUG=true

See argus.example.yaml for all available options.

Tech Stack

Component	Technology	Purpose
Agent Server	Python, FastAPI, SQLAlchemy	Core AI agent, API, business logic
Web UI	Next.js, React, Tailwind CSS	Chat-first dashboard
CLI	Python, Rich	Terminal interface
Operational DB	SQLite	Config, sessions, alert rules
Time-Series DB	DuckDB	Metrics, logs, traces, events
Python SDK	Python	Application instrumentation
Node.js SDK	TypeScript	Application instrumentation
Deployment	Docker, Docker Compose	Production & development

Project Structure

argus/
├── packages/
│   ├── agent/          # Core agent server (Python/FastAPI)
│   ├── web/            # Next.js chat-first web UI
│   ├── cli/            # CLI/TUI client (Python)
│   ├── sdk-python/     # Python instrumentation SDK
│   ├── sdk-node/       # Node.js instrumentation SDK
│   └── shared/         # Shared protocol schemas
├── examples/
│   ├── python-fastapi/ # Instrumented FastAPI example app
│   └── node-express/   # Instrumented Express example app
├── docker-compose.yml  # Production deployment
├── Makefile            # Dev convenience commands
└── scripts/            # Dev and install scripts

Contributing

Contributions are welcome! Please open an issue or submit a pull request on GitHub.

License

MIT

推荐订阅源

Show HN