Using It

Now the practical question you actually came for: where does COSI earn its keep in your systems? This chapter gives a decision framework, a one-page mapping from domain concepts to COSI primitives, and two greenfield blueprints — a VM control plane and a workflow/orchestration engine — plus the integration patterns for dropping it into an existing service. The next chapter dissects Talos as the canonical real-world application of these patterns.

#Is COSI the right tool?

COSI shines for exactly one shape of problem: declarative reconciliation — "record the desired state, then continuously drive reality toward it." Score your use case:

The litmus test: if you find yourself writing a polling loop that reads some records, computes what should exist, and makes it so — that loop is a COSI controller waiting to be born.

#The domain → COSI mapping

Almost every COSI design is the same translation exercise. Keep this table next to you:

#Blueprint: a VM control plane greenfield

VM lifecycle management is COSI's home turf — it's essentially what Talos does for machines. Here's how you'd model it if starting fresh on COSI. Model the platform as a small graph of resources and controllers:

The resources

• VMConfig — desired VM (CPUs, memory, image, power state). Written by the API/UI. Namespace vms.
• VMStatus — observed VM (actual power state, IP, last error). Written only by VMController.
• NetworkConfig — derived network plumbing for a VM. Owned by NetworkController.
• Host — a hypervisor node with capacity, carrying labels like host=node-7.

The controllers

1. PlacementController (QController over VMConfig) — reads Host capacity, assigns a host by stamping a host= label on a VMPlacement output.
2. NetworkController (qtransform VMConfig → NetworkConfig) — provisions a bridge/IP; uses an input finalizer so a VM can't be destroyed until its network is torn down (the cooperative-deletion pattern from chapter 01).
3. VMController (QController over VMConfig) — the one that touches the hypervisor. Reconcile = "make libvirt match the spec," then write VMStatus. Returns RequeueError(5s) while a VM is mid-boot so it polls until running, without counting as a crash.

The VMController's reconcile, sketched — note how external state (libvirt) is just another thing you converge toward:

func (c *VMController) Reconcile(ctx context.Context, log *zap.Logger,
    r controller.QRuntime, ptr resource.Pointer) error {

    cfg, err := safe.ReaderGet[*VMConfig](ctx, r, ptr)
    if state.IsNotFoundError(err) { return nil }          // gone; nothing to do
    if err != nil { return err }

    if cfg.Metadata().Phase() == resource.PhaseTearingDown {
        if err := c.hypervisor.Destroy(ctx, cfg.Metadata().ID()); err != nil { return err }
        return r.RemoveFinalizer(ctx, cfg.Metadata(), c.Name())   // safe to delete now
    }
    if err := r.AddFinalizer(ctx, cfg.Metadata(), c.Name()); err != nil { return err }

    // converge the hypervisor toward the desired spec
    actual, err := c.hypervisor.Ensure(ctx, toDomainSpec(cfg.TypedSpec()))
    if err != nil { return err }
    if actual.State != "running" {
        // not there yet — poll again soon, without logging a crash
        return controller.NewRequeueInterval(5 * time.Second)
    }

    // publish observed state
    return safe.WriterModify(ctx, r, NewVMStatus(cfg.Metadata().ID()),
        func(s *VMStatus) error { s.TypedSpec().State = actual.State; s.TypedSpec().IP = actual.IP; return nil })
}

What you get for free here: the API only writes VMConfig; the UI watches VMStatus live; deleting a VM safely tears down its network first; thousands of VMs reconcile concurrently with per-VM backoff; and the whole thing runs in one process for dev and as a central-store-plus-agents fleet in prod with no controller changes.

#Blueprint: a workflow / orchestration engine greenfield

For a system whose job is driving multi-step workflows or coordinating state machines, COSI models each workflow run and each step as resources, and uses controllers as the step executors. The reconcile loop is the state machine's transition function.

• Dependencies between steps become strong inputs + finalizers: a downstream StepRun isn't created until its prerequisites' StepResults exist; teardown unwinds in reverse.
• "Fan-out over N items" is a label query: emit N StepRuns labelled batch=abc, let the QController chew through them concurrently, aggregate by querying the label.
• Durability & resume come from the bolt backing store + bookmarks: restart the process and in-flight workflows resume from exactly where the change stream left off.
• Pause/cancel is just Teardown on the Workflow — finalizers ensure running steps stop cleanly before the run is destroyed.

#Integration patterns

Embed in an existing Go service

COSI is a library, not a framework that owns main. Construct the state and runtime alongside your HTTP server, share the state.State handle, and let your handlers do typed writes that controllers pick up:

st := state.WrapCore(namespaced.NewState(inmem.Build))
rt, _ := runtime.NewRuntime(st, logger, options.WithMetrics(true))
registerControllers(rt)            // your transform/qtransform/QControllers
go rt.Run(ctx)

// an HTTP handler just writes a desired-state resource; controllers do the rest
http.HandleFunc("/vms", func(w http.ResponseWriter, req *http.Request) {
    spec := decode(req)
    _ = st.Create(req.Context(), vm.NewVMConfig(spec.ID, spec))
    w.WriteHeader(202) // accepted; reconciliation is async
})

Expose the store as your API

Or skip bespoke handlers entirely: run server.NewState and let clients do typed CRUD + Watch over gRPC, guarded by a state.Filter RBAC rule. Your "API" becomes "the resource model," which is hard to drift out of sync with reality.

#Bridging the outside world

Reconciliation needs to react to things that aren't resources — a hypervisor event, a webhook, a timer, an inotify. Two clean bridges:

#Testing & rollout

• Unit-test controllers against in-memory state — construct inmem state + runtime, register the controller, write inputs, assert outputs. The rtestutils package has AssertResources helpers for exactly this; tests run in milliseconds with no external dependencies.
• Conformance suite — if you write a custom CoreState backend, state/conformance is a ready-made test suite that asserts correct CRUD, watch, bookmark, and finalizer semantics.
• Start as a monolith. Ship the in-process topology first. Only split to central-store-plus-agents when you actually need horizontal scale or process isolation — and when you do, no controller changes.
• Migrate incrementally. You can stand up COSI alongside an existing system: model one slice of your domain as resources, run one controller, and expand. It doesn't demand a rewrite to start paying off.

#Pitfalls & anti-patterns

#Where to go from here