Introducing DOIL: The Language Behind Agentic Network Operations

There's a question that has driven me throughout my OSS/BSS/NOC solutions career: How do you capture the moment of operational genius? That split second when an expert sees the solution, understands the pattern, knows exactly what needs to happen?

I've been thinking about this for thirty years. From building web CRUD with raw HTML and PHP in the 90s, through working with some of the largest telecom vendors and technology giants, to collaborating with governments and major corporations on billion-dollar infrastructure investments.

The journey took me across innovation centers, research hubs, technical universities, and massive network deployments. Each environment taught me something different about how expertise manifests in complex systems.

Here's what struck me: In operations support systems and operation centers, we've been solving the wrong problem.

Recently, I watched David Heinemeier Hansson reflect on Rails' approach in a 6-hour interview . He spoke about how Rails wasn't about capturing intention, but about making the complex feel simple. It reminded me of something deeper I'd been wrestling with in network operations centers worldwide. It's complexity that can only be absorbed and overcome by experts. Their brain thinks different, so we need something that captures their chain of thought, driven by intent, not programmers' hypercapacity approach.

Now, agentic frameworks and AI automation are sweeping across telecom and operations industries like a wave. Everything is changing fast. NOC operations have evolved beyond pure engineering—they will become full orchestration centers very soon everywhere, where human insight guides intelligent agents.

In these modern NOCs, we will see new patterns. Not just in the data, but in how the best operators think. How they orchestrate solutions across human and AI teams. How they see connections between systems that others miss. These experts don't just solve problems—they conduct symphonies of intelligence.

Think of a master violinist performing without sheet music—pure improvisation, emotion flowing through decades of technique. We still write music down. Not because the violinist needs it, but because we want to capture that genius, preserve it, and amplify it across time and space.

DOIL — the Dark Operations Intent Language — is the attempt to create musical notation for operational brilliance.

I've watched automation evolve, and not to be modest, I always envisioned it reaching the level of intent. When an operator intuitively knows how to orchestrate agents for optimization, when an engineer can choreograph the perfect sequence of tools, when an expert sees exactly which agents to deploy and how they should collaborate—that's not just skill. That's artistry. That's human creativity at its peak.

This vision led me to the concept of "Dark Operations"—that moment when you can switch the lights off in a NOC and everything still runs perfectly. Not because humans aren't needed, but because human genius has been captured, amplified, and transformed into executable intelligence.

I am trying to build instruments for experts that embody this dark operations philosophy. DOIL attempts to preserve that moment of creative birth—that flash of insight when an expert sees the solution—and transform it into something that can be performed by AI agents across the entire infrastructure symphony.

Your wish becomes their command. As natural as playing violin, as powerful as conducting an orchestra.

That's the promise of DOIL and the DarkNOC vision.

DOIL is not just a technical feature; it is the manifestation of this new approach. A way of saying: we can describe what needs to happen without micromanaging every detail. I've observed that the best abstractions don't hide complexity—they capture human insight and make it reproducible.

From Thought to Language: Why We Need DOIL

I've always been fascinated by the gap between human intent and machine execution.

We don't build systems just to control them — we build them to understand, to respond, to evolve with us. But how do you express operational intent clearly enough that an autonomous agent can act on it?

Not with scripts. Not with JSON. Not with dashboards full of checkboxes.

Working across different ecosystems, I realized we needed a middle ground: something as expressive as a prompt, as structured as a spec, and as composable as a microservice.

That's why I created DOIL—a Ruby-inspired, Git-native, intent-first agent programming language that captures the way expert operators actually think. It's the language for the future we need now.

DOIL in Action: Real Syntax

Here's a basic example of what a .doil file looks like (this is just a simple subset of the language's capabilities):

# EnergySaverAI - Ruby-style DOIL Agent
class EnergySaverAI < BaseNetworkAgent
  version "2.1.3"

  # Agent description using Ruby heredoc
  description <<-DESC
    Autonomously reduce energy consumption during low-traffic periods
    by intelligently adjusting transmission power while maintaining
    network quality and ensuring seamless failover capabilities.
  DESC

  # Dynamic constants and variables
  LOW_TRAFFIC_THRESHOLD = 0.3
  MAX_POWER_REDUCTION = 40.percent
  NIGHT_HOURS = (22..5).to_a + [0, 1]

  attr_reader :current_traffic, :energy_savings, :active_sites

  # When should this agent activate?
  triggers do
    every 15.minutes
    on_event :traffic_threshold_low
    manual true
  end

  # Data sources with transformation pipelines
  data_sources do
    kpis "tmf/pm_data.json" | normalize_traffic_metrics
    thresholds "config/energy_policy.yaml"
    topology "network/site_graph.json" | filter("status == 'active'")
  end

  # Available tools with Ruby-style configuration
  tools do
    traffic_analyzer window: 30.minutes, granularity: :cell
    power_controller safety: true, max_reduction: MAX_POWER_REDUCTION
    rollback_guard timeout: 5.seconds
  end

  # Main execution logic
  def execute
    @current_traffic = analyze_current_load
    @active_sites = get_active_sites

    return abort_and_notify("Emergency override active") if emergency_override?

    if low_traffic_period? && night_hours?
      potential = calculate_optimization_potential
      simulation = simulate_power_reduction(potential)

      if simulation.safe? && simulation.savings > 5.percent
        apply_changes_gradually(simulation)
        @energy_savings = simulation.savings
      end
    end

    generate_reports
    notify_significant_savings if @energy_savings > 10.percent
  end

  private

  def low_traffic_period?
    @current_traffic.load < LOW_TRAFFIC_THRESHOLD
  end

  def night_hours?
    NIGHT_HOURS.include?(Time.now.hour)
  end

  def emergency_override?
    config[:emergency_override] == true
  end

  def generate_reports
    timestamp = Time.now.strftime("%Y%m%d_%H%M")

    render_markdown "reports/energy_optimization_#{timestamp}.md",
                   template: "templates/energy_report.md"

    export_metrics "metrics/energy_savings.json",
                   schema: "schemas/energy_metrics.json"
  end

  def notify_significant_savings
    notify :slack, :email do
      "Energy optimization complete! Achieved #{@energy_savings.round(1)} savings."
    end
  end

  # UI Layout - Clean DSL syntax
  ui theme: :dark do
    network_map input: :topology, zoom: :auto, highlight: @active_sites.optimized
    realtime_chart input: "metrics/energy_savings.json", refresh: 30.seconds
    markdown_viewer input: "reports/energy_optimization_#{timestamp}.md", collapsible: true
  end
end

This isn't just config. This defines an agent, describes its job, binds the data, and also lays out the front-end interface—all in one file. Notice the sophisticated language features: conditional logic, workflow steps, parameter passing, templating, and structured output definitions.

The compiler then:

• Parses it deterministically
• Compiles it into a LangGraph executable agent flow
• Generates a Next.js front-end with visual outputs and live context
• (If enabled) uses LLMs to refine prompts or adapt the UI layout

DOIL bridges everything—data, AI, UI—under a single declarative interface. You can explore working examples of these unified interfaces at darknoc.net and find production-ready DOIL agents at darknoc.org.

DOIL can be as short as this and still deliver complex agent behavior:

class QuickMonitor < BaseAgent
  description "Watch system health, alert on issues"

  triggers { every 5.minutes }
  data_sources { metrics "api/health.json" }
  tools { slack_notifier, email_alerts }

  def execute
    health = get_system_health
    notify_if_critical(health) if health.critical?
  end
end

Ten lines. Full agent with scheduling, data integration, tool access, and logic. The compiler generates the complete infrastructure.

The Compiler: Controlled and LLM-Enhanced

DOIL Compiler Modes:

You can choose which mode per project or per agent.

VSCode, Cursor, and IDE Integration

DOIL is meant to be developer-native. I've seen that the best languages feel natural in your editor. The workflow is:

• .doil files open in VSCode or Cursor
• Live syntax highlighting via LSP
• Auto-suggestions for fields, components, and tools
• "Run Agent" button built into the editor
• Real-time preview of the generated front-end layout
• Git commit hooks that validate .doil structure before deployment

We're providing:

• A darknoc-language-server (LSP)
• A VSCode extension with smart snippets
• Cursor-native support for CoAgent compilation

Where It Works Best: Beyond Telecom

DOIL was born out of telecom challenges—5G networks, alarm floods, config sprawl, and digital twins. But working across different industries taught me that operational patterns are universal. The same thinking that optimizes networks can manage energy grids, security systems, or data centers anywhere.

NOC-style automation with DOIL can be applied to:

• Enterprise IT and infrastructure
• Industrial automation and robotics
• Cybersecurity and threat response
• Energy grid operations and smart metering
• Airport and rail system control
• Aerospace mission control
• Live broadcast event management
• Healthcare systems and smart hospitals

Anywhere you have agents, data, and decisions — you can use DOIL.

Why Not JSON? Why Not YAML Only? Why Not Just Code?

Because I've seen what doesn't work. These approaches don't scale across human intention. They don't help teams reason, collaborate, or visualize agent workflows.

DOIL gives you:

• Ruby-inspired syntax that feels natural to developers
• A Git-native declarative spec for agents
• UI layout as a first-class construct
• LLM-tuned flexibility where needed

You're not reinventing programming. You're raising it to the level of intention.

The Dark Operations Framework

The concept of "DarkNOC" isn't just about automation—it's about that moment when you can switch the lights off and everything still runs perfectly. I've seen this vision emerging in operations centers worldwide. The best centers become invisible, not because they're unmanned, but because human expertise has been captured and amplified.

DOIL is the foundation for building efficient Dark Operations frameworks. It's about encoding the intuition of expert operators, the patterns that emerge from years of troubleshooting complex systems, the orchestration knowledge that can't be captured in traditional documentation.

When you switch the lights off, the genius remains. That's what I'm building toward.

Toolchain and Next Steps

I'm releasing the DOIL toolchain as part of the darknoc.dev suite:

• ✅ doil compile — turns .doil into JSON, LangGraph, and .tsx components
• ✅ VSCode plugin — highlighting, validation, previews, AI-enhanced layout support
• ✅ LLM plugin — optional layer that enhances vague intents or prompt design
• ✅ Next.js scaffolder — builds UI shells and agent interfaces
• ✅ Cursor AI integration — compile, deploy, test from one unified interface
• ✅ GitOps-ready — version .doil alongside code and infra

You write .doil. Everything else follows.

Begin the Next Era

Visit darknoc.dev and open the DOIL Playground.

Start with:

$ npx darknoc init
$ code energy_optimizer.doil

Click "Compile + Preview" and watch the system come alive.

This feels like the next natural step. DOIL is doing for operations what Rails did for web development—not just making things easier, but capturing the way experts think and making it reproducible.

You're not managing code. You're sculpting intent.

Welcome to DOIL.

— The inventor of DOIL and architect of Dark Operations