A provider-neutral AI agent operating system for software engineering, security analysis, guarded remediation, validation, and GitHub pull-request automation.
NEXUS combines specialist AI agents, multi-provider model routing, repository intelligence, SAST-style security scanning, conservative patch generation, sandbox validation, human approval, and GitHub PR creation into one controlled workflow.
The central idea is simple:
🐙 Repository
↓
🔎 Understand + Scan
↓
🛡️ Identify Risk
↓
🧠 Analyze with AI
↓
🔧 Generate a Conservative Patch
↓
🧪 Re-scan + Safety Gate
↓
👤 Human Approval
↓
🌿 Branch
↓
💾 Commit
↓
🔀 Pull Request
NEXUS is deliberately guarded. AI can propose and validate changes, but high-risk repository writes are not silently performed.
Watch the polished NEXUS demonstration showing the platform UI, AI specialists, model routing, security scanning, patch generation, and the Researcher AI runtime in action. 🚀
🎥 Open / Watch the NEXUS 3.2.4 Demo Video
The source MP4 is included directly in this repository under docs/demo/, so the final project package contains both the application and its demonstration asset.
Demo flow: 🐙 GitHub → 🔎 Security Scan → 🤖 AI Analysis → 🔧 Safe Patch → 🧪 Sandbox Validation → 👤 Approval → 🔀 Pull Request
NEXUS is designed as an AI engineering control plane rather than a simple chatbot.
It has two major sides:
NEXUS can run specialist agents for:
- 🔎 repository research
- 🛡️ vulnerability analysis
- 🔧 remediation and patch generation
- 🧠 multi-agent orchestration
- 🔀 provider/model routing
- 🧰 tool-assisted tasks
- 📊 run and provider visibility
NEXUS can:
- connect to a GitHub repository
- fetch bounded source files
- inspect source and manifests
- detect common security weaknesses
- group findings
- calculate a security score
- classify risk
- generate conservative remediations
- re-scan patched content
- reject unsafe or incomplete patches
- stop for human approval
- create a dedicated branch
- create a commit
- create a pull request
NEXUS exposes three clear user-facing specialist identities.
The underlying model can change. The agent role does not.
Purpose: Understand the repository before making decisions.
Researcher AI is responsible for:
- repository architecture context
- source-code investigation
- dependency/context discovery
- evidence gathering
- repository-aware reasoning
- research questions
- calculations and tool-assisted tasks
- preparing context for downstream agents
Example demo:
Task:
18 * 7 + 4
Researcher AI returns:
The calculation for 18 * 7 + 4 is 130,
as confirmed by the calculator tool.
This demonstrates that the agent can combine a natural-language request with a tool-backed result rather than simply presenting a guess.
Purpose: Find security weaknesses and explain why they matter.
Security AI works with scanner evidence such as:
const key = 'sk-demo-secret';
eval(input);
const html = userInput;
element.innerHTML = html;Typical findings include:
- 🔐 hardcoded credentials
- 💥 dynamic code execution
- 🧪 injection/query construction
- 🧬 HTML/XSS sinks
- 🌐 insecure HTTP usage
- 🐳 Docker hardening issues
- 📦 manifest/dependency hygiene issues
- 🔑 private-key or secret-like material
Each finding can carry:
- severity
- confidence
- category
- file
- line
- evidence
- remediation
- CWE
- OWASP mapping
- grouping information
Purpose: Turn validated findings into focused, conservative changes.
Fixer AI does not get permission to blindly rewrite the repository.
Instead, NEXUS:
- identifies a finding
- selects a supported remediation strategy
- creates a bounded change
- validates the change
- re-scans the changed file
- blocks the pipeline if the original finding remains
- requires approval before Git writes
Examples:
Unsafe:
export function calculate(expression) {
return eval(expression);
}NEXUS replaces this with a constrained arithmetic parser that:
- accepts only numeric arithmetic tokens
- supports parentheses
- supports
+,-,*,/,% - rejects unsupported expressions
- rejects invalid numbers
- rejects division/modulo by zero
- never executes arbitrary JavaScript
Unsafe:
export const config = {
apiKey: "sk-test-example",
databasePassword: "SuperSecretPassword123!"
};Safer:
export const config = {
apiKey: process.env.NEXUS_SECRET,
databasePassword: process.env.NEXUS_DB_PASSWORD
};The actual secret values should then be supplied through .env.local, a deployment secret manager, or another secure runtime mechanism.
Unsafe:
element.innerHTML = "Welcome " + username;Safer pattern:
element.textContent = "Welcome " + username;The project includes several control-plane views.
The Autopilot page presents the guarded GitHub workflow:
GitHub → Scan → Patch → Sandbox → PR
The page also explains that NEXUS pauses before Git writes and requires explicit human approval.
The Command Center provides a universal task console.
It shows:
- number of runs
- success rate
- latency
- tool calls
- selected specialist
- integrations
- security boundary
- agent output
The agent selector exposes:
🛡️ Security AI — Vulnerability detection & analysis
🔎 Researcher AI — Research & repository intelligence
🔧 Fixer AI — Remediation & patch generation
The Model Router is the provider abstraction layer.
It can display providers such as:
- OpenAI
- Google Gemini
- Anthropic
- OpenRouter
- Ollama
- OmniRoute
The important design principle is:
The specialist agent is separate from the provider.
For example:
Security AI
↓
NEXUS Model Router
↓
OmniRoute
↓
Gemini / OpenAI / OpenRouter / local model
That means changing providers does not require changing the user-facing security agent.
The dedicated Agents page shows the three specialist roles.
Each agent has a clear responsibility instead of presenting one generic “AI” button.
The Security page supports both:
Paste code into the local scanner and run a security analysis.
Enter:
Owner
Repository
Branch (optional)
and NEXUS can scan a repository you control.
A scan produces a score and grouped findings.
Example demo state:
70/100
2 risk groups
The exact score depends on the scanner rules and findings present in the input repository.
The Patch Engine displays proposed changes and their validation state.
The important distinction is:
Finding
↓
Patch proposal
↓
Validation
↓
Approval
↓
Git write
A patch proposal is not automatically a repository write.
The Command Center can run a tool-assisted Researcher AI task.
Example:
18 * 7 + 4
Result:
130
This is useful in a portfolio demonstration because it visibly shows the difference between a specialist agent and a static UI.
This is the most important workflow in NEXUS.
NEXUS connects to the selected repository using the GitHub API.
It identifies:
- default branch
- repository tree
- eligible text files
- file sizes
- supported source/config formats
The implementation bounds repository analysis with limits such as:
- maximum analyzed files
- maximum file size
- supported text extensions
This prevents the scanner from blindly loading an unbounded repository.
Each eligible file is passed through the appropriate scanner.
Examples:
JavaScript / TypeScript
Python
Go
Java
Ruby
PHP
Rust
YAML
JSON
SQL
Shell
Dockerfile
package.json
NEXUS can inspect for categories such as:
Examples:
apiKey
token
password
secret
private key material
cloud credentials
Example:
eval(expression);Example:
db.query("SELECT ... '" + username + "'");Example:
element.innerHTML = userInput;Examples:
- missing non-root
USER - pipe-to-shell installation
- remote URL in Docker
ADD
The package scanner can inspect dependency declarations for risky or suspicious patterns.
NEXUS starts from a baseline of:
100 / 100
It subtracts points based on grouped findings.
Conceptually:
Critical finding → large deduction
High finding → significant deduction
Medium finding → moderate deduction
Low finding → small deduction
Repeated group → additional deduction
The result becomes the repository's security score.
Example:
100
↓
finding penalties
↓
70/100
The score is a NEXUS risk indicator, not a replacement for a full commercial security assessment.
NEXUS uses risk to determine how much autonomy is allowed.
| Risk | Policy |
|---|---|
| 🟢 CLEAN | No remediation required |
| 🟡 LOW | Proposal + human review |
| 🟠 MEDIUM | Guarded patch + sandbox + approval |
| 🔴 HIGH | Guarded patch + sandbox + mandatory approval |
| 🚨 CRITICAL | Security-engineer review required |
The key safety rule is:
AI does not get unrestricted Git write access merely because it generated a patch.
For supported findings, NEXUS creates conservative changes.
Examples include:
eval()
↓
constrained parser
hardcoded API key
↓
process.env.NEXUS_SECRET
hardcoded DB password
↓
process.env.NEXUS_DB_PASSWORD
innerHTML
↓
textContent
dynamic SQL
↓
parameterized query
The remediation engine is deliberately conservative.
If it cannot confidently produce a supported safe transformation, it should leave the finding for manual remediation instead of inventing a risky patch.
This is one of the most important parts of NEXUS.
The sandbox gate performs safety checks such as:
✓ No destructive shell payloads
✓ No pipe-to-shell patterns
✓ Changed files remain within size limits
✓ Changed content is re-scanned
✓ Original finding groups must disappear
A proposed patch is rejected if a finding remains after remediation.
For example:
Original:
hardcoded-credential
Patch:
apiKey → process.env.NEXUS_SECRET
But:
databasePassword → still hardcoded
Result:
❌ SANDBOX BLOCKED
This is exactly the kind of failure that NEXUS is designed to catch.
The pipeline must not proceed merely because an AI generated some change.
When the sandbox passes, NEXUS moves into a guarded approval state.
Sandbox PASSED
↓
READY FOR APPROVAL
↓
Human / Security Engineer
↓
APPROVE
Only after approval can NEXUS perform Git writes.
NEXUS creates a dedicated branch similar to:
nexus/security-autopilot-xxxxxxxx
This isolates the remediation from the repository's main branch.
NEXUS creates:
security: NEXUS autopilot remediation
The commit contains only the validated changed files.
NEXUS creates a GitHub pull request with:
- task description
- security score
- number of findings
- number of changed files
- sandbox validation result
- approval state
Example title:
🛡️ NEXUS Security Autopilot remediation
This gives the repository owner a normal GitHub review point.
NEXUS can run several specialist agents for one task.
The high-level orchestration model is:
User Task
↓
Agent Selection
↓
┌────────────┼────────────┐
↓ ↓ ↓
Researcher Security Fixer
↓ ↓ ↓
Context Findings Patches
└────────────┼────────────┘
↓
NEXUS Synthesizer
↓
Final Result
Agent selection is task-aware.
Examples:
"Investigate repository architecture"
↓
Researcher AI
"Find security vulnerabilities"
↓
Security AI
"Fix this vulnerability"
↓
Fixer AI
For autonomous tasks, multiple active specialists can be selected and their outputs synthesized.
NEXUS is provider-neutral.
Supported provider identifiers in this release are:
openai
gemini
anthropic
openrouter
ollama
omniroute
The provider gateway exposes a common interface so the rest of NEXUS does not need to know every provider's API format.
Example:
AI_PROVIDER=omniroute
AI_FALLBACK_PROVIDERS=gemini,openrouter,ollamaThe routing sequence becomes:
1. 🔀 OmniRoute
↓
failed / quota / timeout
↓
2. ♊ Gemini
↓
failed
↓
3. 🌐 OpenRouter
↓
failed
↓
4. 🦙 Ollama
The first successful provider returns the response.
NEXUS also handles providers that return OpenAI-compatible JSON or SSE-style responses.
This section explains exactly what you need to configure.
Copy:
Copy-Item .env.example .env.localThe main variables are:
AI_PROVIDER=omniroute
AI_FALLBACK_PROVIDERS=gemini,openrouter,ollama
NEXUS_MAX_OUTPUT_TOKENS=2048
OMNIROUTE_BASE_URL=http://localhost:20128/v1
OMNIROUTE_API_KEY=
OMNIROUTE_MODEL=auto
OPENAI_API_KEY=
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4.1-mini
GEMINI_API_KEY=
GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta
GEMINI_MODEL=gemini-2.5-flash
ANTHROPIC_API_KEY=
ANTHROPIC_BASE_URL=https://api.anthropic.com/v1
ANTHROPIC_MODEL=claude-3-5-haiku-latest
OPENROUTER_API_KEY=
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
OPENROUTER_MODEL=openai/gpt-4o-mini
OLLAMA_BASE_URL=http://localhost:11434/v1
OLLAMA_MODEL=llama3.2
GITHUB_TOKEN=
GITHUB_WEBHOOK_SECRET=
TAVILY_API_KEY=
DATABASE_URL=
NEXUS_SANDBOX_DOCKER=falseOmniRoute is a local OpenAI-compatible gateway.
Current documented defaults are:
Dashboard:
http://localhost:20128
API:
http://localhost:20128/v1
The official OmniRoute project currently documents npm installation, a local dashboard, provider connections, endpoint API keys, automatic routing, and fallback behavior.
npm install -g omnirouteomnirouteOpen:
http://localhost:20128
Inside the OmniRoute dashboard:
Providers
↓
Connect a provider
You can connect a provider through its supported authentication method.
Go to:
Endpoints
↓
Create API Key
Copy the generated endpoint key.
AI_PROVIDER=omniroute
AI_FALLBACK_PROVIDERS=gemini,openrouter,ollama
OMNIROUTE_BASE_URL=http://localhost:20128/v1
OMNIROUTE_API_KEY=YOUR_OMNIROUTE_ENDPOINT_KEY
OMNIROUTE_MODEL=autocurl http://localhost:20128/v1/models -H "Authorization: Bearer YOUR_OMNIROUTE_ENDPOINT_KEY"You should receive a list of available models.
The OmniRoute endpoint key is not the same thing as a Gemini/OpenAI/Anthropic provider key.
OmniRoute is the local gateway.
The provider credentials are configured inside OmniRoute.
Official references:
- https://github.com/CarlaSalles-AI/omniroute
- https://github.com/diegosouzapw/OmniRoute/wiki/Setup-Guide
NEXUS supports Gemini directly through:
GEMINI_API_KEY=
GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta
GEMINI_MODEL=gemini-2.5-flash- Open Google AI Studio.
- Sign in with your Google account.
- Open the API Keys section.
- Create a new API key.
- Copy the key.
- Put it in
.env.local.
Example:
GEMINI_API_KEY=YOUR_GEMINI_KEYDo not paste the real key into GitHub.
Google's current Gemini documentation says new keys created in AI Studio are moving to the newer authorization-key model, and Google recommends migrating older standard keys before the September 2026 enforcement change.
Official documentation:
https://ai.google.dev/gemini-api/docs/api-key
AI_PROVIDER=gemini
AI_FALLBACK_PROVIDERS=openrouter,ollama
GEMINI_API_KEY=YOUR_GEMINI_KEY
GEMINI_MODEL=gemini-2.5-flashRestart NEXUS after changing .env.local.
For direct OpenAI usage:
AI_PROVIDER=openai
AI_FALLBACK_PROVIDERS=gemini,openrouter,ollama
OPENAI_API_KEY=YOUR_OPENAI_KEY
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4.1-mini- Sign in to the OpenAI API platform.
- Open your project/API key management area.
- Create a project API key.
- Copy it immediately.
- Store it only in
.env.local.
Official API documentation:
https://platform.openai.com/docs/api-reference/
OpenAI explicitly recommends keeping API keys secret and loading them server-side from environment variables or a key-management system.
For direct Claude-compatible access:
AI_PROVIDER=anthropic
AI_FALLBACK_PROVIDERS=gemini,openrouter,ollama
ANTHROPIC_API_KEY=YOUR_ANTHROPIC_KEY
ANTHROPIC_BASE_URL=https://api.anthropic.com/v1
ANTHROPIC_MODEL=claude-3-5-haiku-latest- Open the Anthropic Console.
- Create/select an API project.
- Create an API key.
- Copy it.
- Store it in
.env.local.
Official documentation:
OpenRouter gives NEXUS access to many model providers through one OpenAI-compatible API.
Configuration:
AI_PROVIDER=openrouter
AI_FALLBACK_PROVIDERS=gemini,ollama
OPENROUTER_API_KEY=YOUR_OPENROUTER_KEY
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
OPENROUTER_MODEL=openai/gpt-4o-mini- Create/sign in to your OpenRouter account.
- Open API key management.
- Create a key.
- Set an appropriate spending/usage limit if available.
- Copy the key.
- Store it in
.env.local.
Official quickstart:
https://openrouter.ai/docs/quickstart
OpenRouter API keys are sensitive credentials. Treat them like passwords.
Ollama allows NEXUS to use local models without a cloud API key.
Install Ollama from:
Then pull a model:
ollama pull llama3.2Configure:
AI_PROVIDER=ollama
AI_FALLBACK_PROVIDERS=omniroute,gemini
OLLAMA_BASE_URL=http://localhost:11434/v1
OLLAMA_MODEL=llama3.2Start/verify Ollama:
ollama listThis is useful when you want a local fallback or want to experiment without sending requests to a hosted provider.
NEXUS uses the GitHub REST API for repository intelligence and the guarded PR workflow.
Set:
GITHUB_TOKEN=YOUR_GITHUB_TOKENUse a fine-grained personal access token when possible.
GitHub recommends fine-grained tokens over classic tokens because access can be limited to selected repositories and specific permissions.
- Open GitHub.
- Go to Settings.
- Open Developer settings.
- Open Personal access tokens.
- Select Fine-grained tokens.
- Click Generate new token.
- Give it a descriptive name.
- Select an expiration.
- Restrict it to the test repository you want NEXUS to access.
- Grant only the permissions required by your workflow.
- Generate the token.
- Copy it immediately.
- Put it in
.env.local.
For the full GitHub workflow, NEXUS needs permission to read repository content and, when creating a PR, appropriate write permissions for repository contents and pull requests.
Official GitHub documentation:
GitHub permissions reference:
Never:
❌ commit GITHUB_TOKEN
❌ put it in React/client-side code
❌ paste it into screenshots
❌ put it in README.md
❌ upload it to GitHub
If a token is accidentally exposed, revoke/rotate it immediately.
Your real .env.local should look like:
GEMINI_API_KEY=real-secret
OPENROUTER_API_KEY=real-secret
GITHUB_TOKEN=real-secret
OMNIROUTE_API_KEY=real-secretbut those values must never be committed.
The repository should contain:
.env.example
and not:
.env.local
Recommended .gitignore entries:
.env
.env.local
.env.*.localInstall Node.js 22+.
Verify:
node --version
npm --versioncd C:\path\to\NEXUS-3.2.4-AUTONOMOUS-REMEDIATIONnpm installCopy-Item .env.example .env.localThe easiest starting options are:
AI_PROVIDER=omniroute
OMNIROUTE_BASE_URL=http://localhost:20128/v1
OMNIROUTE_API_KEY=YOUR_KEY
OMNIROUTE_MODEL=autoAI_PROVIDER=gemini
GEMINI_API_KEY=YOUR_KEY
GEMINI_MODEL=gemini-2.5-flashAI_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434/v1
OLLAMA_MODEL=llama3.2GITHUB_TOKEN=YOUR_GITHUB_TOKENnpm run devOpen:
http://localhost:3000
For a strong portfolio/demo video, use this sequence.
Open:
Command Center
Select:
Researcher AI
Enter:
18 * 7 + 4
Run the agent.
Expected result:
130
Open:
Security
Load the security demo.
Example vulnerable code:
const key = 'sk-demo-secret';
eval(input);
const html = userInput;
element.innerHTML = html;Run:
Scan code
Show the resulting findings.
Open:
Patch Engine
Generate patches.
Show:
eval(...)
↓
safe implementation
innerHTML
↓
textContent
The patch should show as validated before it becomes eligible for approval.
Create/use a test repository you control:
Krishna-Gudavalli/nexus-security-test
Enter:
Owner:
Krishna-Gudavalli
Repository:
nexus-security-test
Branch:
main
Then run:
GitHub Fetch
↓
Security Scan
↓
AI Patch
↓
Sandbox
↓
Approval
↓
Pull Request
For a real demo, use fake credentials only.
A deliberately vulnerable repository is useful for demonstrating the complete pipeline.
Example:
// INTENTIONALLY VULNERABLE — DEMO ONLY
export function calculate(expression) {
return eval(expression);
}// INTENTIONALLY VULNERABLE — DEMO ONLY
export const config = {
apiKey: "sk-test-1234567890-example-secret",
databasePassword: "SuperSecretPassword123!"
};// INTENTIONALLY VULNERABLE — DEMO ONLY
export function renderProfile(element, username) {
element.innerHTML = "Welcome " + username;
}These are fake demonstration values.
Do not replace them with real credentials.
Suppose the scanner finds:
Dynamic code execution
Hardcoded credential
Potential hardcoded secret
Potential HTML injection sink
NEXUS groups the findings.
Then Fixer AI proposes:
calculator.js
eval → constrained arithmetic parser
config.js
apiKey → process.env.NEXUS_SECRET
databasePassword → process.env.NEXUS_DB_PASSWORD
profile.js
innerHTML → textContent
The sandbox then re-scans the changed files.
If everything is resolved:
🟢 Sandbox PASSED
NEXUS moves to:
👤 Waiting for approval
After approval:
🌿 Create branch
↓
💾 Create commit
↓
🔀 Create PR
NEXUS is also designed to demonstrate failure safely.
Imagine the original repository has:
apiKey: "fake-secret",
databasePassword: "fake-password"but the patch only changes:
apiKey: process.env.NEXUS_SECRETThe database password remains hardcoded.
The sandbox re-scan detects:
❌ config.js:
Potential hardcoded secret remains
Therefore:
Sandbox:
FAILED
Approval:
BLOCKED
PR:
NOT CREATED
This is intentional.
It prevents a partially fixed repository from being presented as successfully remediated.
The architecture intentionally separates:
AI reasoning
from:
Git write authority
AI may generate a patch.
AI may validate a patch.
But Git writes require the guarded workflow.
This makes the system more appropriate for security-sensitive automation.
🧠 NEXUS
│
┌─────────┴─────────┐
│ │
Agent Runtime Security Control Plane
│ │
┌─────────┼─────────┐ │
↓ ↓ ↓ ↓
Researcher Security Fixer Scanner
│ │ │ │
└─────────┼─────────┘ │
↓ ↓
Tools Findings
│ │
└────────┬─────────┘
↓
AI Gateway
↓
┌────────┴────────┐
↓ ↓
Direct Providers OmniRoute
│ │
┌────────────┼────────────┐ │
↓ ↓ ↓ ↓
OpenAI Gemini Anthropic OpenRouter/
Ollama/etc.
│
↓
AI Response
│
↓
Patch Engine
│
↓
Sandbox Re-scan
│
┌─────────┴─────────┐
↓ ↓
BLOCKED PASSED
│ │
│ Human Approval
│ │
│ ↓
│ GitHub
│ │
│ ┌──────┴──────┐
│ ↓ ↓
│ Branch Commit
│ │
│ ↓
│ PR
↓
Manual remediation
The project is organized around the control-plane architecture.
NEXUS/
├── app/
│ ├── api/
│ │ ├── agents/
│ │ ├── github/
│ │ ├── providers/
│ │ ├── security/
│ │ ├── autopilot/
│ │ └── ...
│ ├── autopilot/
│ ├── security/
│ ├── ...
│ └── page.tsx
│
├── lib/
│ ├── agent-roles.ts
│ ├── ai.ts
│ ├── autopilot.ts
│ ├── github-api.ts
│ ├── model-router.ts
│ ├── provider-gateway.ts
│ ├── security.ts
│ ├── patch-engine.ts
│ ├── orchestrator.ts
│ ├── tools.ts
│ └── ...
│
├── worker/
├── scripts/
├── cli/
├── docs/
│ └── screenshots/
│
├── .env.example
├── package.json
├── tsconfig.json
└── README.md
Contains the deterministic security scanning logic, finding grouping, scoring, and autonomy policy.
Responsibilities include:
scanText()
scanPackageJson()
scanDockerfile()
groupFindings()
scoreFindings()
classifyRisk()
autonomyPolicy()
Provides patch proposal generation and patch validation.
It understands supported remediation patterns and rejects obviously unsafe patch content.
Coordinates the guarded repository workflow:
fetch
scan
patch
sandbox
approval
PR
It also creates the Git branch, commit tree, commit, and pull request after approval.
Wraps GitHub REST API operations such as:
repository information
branch references
commit information
repository tree
file content
branch creation
blob creation
tree creation
commit creation
ref update
pull request creation
Provides the provider abstraction.
It normalizes different AI APIs into one NEXUS interface.
It also handles:
provider selection
fallback order
API configuration
OpenAI-compatible providers
Gemini requests
Anthropic requests
SSE response parsing
bounded output tokens
provider errors
Coordinates specialist agents.
It:
- loads active agents
- scores agents against the task
- selects specialists
- chooses tools
- executes tools
- generates specialist responses
- synthesizes the results
After starting the application:
Main dashboard
http://localhost:3000
Security Autopilot
http://localhost:3000/autopilot
Security
http://localhost:3000/security
Agents
http://localhost:3000/agents
Models
http://localhost:3000/models
Health
http://localhost:3000/api/health
Providers
http://localhost:3000/api/providers
Exact route availability can depend on the current build.
Example:
POST /api/security/repository
Content-Type: application/jsonBody:
{
"owner": "Krishna-Gudavalli",
"repo": "nexus-security-test",
"branch": "main"
}The response can contain:
security score
risk level
findings
autonomy policy
analyzed files
grouped vulnerabilities
SBOM information
The project also includes:
npm run nexus -- run "Calculate 18 * 7 + 4"Security demo:
npm run security:demoDevelopment:
npm run devProduction:
npm run build
npm startLint:
npm run lintRun:
npm run buildA successful Next.js build should complete compilation and TypeScript validation without errors.
If you encounter stale build artifacts:
Remove-Item -Recurse -Force .next -ErrorAction SilentlyContinue
npm install
npm run buildDocker is optional.
Build/start:
docker compose up --buildOptional infrastructure profile:
docker compose --profile infra up -d postgres redisThe exact Docker configuration depends on the included compose files and environment configuration.
This usually means the selected provider rejected the request because of rate limits, credits, quota, or billing state.
Use a fallback:
AI_PROVIDER=omniroute
AI_FALLBACK_PROVIDERS=gemini,openrouter,ollamaor switch to another configured provider.
Check:
GEMINI_API_KEY=...Then restart:
npm run devEnvironment changes do not reliably apply to an already-running process.
Check:
OPENROUTER_API_KEY=...Also verify:
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1Verify the gateway:
curl http://localhost:20128/v1/modelsIf authentication is enabled:
curl http://localhost:20128/v1/models -H "Authorization: Bearer YOUR_KEY"Then confirm:
OMNIROUTE_BASE_URL=http://localhost:20128/v1
OMNIROUTE_API_KEY=YOUR_KEY
OMNIROUTE_MODEL=autoCheck:
ollama listThen verify:
http://localhost:11434
Pull the model:
ollama pull llama3.2This generally indicates an upstream API returned an empty/non-standard response.
NEXUS's provider gateway attempts to handle JSON and SSE-style responses and reports provider-specific failures.
Check:
/api/providers
and the terminal logs.
Check:
GITHUB_TOKEN
Then verify:
- token has not expired
- repository is included in the token
- required permissions are enabled
- organization approval is not blocking the token
- repository is accessible to the token owner
For PR creation, read-only permissions are not sufficient.
Do not bypass the sandbox.
Inspect:
sandbox.blocked
If the original finding remains, the correct behavior is to stop and fix the patch.
Use:
.env.local
and keep it out of Git.
Good:
sk-test-example
Bad:
real production API key
Give GitHub access only to the repository and permissions NEXUS actually needs.
Use:
localhost:20128
unless you have intentionally secured remote access.
Do not remove the approval requirement just to make a demo look more autonomous.
The approval gate is part of the security architecture.
Even if the patch looks correct:
AI proposal
↓
validation
↓
re-scan
↓
human review
is safer than:
AI proposal
↓
direct commit
NEXUS is a portfolio/research engineering platform and should not be described as a complete replacement for:
- enterprise SAST
- enterprise DAST
- secret-management platforms
- dependency vulnerability databases
- penetration testing
- formal security review
- production change-management systems
Its goal is to demonstrate a strong architecture for AI-assisted, guarded security remediation.
NEXUS demonstrates several engineering concepts in one project:
- specialist agents
- tool use
- multi-agent orchestration
- provider abstraction
- model routing
- fallback behavior
- SAST-style scanning
- secret detection
- injection detection
- CWE/OWASP mapping
- security scoring
- risk classification
- deterministic safe transformations
- patch proposals
- before/after changes
- patch validation
- re-scanning
- bounded repository analysis
- provider error handling
- SSE parsing
- fallback providers
- sandbox gates
- repository fetch
- branch creation
- Git object creation
- commits
- pull requests
- human approval
- risk-aware policies
- blocked critical changes
- audit-style logs
A strong video can tell this story in approximately 2–4 minutes:
Show:
NEXUS
Agents that actually work.
Say:
“NEXUS is an autonomous AI security and engineering platform that connects AI agents, GitHub, security scanning, safe remediation, validation, and pull requests.”
Show:
Researcher AI
Security AI
Fixer AI
Explain:
“Instead of one generic AI, NEXUS separates repository research, security analysis, and remediation into specialist agents.”
Enter:
18 * 7 + 4
Show:
130
Show vulnerable code:
eval(input);
element.innerHTML = userInput;Run the scanner.
Show the findings.
Show:
eval → safe parser
innerHTML → textContent
secret → environment variable
Show:
GitHub
↓
Scan
↓
Patch
↓
Sandbox
↓
Approval
↓
PR
Open GitHub and show the generated branch and pull request.
This is the strongest proof that the project is not merely a UI mockup.
The repository includes the supplied NEXUS screenshots under:
docs/screenshots/
Files:
01-security-autopilot.png
02-command-center-agents.png
03-model-router.png
04-ai-specialists.png
05-security-command-center.png
06-security-scan-result.png
07-ai-patch-engine.png
08-researcher-ai-demo.png
These are useful for GitHub documentation, project presentations, and portfolio pages.
For current provider setup instructions, always prefer the provider's own documentation because API dashboards, model names, quotas, billing, and authentication flows can change.
https://ai.google.dev/gemini-api/docs/api-key
https://platform.openai.com/docs/api-reference/
https://openrouter.ai/docs/quickstart
https://github.com/CarlaSalles-AI/omniroute
# 1. Install dependencies
npm install
# 2. Create environment file
Copy-Item .env.example .env.local
# 3. Configure at least one AI provider
# and GITHUB_TOKEN if using GitHub Autopilot
# 4. Start NEXUS
npm run dev
# 5. Open
# http://localhost:3000For OmniRoute:
npm install -g omniroute
omnirouteThen:
AI_PROVIDER=omniroute
AI_FALLBACK_PROVIDERS=gemini,openrouter,ollama
OMNIROUTE_BASE_URL=http://localhost:20128/v1
OMNIROUTE_API_KEY=YOUR_OMNIROUTE_ENDPOINT_KEY
OMNIROUTE_MODEL=autoFor Gemini:
AI_PROVIDER=gemini
GEMINI_API_KEY=YOUR_GEMINI_KEY
GEMINI_MODEL=gemini-2.5-flashFor GitHub:
GITHUB_TOKEN=YOUR_GITHUB_TOKENNEXUS 3.2.4 brings together:
🔎 Research
+
🛡️ Security Analysis
+
🔧 Safe Remediation
+
🧪 Validation
+
🔀 AI Routing
+
🐙 GitHub Automation
+
👤 Human Approval
+
🔀 Pull Requests
The final architecture is built around one principle:
Automate aggressively where it is safe, and stop where human judgment is required.
That makes NEXUS more than an AI demo.
It is a demonstration of how AI agents, software security, controlled automation, provider abstraction, and modern Git workflows can work together in a single engineering platform.
Krishna Gudavalli
GitHub:
https://github.com/Krishna-Gudavalli
NEXUS is built as a portfolio-grade demonstration of:
Full-Stack Development
AI Engineering
Cybersecurity
Agentic Systems
Cloud/API Integration
GitHub Automation
Responsible AI Automation
⭐ If you found the project interesting, consider starring the repository and exploring the implementation.