How to Run Strix in Headless Mode for Automated CI/CD Pipelines

Run Strix with the -n or --non-interactive flag to disable the Text-User-Interface (TUI) and execute fully headless, streaming findings to stdout and exiting with code 2 when vulnerabilities are detected.

Strix is an AI-powered security scanning tool from the usestrix/strix repository designed for automated vulnerability detection. Running Strix in headless mode eliminates the need for an interactive terminal, making it ideal for integration into CI/CD pipelines, containerized environments, and scheduled security scans.

The Non-Interactive Flag

Strix provides the --non-interactive (short form -n) boolean flag in strix/interface/main.py (lines 336–343) to bypass the interactive TUI. When this flag is present, the application calls asyncio.run(run_cli(args)) instead of launching the TUI, enabling the scanner to operate in environments without a TTY.

Architecture of Headless Execution

CLI Argument Parsing

In strix/interface/main.py (lines 336–343), the argument parser defines --non-interactive as a boolean flag. This setting determines the execution path within the main() function, ensuring that CI environments can invoke the tool without triggering interactive widgets.

Main Entry Point and Exit Codes

The main() function in strix/interface/main.py (lines 557–579) implements the critical logic for automated pipelines. After parsing arguments, it checks args.non_interactive:

• If true: Executes asyncio.run(run_cli(args)) and, upon completion, exits with code 2 when any vulnerability reports are generated
• If false: Launches the TUI via run_tui()

The exit code 2 behavior enables pipelines to automatically fail when security findings are detected, gating deployments based on scan results.

CLI Runner Implementation

The run_cli function in strix/interface/cli.py handles the headless execution flow. Instead of interactive widgets, it prints a static startup panel, streams live statistics to stdout, and outputs a final summary panel. This implementation writes the complete report to strix_runs/<run-name> while maintaining console output suitable for CI logs.

Browser Automation in Headless Mode

When scans require browser automation (e.g., for XSS detection or authentication flows), Strix ensures headless operation at the tooling level. In strix/tools/browser/browser_instance.py (lines 63–66), the Playwright browser instance launches with headless=True, guaranteeing that browser-based tools function in display-less container environments regardless of the CLI mode.

Command-Line Usage Examples

Basic Headless Scan

Execute a quick security scan against a live application without interactive elements:

strix -n -t https://my-app.example.com --scan-mode quick

• -n: Enables non-interactive (headless) mode
• -t: Specifies the target URL (repeatable for multiple targets)
• --scan-mode quick: Uses lightweight scanning suitable for CI (default is deep)

The command streams findings to stdout, writes the full report to strix_runs/<run-name>, and exits with code 2 if vulnerabilities are found.

Headless Scan with Custom Instructions

Provide detailed scope, authentication, or vulnerability focus via an instruction file:

strix -n -t ./my-service \
      --instruction-file ./ci-instructions.txt \
      --scan-mode standard

CI/CD Pipeline Integration

GitHub Actions Workflow

Integrate Strix into pull request checks to block merges with security regressions:

name: Security Scan with Strix

on:
  pull_request:
    branches: [ main ]

jobs:
  strix-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Strix
        run: curl -sSL https://strix.ai/install | bash

      - name: Run Strix (headless)
        env:
          STRIX_LLM: ${{ secrets.STRIX_LLM }}
          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
        run: |
          strix -n -t ./ --scan-mode quick

The workflow sets LLM configuration via repository secrets. Because the CLI runs with -n, the job fails automatically when Strix detects vulnerabilities, preventing insecure code from reaching the main branch.

GitLab CI Configuration

Run Strix in a Python-based container with explicit environment variable exports:

strix_scan:
  image: python:3.11-slim
  stage: test
  script:
    - apt-get update && apt-get install -y curl
    - curl -sSL https://strix.ai/install | bash
    - export STRIX_LLM="anthropic/claude-sonnet-4.6"
    - export LLM_API_KEY="${LLM_API_KEY}"
    - strix -n -t https://staging.example.com --scan-mode quick

Exit Codes and Automation Gates

Strix uses specific exit codes to communicate scan results to CI systems:

• Exit 0: Scan completed successfully with no vulnerabilities detected
• Exit 2: Scan completed but vulnerability reports were generated (configurable gate failure)
• Other non-zero: Critical errors or crashes during execution

According to the source code in strix/interface/main.py, the exit code 2 is explicitly set when findings exist, allowing pipeline configurations to use set -e or equivalent error-on-failure mechanisms to automatically halt deployments when security issues arise.

Summary

• Use the -n or --non-interactive flag in strix/interface/main.py to disable the TUI and enable headless execution
• The main() function exits with code 2 when vulnerabilities are found, enabling automated pipeline gating
• The run_cli implementation in strix/interface/cli.py provides static console output suitable for CI logs without interactive elements
• Browser automation automatically runs headlessly via headless=True in strix/tools/browser/browser_instance.py, ensuring compatibility with containerized environments
• Reports are written to strix_runs/<run-name> while findings stream to stdout for immediate CI feedback

Frequently Asked Questions

What exit code does Strix return when vulnerabilities are found in headless mode?

Strix exits with code 2 when any vulnerability reports are generated during a headless scan. This behavior is implemented in strix/interface/main.py (lines 557–579) and allows CI/CD systems to automatically fail builds or block deployments when security issues are detected.

Does Strix require a display or browser setup in CI environments?

No. Strix launches Playwright browser instances with headless=True in strix/tools/browser/browser_instance.py (lines 63–66), ensuring all browser automation functions in display-less containers. This is independent of the CLI's --non-interactive flag and guarantees XSS and authentication testing work in pure CI environments.

How do I configure LLM providers when running Strix in CI/CD?

Set the STRIX_LLM and LLM_API_KEY environment variables before invoking the CLI. These variables configure the underlying AI provider without requiring interactive configuration. In GitHub Actions or GitLab CI, store these as repository or project secrets and reference them in your workflow environment blocks.

Can I run Strix headless against multiple targets simultaneously?

Yes. The -t flag accepts multiple targets when repeated. For example: strix -n -t https://api.example.com -t https://app.example.com --scan-mode quick. Strix processes all specified targets in a single headless execution, aggregating findings into the final report and maintaining a single exit code for the entire scan suite.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}