Ikanos¶

Ikanos is the capability engine at the heart of the Naftiko Fleet. It reads a Naftiko YAML specification at startup and immediately serves it as a multi-protocol server — MCP, Skill, REST, and Control — with no code generation or compilation step.

Ikanos comes from the Greek "ικανός" — capable.

What it does¶

Layer	Responsibility
Spec loader	Parses `*.naftiko.yml`, resolves `$ref`, applies `binds`, validates against the JSON Schema
Consumes runtime	Executes HTTP calls against upstream APIs with auth, format conversion, headers, retries
Orchestration	Runs `steps:` (call + lookup), evaluates JSONPath `mapping:`, threads variables across steps
Aggregates	Resolves `ref:` from MCP tools and REST operations, merges semantics into hints
Exposes runtime	Serves MCP (streamable HTTP + stdio), Skill (HTTP catalog), REST, and Control adapters
Observability	Emits OpenTelemetry traces and Prometheus RED metrics on the Control Port

What it is not¶

Not a code generator. No source files are produced. The spec is the artifact and the runtime contract.
Not a workflow engine. Multi-step orchestration is supported, but long-running workflows, schedules, and durable state are out of scope.
Not a service mesh. Ikanos focuses on the application contract; mesh features (mTLS between services, traffic shifting) live below it.

Where it fits¶

            ┌────────────────────────────────────────────────┐
            │              Ikanos process                    │
            │                                                │
   YAML ──► │  spec ──► consumes ──► steps ──► exposes ──►   │ ──► clients
   spec    │            (HTTP)      (call,     (MCP, Skill,  │     (AI agents,
            │                       lookup)    REST, Control)│      web apps,
            │                                                │      partners)
            │                ▲           ▲                   │
            │           OTel traces  Prometheus              │
            │                                                │
            └────────────────────────────────────────────────┘

One Ikanos process serves one capability. Multiple capabilities → multiple processes → orchestrated together by Skipper, with multi-region orchestration as an Enterprise premium feature on top of the single-host orchestration available in every edition.

Key features at a glance¶

Feature	Description
Spec-Driven Integration	Declare capabilities entirely in YAML — no Java required
Multi-Protocol Servers	Expose capabilities via MCP, Skill, REST, or Control
Data Format Conversion	Protobuf, XML, YAML, CSV, TSV, PSV, Avro, HTML, Markdown → JSON
HTTP API Consumption	Bearer, API key, basic, digest, OAuth 2.1 auth out of the box
Templating & Querying	Mustache templates and JSONPath expressions for flexible data mapping
Inline Scripting	Sandboxed JavaScript, Python, or Groovy steps via GraalVM
Domain-Driven Aggregates	Define reusable functions once, reference from multiple adapters
OpenAPI Interoperability	Import Swagger 2.0, OAS 3.0/3.1; export REST adapters as OpenAPI
Cloud-Native Operations	OTel tracing, RED metrics, Prometheus scrape, single Docker image
AI Native	Designed for context engineering and agent orchestration

For the full feature list see Features.

Continue reading¶

Installation — install via Docker or native binary
Use Cases — typical integration scenarios
Schema — the full reference for every keyword
Linting Guide — pair Ikanos with Polychro
Roadmap — what's coming in upcoming alphas