Getting Started

Getting Started with Best Practices

Set up Autonoma for maximum value—whether you prefer terminal, IDE, or web workflows. Configure integrations, import historical context, and optimize agent behavior from day one.

What's included in self-hosted GA

Twenty agents ship in the self-hosted bundle, organized into three operator-meaningful tiers: BUILD (code → merge), OPERATE (deploy → observe → recover), and SECURE (scan → hunt → remediate). Plus foundation agents that coordinate the rest. Every capability listed below is backed by shipping code in tools/ai-agents/.

BUILD7 agents

Take an idea from requirement to merged PR with full RIGOR pipeline coverage.

  • req-aiIngest requirements, draft acceptance criteria, persist to RequirementRepository
  • planner-aiDecompose work into ordered tasks with dependency resolution
  • architect-aiDesign components + persist architecture security reviews
  • coder-aiGenerate code, run real build verification, score perf hotspots + maintainability
  • tester-aiAuthor and run tests, report quality with sub-dimensions
  • debug-aiLocalize faults via stack/coverage adapters, validate fixes
  • review-aiPR review with real CodeAnalyzer + apply-suggestion wiring
OPERATE6 agents

Run, observe, and recover production workloads on AWS with real telemetry.

  • deploy-aiDeploy to AWS with strategy selection, pre-deploy security gate, drift detection
  • maintain-aiApply patches via SSM, post-deploy verify, automated rollback on failure
  • observe-aiCloudWatch metric correlation, deploy-completion subscription, anomaly triage
  • incident-aiPostgres-backed incident store, finding confirmation, security context replies
  • capacity-aiCloudWatch + Holt-Winters forecasting with cross-domain threat enrichment
  • backup-aiSnapshot orchestration, snapshot-on-threat NATS contract, recovery validation
SECURE2 agents

Scan code + infra for vulnerabilities, hunt threats, and remediate with audit trail.

  • security-aiContinuous scanning across source, dependencies, containers, and IaC; secrets detection; compliance mapping (SOC2/PCI/HIPAA); auto-PR remediation through the BUILD pipeline
  • threathunter-aiAlways-on threat hunting with IOC matching, MITRE ATT&CK technique mapping, attack-path analysis, ML anomaly detection, and threat-intel feed enrichment

Foundation agents (coordinate the tiers)

  • orchestrator-aiMulti-agent task routing, classifier + topo-sort, workflow create/lookup
  • data-aiData persistence layer for shared agent state
  • training-aiPerAgent training service + GRM coordinator (closed-loop training pipeline)
  • orchestrator-ai-v2 / v3Shadow orchestrators with real policyEngine + RuntimeConfidence/ContextQuality signals

Security capabilities (always-on)

Both security-ai and threathunter-ai run 24/7 — they catch issues at 3am, not just during business hours.

security-ai — find & fix

  • Source code analysis — SAST patterns, taint tracking, injection risks
  • Dependency audit — CVE matching against your manifest, transitive risk graphs
  • Container scanning — base-image vulnerabilities, layer-level CVEs
  • IaC validation — Terraform / CloudFormation / Helm misconfigurations
  • Secrets detection — active code + commit history, regex + entropy
  • Compliance mapping — SOC2, PCI-DSS, HIPAA control coverage reports
  • Auto-PR remediation — critical findings route into the BUILD pipeline as remediation tasks for coder-ai + review-ai to land

threathunter-ai — detect & respond

  • IOC matching — IPs, domains, file hashes against curated and customer feeds
  • MITRE ATT&CK mapping — observed activity → technique IDs with confidence scores
  • Attack-path analysis — multi-stage chain reconstruction across logs and telemetry
  • ML anomaly detection — baselined behavioral models flag deviations
  • Detection-rule engine — converts community rules into the runtime hunt format
  • Threat-intel enrichment — pulls reputation, campaign attribution, and context from feeds
  • Incident hand-off — confirmed findings post to incident-ai for triage and runbook execution

Both agents emit findings to knowledge-graph for cross-agent learning, and to incident-ai for any finding that crosses your severity threshold.

Roadmap / Commercial tier (not in self-hosted GA)

The following agent tiers are not included in the self-hosted GA bundle. They're available in the hosted commercial tier or on the roadmap.

  • GOVERN: Multi-tenant policy enforcement (govern-ai, policy-ai, tenant-ai). Available in commercial tier.
  • OPTIMIZE: Cost / DBA / billing optimization (optimize-ai, cost-ai, dba-ai, billing-ai). Available in commercial tier.
  • EVOLVE: Adaptive workload + customer-success learning (adapt-ai, evolve-ai, success-ai). Available in commercial tier.

1. Choose Your Workflow

Autonoma adapts to how you work. Select your preferred interaction style:

Terminal-First

Command-line developers who prefer shell scripts and automation

RECOMMENDED:
CLIAPI

Install CLI globally, configure shell aliases, use RIGOR commands

IDE-Based

Developers using VS Code, JetBrains, Neovim, Emacs, or Sublime Text

RECOMMENDED:
IDE ExtensionDashboard

Install the A6s extension for your editor, connect to CLI daemon

Web Dashboard

Teams preferring visual interfaces and point-and-click workflows

RECOMMENDED:
DashboardAPI

Use dashboard for all operations, API for custom integrations

2. Set Up Access Methods

Get your tools configured for immediate productivity:

⚡ 5-minute developer quickstart

  1. 1. Get your API key — Dashboard → API Keys → Create Key. The plaintext key is shown once.
  2. 2. Install the CLI + daemon — one command: npm install -g @autonoma-io/a6s
  3. 3. Install the IDE extension for your editor (below). It auto-connects to the daemon at ws://localhost:9876.

VS Code

Marketplace install + zero config — the daemon connection is automatic.

# 1. Install CLI + daemon
npm install -g @autonoma-io/a6s
export A6S_API_KEY=<paste-key-from-dashboard>

# 2. Start daemon (background)
a6s code --daemon &

# 3. Install extension
code --install-extension autonoma.autonoma-code

# 4. Open any file → ⌘⇧P → "A6s: Invoke"
#    (extension auto-connects to ws://localhost:9876)
Full VS Code guide

JetBrains (IntelliJ / WebStorm / PyCharm / GoLand)

One marketplace search; same daemon underneath.

# 1. Install CLI + daemon
npm install -g @autonoma-io/a6s
export A6S_API_KEY=<paste-key-from-dashboard>
a6s code --daemon &

# 2. In IDE: Settings → Plugins → Marketplace
#    Search "A6s" → Install → Restart

# 3. Tools menu → A6s → Invoke
#    (or right-click in editor → "A6s: Refactor / Review / …")
Full JetBrains guide

Neovim (lazy.nvim)

Lua plugin connects to the same local daemon.

-- 1. Install CLI + daemon
-- (in shell)
-- npm install -g @autonoma-io/a6s
-- export A6S_API_KEY=<paste-key-from-dashboard>
-- a6s code --daemon &

-- 2. In your lazy.nvim spec
{
  "The-Autonoma/a6s-nvim",
  config = function() require("a6s").setup({}) end,
}

-- 3. :A6sInvoke   or   :A6sReview
Full Neovim guide

Emacs / Sublime Text

Same daemon, two install paths.

# Shared CLI + daemon setup
npm install -g @autonoma-io/a6s
export A6S_API_KEY=<paste-key-from-dashboard>
a6s code --daemon &

# --- Emacs (use-package) ---
(use-package a6s
  :hook (prog-mode . a6s-mode)
  :bind ("C-c a" . a6s-invoke))

# --- Sublime Text ---
# Package Control → Install Package → A6s
# Command Palette → "A6s: Invoke"
Full Emacs / Sublime guide

CLI-only (no IDE)

Same daemon, invoked directly. Useful for CI/CD and terminal-first developers.

# Install
npm install -g @autonoma-io/a6s
export A6S_API_KEY=<paste-key-from-dashboard>

# Invoke directly (no daemon needed)
a6s agents list
a6s code refactor src/server.ts --goal "extract auth middleware"
a6s code review src/server.ts
a6s rigor analyze --phase research
a6s workflow run deploy-staging
a6s status
Full CLI reference

Web Dashboard

Visual interface for monitoring, configuration, and approvals

Real-time agent activity monitoring
ACMF mode management per agent
Human approval workflows
RIGOR execution history and audit logs
Open Dashboard

REST API

Direct API access for custom integrations and automation

# Invoke RIGOR agent
curl -X POST 'https://api.theautonoma.io/api/v1/rigor/invoke/coder-ai' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "Generate unit tests for auth module",
    "priority": "normal",
    "acmfMode": "ASSISTED"
  }'

# Check execution status
curl 'https://api.theautonoma.io/api/v1/rigor/status/exec-123' \
  -H 'Authorization: Bearer YOUR_API_KEY'
API Reference

3. Connect Third-Party Integrations

Import historical project context and enable real-time synchronization with your existing tools:

AWS CloudWatch

Monitoring

~10 min setup

Sync metrics, logs, and alarms for unified observability

Metrics ingestionLog aggregationAlarm triggersDashboard sync

PagerDuty

Incident Management

~5 min setup

Route alerts, manage on-call schedules, automate escalations

Event routingIncident triggersEscalation policiesResolution tracking

Datadog

APM & Monitoring

~10 min setup

Full-stack observability with APM, logs, and infrastructure metrics

APM tracesCustom metricsLog forwardingDashboard integration

Jira

Project Management

~15 min setup

Sync issues, automate workflows, connect development to planning

Webhook eventsIssue creationStatus syncSprint integration

Slack

Native

Communication

~5 min setup

Native integration for alerts, approvals, and team notifications

Alert notificationsApproval workflowsAgent commandsStatus updates

AWS CloudWatch Integration

Configuration

# autonoma.config.yaml
integrations:
  cloudwatch:
    enabled: true
    region: us-east-1
    credentials:
      access_key_id: ${AWS_ACCESS_KEY_ID}
      secret_access_key: ${AWS_SECRET_ACCESS_KEY}

    # Metrics to sync
    metrics:
      namespaces:
        - AWS/ECS
        - AWS/RDS
        - Custom/Autonoma
      period: 60  # seconds

    # Log groups to ingest
    logs:
      groups:
        - /aws/ecs/autonoma-alpha
        - /aws/lambda/autonoma-*

    # Alarm integration
    alarms:
      sync_existing: true
      create_autonoma_alarms: true
      sns_topic_arn: arn:aws:sns:us-east-1:xxx:alerts

Best Practices

  • • Use CloudWatch Embedded Metric Format for high-cardinality data
  • • Enable detailed monitoring (1-min intervals) for critical resources
  • • Create composite alarms to reduce alert fatigue
  • • Use Anomaly Detection for dynamic thresholds
  • • Tag resources consistently for filtering
AWS CloudWatch Best Practices

PagerDuty Integration

Events API v2 Configuration

# autonoma.config.yaml
integrations:
  pagerduty:
    enabled: true
    # Get routing key from PagerDuty service integration
    routing_key: ${PAGERDUTY_ROUTING_KEY}

    # Event routing rules
    routing:
      critical:
        severity: critical
        class: infrastructure
      warning:
        severity: warning
        class: application

    # Dedup key strategy
    dedup_strategy: deployment_id  # or: alert_type, custom

    # Webhook for bi-directional sync (V3)
    webhooks:
      enabled: true
      endpoint: https://api.theautonoma.io/webhooks/pagerduty
      events:
        - incident.triggered
        - incident.acknowledged
        - incident.resolved

Security Notes

  • • Store routing key in environment variables, never in code
  • • Use V3 webhooks (V2 is end-of-support)
  • • Verify webhook signatures using X-PagerDuty-Signature header
  • • Use dedup_key to prevent duplicate incidents
PagerDuty Events API v2 Docs

Datadog Integration

Configuration

# autonoma.config.yaml
integrations:
  datadog:
    enabled: true
    api_key: ${DD_API_KEY}
    app_key: ${DD_APP_KEY}
    site: datadoghq.com  # or datadoghq.eu

    # Metrics submission
    metrics:
      enabled: true
      prefix: autonoma
      tags:
        - env:production
        - service:autonoma

    # APM trace correlation
    apm:
      enabled: true
      service_name: autonoma-agents

    # Log forwarding
    logs:
      enabled: true
      source: autonoma
      service: autonoma-rigor

    # Events (deployments, incidents)
    events:
      enabled: true
      aggregation_key: autonoma_deployment

OpenTelemetry Support

Autonoma supports OTel for vendor-agnostic telemetry:

OTEL_EXPORTER_OTLP_ENDPOINT=https://api.datadoghq.com
OTEL_EXPORTER_OTLP_HEADERS=DD-API-KEY=${DD_API_KEY}
Datadog API Reference

Jira Integration

Webhook + REST API Configuration

# autonoma.config.yaml
integrations:
  jira:
    enabled: true
    base_url: https://yourcompany.atlassian.net

    # Authentication (use API token, not password)
    auth:
      email: ${JIRA_EMAIL}
      api_token: ${JIRA_API_TOKEN}

    # Project mapping
    projects:
      default: PROJ
      mapping:
        infrastructure: INFRA
        security: SEC

    # Webhook events to receive
    webhooks:
      endpoint: https://api.theautonoma.io/webhooks/jira
      events:
        - jira:issue_created
        - jira:issue_updated
        - jira:sprint_started
        - jira:sprint_closed

    # Issue creation templates
    templates:
      bug:
        project: PROJ
        issuetype: Bug
        priority: Medium
      task:
        project: PROJ
        issuetype: Task

GitHub + Jira Automation

Connect GitHub PRs to Jira issues automatically:

  1. Create Automation rule with "Incoming webhook" trigger
  2. Configure GitHub webhook for Pull Request events
  3. Use Smart Values to extract PR data
  4. Auto-transition issues based on PR status

Slack (Native Integration)

Autonoma includes native Slack integration with no additional configuration required.

# Simply enable in your dashboard or config
integrations:
  slack:
    enabled: true
    # OAuth installed via dashboard - one-click setup

    channels:
      alerts: "#autonoma-alerts"
      approvals: "#autonoma-approvals"
      deployments: "#deployments"

    notifications:
      - type: deployment_started
        channel: deployments
      - type: approval_required
        channel: approvals
        mention: "@oncall"
      - type: alert_critical
        channel: alerts
        mention: "@here"

4. Configure Agent Behavior (ACMF)

Set the appropriate autonomy level for each agent based on your risk tolerance:

ModeBehaviorRisk LevelRecommended Use Case
OBSERVEObserve only, no executionNoneInitial deployment, learning phase
LEARNINGExecute with full reviewLowBuilding confidence, pattern recognition
ASSISTEDExecute, approve critical onlyMediumNormal operations
AUTONOMOUSFull autonomy, audit trailManagedTrusted, mature agents

Sample ACMF Configuration

# autonoma.config.yaml
agents:
  # Start observability agents in AUTONOMOUS mode
  observe-ai:
    acmf_mode: AUTONOMOUS
    capabilities: [self-monitoring, self-diagnosing]

  # Code generation in ASSISTED mode (review changes)
  coder-ai:
    acmf_mode: ASSISTED
    capabilities: [self-coding, self-testing]
    approval_required_for:
      - production_changes
      - security_sensitive

  # Deploy in LEARNING mode initially
  deploy-ai:
    acmf_mode: LEARNING
    capabilities: [self-deploying]
    progression:
      to_assisted:
        success_rate: 0.95
        min_tasks: 50
        consecutive_success: 10

5. Quick Reference: Sample Commands

Common commands to get started immediately:

Your first invocation — IDE

# VS Code:
#   ⌘⇧P (Mac) / Ctrl+Shift+P (Linux/Win)
#   "A6s: Refactor Selection"
#   (or "A6s: Review File", "A6s: Generate Tests")

# JetBrains:
#   Tools menu → A6s → Invoke
#   Right-click in editor → A6s: Refactor

# Neovim:
#   :A6sInvoke
#   :A6sReview

# Emacs:
#   C-c a   (a6s-invoke)

Your first invocation — CLI

# Refactor a file with a goal
a6s code refactor src/server.ts \
  --goal "extract auth middleware"

# Review a file for issues
a6s code review src/server.ts

# Generate tests for a file
a6s code generate-tests src/auth.ts

# Invoke any agent directly
a6s invoke coder-ai "add rate limiting to /api/login"

RIGOR Workflow Commands

# Research phase - gather context
a6s rigor research "implement user auth"

# Inspect phase - validate constraints
a6s rigor inspect --project ./

# Generate phase - create implementation
a6s rigor generate --task "add JWT auth"

# Optimize phase - improve performance
a6s rigor optimize --target latency

# Review phase - validate outcome
a6s rigor review --execution exec-123

Agent & Workflow Commands

# List available agents
a6s agents list

# Invoke specific agent
a6s invoke architect-ai "design payment service"

# Create deployment workflow
a6s workflow create deploy-staging \
  --trigger git-push \
  --branch staging

# Check system health
a6s status

# View audit logs
a6s logs --agent deploy-ai --last 1h