Your First Fleet¶

A fleet is what happens when you stop running a single capability and start composing several of them together — authoring, linting, running, governing, and orchestrating them as a group.

With the v1.0 Alpha 3 release, the canonical Naftiko Fleet workflow is available end-to-end: many small capabilities, each in its own YAML file, authored in Crafter, validated by Polychro, executed by Ikanos, governed by Warden, and orchestrated by Skipper on Kubernetes.

This guide walks through a minimal fleet you can run entirely on your laptop with two Ikanos capabilities and the Polychro linter, then shows the same setup deployed under Skipper on Kubernetes and surfaced in Warden inside Backstage.

Prerequisites. Ikanos and Polychro installed — see Installation. Crafter is optional but recommended for authoring. For the Kubernetes section, have Skipper installed in a cluster (also covered in Installation).

If you have not yet run a single capability, do the Quickstart first.

Scenario¶

You will:

1. Author two capabilities in Crafter — one consuming the Maritime Registry API, one consuming a Crew API.
2. Lint both with Polychro in one command, using a shared ruleset.
3. Run them side by side with two Ikanos processes, each exposing MCP.
4. Discover the union of their tools from a single MCP client.
5. (Optional) Deploy the same files to Kubernetes as Capability CRDs under Skipper.
6. (Optional) Surface the fleet in your Backstage developer portal through Warden.

1. Author the capabilities (in Crafter)¶

Put the following two files in a folder called fleet/ (lowercase — this is your runtime fleet). The Crafter VS Code extension picks them up automatically by file name (*.naftiko.yml) and provides inline validation and quick fixes:

ikanos: "1.0.0-alpha3"
info:
  display: Maritime Registry
capability:
  consumes:
    - namespace: registry
      type: http
      baseUri: "https://mocks.naftiko.net/rest/naftiko-shipyard-maritime-registry-api/1.0.0-alpha3"
      resources:                          # alpha3 — keyed map
        ships:
          path: "/ships/{{imo}}"
          operations:                     # alpha3 — keyed map
            get-ship:
              method: GET
              inputParameters:            # alpha3 — keyed map
                imo: { in: path, required: true }
  exposes:
    - type: mcp
      port: 3001
      namespace: registry-tools
      tools:                              # alpha3 — keyed map
        get-ship:
          inputParameters:
            imo: { type: string, required: true }
          call: registry.get-ship
          with: { imo: registry-tools.imo }

ikanos: "1.0.0-alpha3"
info:
  display: Crew Roster
capability:
  consumes:
    - namespace: crew
      type: http
      baseUri: "https://mocks.naftiko.net/rest/naftiko-shipyard-crew-api/1.0.0-alpha3"
      resources:                          # alpha3 — keyed map
        roster:
          path: "/crew"
          operations:                     # alpha3 — keyed map
            list-crew:
              method: GET
  exposes:
    - type: mcp
      port: 3002
      namespace: crew-tools
      tools:                              # alpha3 — keyed map
        list-crew:
          call: crew.list-crew

2. Lint the whole fleet with Polychro¶

A single Polychro invocation lints every file in the folder:

polychro lint fleet/*.naftiko.yml --ruleset polychro:governance

Polychro runs:

• JSON Schema validation against the Naftiko capability schema
• The bundled polychro:governance ruleset
• Cross-file consistency checks (port collisions, namespace uniqueness, duplicate tool names)

Fix any reported diagnostics before continuing. As your fleet grows, this step is where most issues are caught — long before Ikanos ever runs.

3. Run the fleet — many Ikanos processes, one engine¶

Each capability is a single-process Ikanos server. Launch them in two terminals:

ikanos run fleet/registry.naftiko.yml

ikanos run fleet/crew.naftiko.yml

You now have two MCP servers running on ports 3001 and 3002.

This is the simplest fleet topology: one process per capability, on one host. It scales surprisingly far — many production deployments look exactly like this, just behind a reverse proxy.

4. Discover the fleet from one MCP client¶

Most MCP clients accept multiple server URLs. Configure them with both Ikanos endpoints:

{
  "mcpServers": {
    "registry": { "url": "http://localhost:3001" },
    "crew":     { "url": "http://localhost:3002" }
  }
}

Your agent (or MCP Inspector) will discover the union of all tools from both capabilities — get-ship and list-crew — as if they were one coherent toolset. That's the user's view of a fleet: many small specs, one experience.

5. (Optional) Deploy the same fleet on Kubernetes with Skipper¶

The same two YAML files run unchanged on a cluster with the Skipper operator. Push them as ConfigMaps and reference them from Capability CRDs:

kubectl create configmap registry-spec \
  --from-file=registry.naftiko.yml=fleet/registry.naftiko.yml
kubectl create configmap crew-spec \
  --from-file=crew.naftiko.yml=fleet/crew.naftiko.yml

apiVersion: naftiko.io/v1alpha1
kind: Capability
metadata:
  name: registry
spec:
  source:
    configMapRef:
      name: registry-spec
      key: registry.naftiko.yml
  class: standard
---
apiVersion: naftiko.io/v1alpha1
kind: Capability
metadata:
  name: crew
spec:
  source:
    configMapRef:
      name: crew-spec
      key: crew.naftiko.yml
  class: standard

kubectl apply -f fleet/k8s/
kubectl get capabilities

Skipper reconciles each Capability into an Ikanos workload, complete with autoscaling, resilience defaults from the CapabilityClass, and service endpoints — see Components → Skipper for the full CRD reference and GitOps workflows.

6. (Optional) Govern the fleet in Backstage with Warden¶

Install the Warden plugin in your Backstage app and point it at the same files (or at the Skipper cluster, if you deployed in step 5). Warden auto-discovers every capability, attaches your organization's policy bundle, and exposes a tab on each component page with:

• Schema + ruleset diagnostics from Polychro
• Policy evaluations (allow / deny / dry-run)
• A timeline of decisions and changes

See Components → Warden for the plugin install guide and policy authoring reference.

What you just did¶

You ran your first fleet — the full v1.0 Alpha 3 picture:

• Authored two independent capabilities in Crafter (VS Code), each a self-contained YAML file
• Linted both with Polychro using a shared ruleset (the same one Warden enforces as policy)
• Ran two Ikanos processes side by side — by hand on your laptop, or as Capability CRDs under Skipper on Kubernetes
• Exposed them to a single AI client as a unified toolset
• (Optionally) Surfaced the whole fleet in Backstage through Warden

The same workflow scales naturally:

• Add more *.naftiko.yml files to grow the fleet
• Add type: rest or type: skill exposes to serve non-AI consumers
• Use aggregates to share logic across capabilities (see Tutorial Track 2)
• Multi-region routing, blue/green and canary deployments — see the Skipper roadmap and the Fleet roadmap

How the full Fleet composes around this¶

You can adopt any of these on its own. The Fleet's value is that they share the same artifact — a Naftiko capability YAML file — across all of them.

Next steps¶

• Tutorial — Track 1: Context Engineering — same pattern, drilled into a real maritime use case
• Tutorial — Track 3: Agent Orchestration — multi-source Fleet Manifest with shared consumes
• Components — Skipper — fleet-wide orchestration on Kubernetes
• Components — Warden — capability governance in Backstage
• Fleet → Editions — Community vs Standard vs Enterprise
• Fleet → Releases — what's in v1.0 Alpha 3