How do I install Aqweth?

Install the CLI with pip install aqweth-cli, then run aqweth init to configure your stack interactively. The wizard validates live connections to each backend. Deploy with helm install aqweth oci://ghcr.io/justjk/charts/aqweth and verify with aqweth validate.

aqweth.yaml is the single configuration file for Aqweth. It defines your LLM gateway, backend connections (logs, metrics, traces, etc.), and deployment context. Switching a backend is a one-line change — no code rebuild required.

Aqweth Docs — Setup, Configuration & Backend Reference

On this page

Getting started

Aqweth runs in a dedicated namespace on your existing Kubernetes cluster. It never touches production workloads directly and connects to observability systems via read-only credentials only.

Read-only

Queries logs, metrics, and traces. Never writes to production systems.

Own namespace

Isolated from your workloads by Kubernetes namespace boundaries.

Human-gated

Every suggested action requires explicit engineer approval.

Prerequisites

Track A · Cloud LLM

recommended

· kubectl configured against the target cluster
· Helm 3.x
· GitHub PAT with read:packages scope

Track B · Self-hosted LLM

· Everything in Track A
· GPU nodes — A10G (24 GB VRAM) minimum
· Ollama or vLLM reachable from aqweth namespace
· LiteLLM gateway fronting the inference server

Setup wizard

The interactive wizard validates every backend connection before writing aqweth.yaml and emits kubectl commands in next-steps.md.

bash

# Install the CLI
pip install aqweth-cli

# Run the interactive wizard
aqweth init

# With a profile preset
aqweth init --profile aws   # or: --profile gcp / k8s / local

# Re-validate without re-running the wizard
aqweth validate --config aqweth.yaml

agent.deployment_context is the single highest-impact config change after wiring backends — a 200–500 token description of your services, stack, and known failure patterns injected into every LLM prompt.

Configuration

All configuration lives in aqweth.yaml. Use ${ENV_VAR} notation for secrets — values are resolved from environment at startup and never stored in the config file.

Section Field Notes

env env Set to prod for Kubernetes deployments

redis redis.url redis://redis-master:6379/0 for bundled Redis

llm gateway_url · api_key URL of your LiteLLM gateway or cloud API base URL

llm.roles triage · primary · deep_rca · coder · embedder Model IDs from your LiteLLM gateway

backends logs · metrics · notifications One provider per category — see Backend reference

backends cloud_provider aws · gcp · none

agent deployment_context Free-text stack description injected into all prompts

investigation alert_spaces Maps severities critical/warning/info to channel keys

Deployment

Aqweth ships as an OCI Helm chart on GHCR. Four steps to first investigation.

Create GHCR pull secret

terminal bash

kubectl create namespace aqweth

kubectl create secret docker-registry ghcr-pull-secret \
  --docker-server=ghcr.io \
  --docker-username=YOUR_GITHUB_USERNAME \
  --docker-password=YOUR_GHCR_PAT \
  --namespace aqweth

Run aqweth init

See Setup wizard above — the wizard validates every backend before writing aqweth.yaml and emits kubectl commands in next-steps.md.

Helm install

bash

helm install aqweth oci://ghcr.io/justjk/charts/aqweth \
  --version 0.1.0 \
  --namespace aqweth --create-namespace \
  -f aqweth.yaml

Verify

bash

kubectl get pods -n aqweth
aqweth validate --config aqweth.yaml

Backend reference

Each category maps to one or more fetch nodes. Only one backend per category is active at a time — configured in aqweth.yaml.

Category Implemented Planned

Logs

Loki · ELK · CloudWatch · Cloud Logging · New Relic

VictoriaLogs · Splunk · Azure Monitor

Metrics

Prometheus · CloudWatch · Cloud Monitoring

VictoriaMetrics · Azure Monitor

Tracing

Grafana Tempo · AWS X-Ray · Cloud Trace

Jaeger · Zipkin · Azure AppInsights

Errors / APM

Sentry · New Relic

Rollbar · Bugsnag · Honeycomb

CI/CD

GitHub Actions · GitLab CI · CircleCI · Jenkins · Cloud Build

ArgoCD · Buildkite

Infra

Kubernetes (EKS · GKE · AKS)

—

Database

PostgreSQL · RDS/Aurora · MySQL · Neo4j

MongoDB · Cassandra · Redis

Queues

SQS

Kafka · RabbitMQ · Azure Service Bus · Google Pub/Sub

Code

GitHub · GitLab · Bitbucket

Azure DevOps

Tickets

Jira · Confluence

Linear · ServiceNow · GitHub Issues

Notifications

Slack · Google Chat

Teams · Discord · PagerDuty · OpsGenie

Vector store

Qdrant · ApertureDB

pgvector · Weaviate · Milvus

LLM roles

Every agent role is independently configurable via llm.roles in aqweth.yaml. Mix self-hosted and cloud providers freely — one line per role.

Role Default Example production

Primary reasoning / RCA qwen3:4b

claude-sonnet-4-6 · gpt-4o

Deep RCA (thinking mode) qwen3:4b

claude-opus-4-7 · Qwen3-30B self-hosted

Fast triage / classification qwen3:4b

Qwen3-4B self-hosted · gpt-4o-mini

Code understanding qwen3:4b

Qwen3-Coder self-hosted · claude-sonnet-4-6

Embeddings nomic-embed-text

bge-m3 self-hosted · text-embedding-3-small

aqweth.yaml yaml

llm:
  gateway_url: http://litellm.internal:4000
  api_key: ${LITELLM_API_KEY}
  roles:
    triage:    qwen3-4b-instruct
    primary:   claude-sonnet-4-6
    deep_rca:  claude-opus-4-7
    coder:     qwen3-coder-next
    embedder:  bge-m3

Troubleshooting

RCA quality is low despite successful investigations.

Set agent.deployment_context in aqweth.yaml — a 200–500 token description of your services, stack, and known failure patterns. This is injected into every synthesiser prompt and has the highest impact on RCA quality.

fetch_runbooks and fetch_similar_rcas return empty results.

These nodes require Qdrant. Set QDRANT_URL in your aqweth-secrets Kubernetes secret. Without it, investigations still complete on live evidence — they just lack historical RCA context and runbook retrieval.

The Approve button in Slack does nothing.

JIRA_URL and JIRA_API_TOKEN must be set in aqweth-secrets. Without them, the human_review interrupt fires correctly but ticket creation is disabled.