Dubnium Technical Overview

Dubnium is a reproducible, observable, governed engineering environment for developer workstations, smaller client environments, build and compute nodes, and AI-assisted automation.

Within Micrantha, Dubnium serves as the canary implementation for the wider development and VM ecosystem: it integrates and exercises NixOS, VM, runtime, and automation patterns before broader reuse.

This technical overview explains the system through responsibilities, state models, invariants, observable behavior, and published interoperability contracts. It is intentionally more detailed than the landing page while stopping before deployment-sensitive implementation and operator material.

What Dubnium is trying to preserve

The project is built around four system qualities:

• reproducibility — environments can be rebuilt, replaced, and reviewed from declared inputs;
• observability — intended state and observed runtime state remain distinct and explainable from bounded evidence;
• security — connectivity, identity, capabilities, and automated effects remain explicit rather than ambient;
• development acceleration — project environments, builds, automation, and AI support reduce setup and recovery cost without making the workstation fragile.

Dubnium is local-first, not local-only. A useful endpoint should remain inspectable and recoverable without depending on a central control plane while still being able to consume remote services through explicit contracts and policy boundaries.

Deployment is compositional

Dubnium is not limited to one workstation shape. The same architectural contracts can support smaller client environments, richer interactive workstations, build or compute nodes, remote managed development environments, and stronger security or administrative environments. Each deployment enables only the capabilities it needs.

AI is one capability of the environment, not the authority for the environment. Deterministic configuration, runtime observation, policy, durable state, and recovery remain useful without a model.

Start with the system flow

• How Dubnium Works gives the end-to-end mental model from declared intent through runtime observation and governed effects.
• Operator Journey shows how the public operator surfaces fit together without exposing deployment-specific procedures.
• Self-Hosted CI Runner Controller explains bounded admission, short-lived workers, canonical status, and reconciliation.

Then inspect the implemented surfaces:

• Components describes the major platform pieces, their maturity, state ownership, and intentional boundaries.
• Operator Tooling explains why dubctl, modectl, and configctl remain separate surfaces.
• Runtime Operating Modes describes desktop, media, and compute posture and the guarded reconciliation model.
• Writable User Configuration explains how legitimate mutable preferences coexist with Nix-store-backed managed configuration.

Then continue into the broader design:

• Vision and Deployment Model describes the long-term product shape.
• Conceptual Architecture describes responsibility and source-of-truth boundaries.
• Reproducible Engineering covers replacement, project environments, mutable-state classification, and supply-chain trust.
• Observability and Evidence separates intended state, runtime facts, durable state, and derived understanding.
• AI and Automation explains how model-assisted work fits without becoming ambient authority.
• Governance and Safety describes bounded effects and trust boundaries.
• Contracts and Conformance describes the independently inspectable interoperability surface.
• Status and Direction distinguishes implemented, experimental, and directional work.
• Community and Contributions points to the open source and contribution surface.

Disclosure boundary

The useful rule for this overview is:

Publish what the system promises and what an integrator or operator can observe; keep private how a particular deployment enforces it.

This overview may therefore publish stable component names, maturity, operator-tool responsibilities, runtime-mode semantics, configuration ownership layers, state-machine invariants, conceptual control flow, and published contracts.

It deliberately omits machine identities, exact topology, ports/endpoints, service-unit wiring, credentials, hardware/resource assignments, exact policy thresholds, trusted identities, provider-selection or model-routing heuristics, privileged recovery procedures, private prompts/data, and real operational evidence.

The published Community repository is independently useful for contracts, conformance, references, and documentation. This technical overview is not a sanitized mirror of private operator documentation.

How Dubnium Works

Dubnium is easiest to understand as a set of boundaries between declared intent, runtime state, observation, and governed effects.

The project does not treat configuration, automation, or AI output as equivalent kinds of truth. Each answers a different question and carries different authority.

End-to-end mental model

flowchart LR
    A[Versioned intent] --> B[Reproducible evaluation]
    B --> C[Installed capability]
    C --> D[Selected runtime posture]
    D --> E[Observed runtime state]
    E --> F[Operator or automation request]
    F --> G[Policy and capability boundary]
    G --> H[Bounded effect]
    H --> I[Durable state and evidence]
    I --> E

The important property is not the exact implementation behind each box. It is that crossing from one responsibility to another is explicit and inspectable.

1. Declared intent describes what may exist

NixOS, Home Manager, project environments, and reviewed configuration describe the reproducible inputs of an endpoint. This layer answers questions such as:

• which capabilities are present;
• which services or tools may be available;
• which user-environment defaults are managed;
• which resource and security boundaries are declared.

Declared intent does not prove that a service is running, a workload is healthy, or a privileged effect is authorized at this moment.

2. Runtime posture selects from already-declared capability

An endpoint may need different operating postures over time. Interactive work, media-priority work, and compute-heavy work can place different demands on the same machine.

A runtime-mode transition selects among capabilities that configuration already permits. It does not install missing capability or create new authority. The transition is only considered successful after the resulting state is observed.

See Runtime Operating Modes.

3. Observation reports what is actually happening

Dubnium keeps intended state and observed state separate. Operator tooling can report service state, runner capacity, runtime posture, configuration ownership, and other bounded facts without pretending that configuration alone proves runtime success.

This separation also prevents telemetry from becoming policy. A log, metric, dashboard, or previous successful run may be useful evidence, but it does not authorize a future effect.

See Observability and Evidence.

4. Requests cross explicit authority boundaries

A human, workflow, scheduler, or model may request an action. A request is not permission.

Consequential effects are expected to cross a boundary that can bind identity, capability, policy, lifecycle state, and evidence. A stronger model or richer context can improve a proposal, but it does not widen the caller’s effect authority.

This same rule applies to retrieved context: similarity or relevance can help reasoning, but retrieval rank does not establish approval, currentness, or operational truth.

See Governance and Safety and AI and Automation.

5. Effects produce state and evidence

A successful operation should leave enough bounded evidence to answer what happened without indiscriminately capturing private source, prompts, credentials, or unrelated activity.

Durable workflow state, domain state, and runtime observation remain distinct. That allows retries, reconciliation, replacement, and audit without reconstructing the world from model context or logs.

Invariants that hold across the system

Several rules repeat throughout Dubnium:

Local-first, not isolated

Dubnium favors local execution and local inspectability where they are sufficient. Remote services, stronger models, shared compute, or central coordination may still be used through explicit contracts.

The important architectural property is that adding a remote dependency does not erase the endpoint’s ability to explain its own declared state, current posture, observed behavior, or authority boundaries.

What this overview intentionally does not publish

This chapter describes responsibility and behavior, not deployment-sensitive implementation. It intentionally omits exact topology, service-unit wiring, trusted identities, credentials, policy thresholds, routing heuristics, privileged procedures, and production operational evidence.

The public contract is the separation between responsibilities, not the private mechanics used by one deployment to enforce them.

Components

Dubnium is composed from bounded components rather than one always-on control plane. The important question for each component is not only what it does, but what authority and state it deliberately does not own.

Maturity labels describe the current implementation surface, not a compatibility guarantee.

Declarative platform

Purpose. Define what an endpoint is allowed and able to become from reviewed inputs. NixOS and Home Manager provide the rebuildable system and portable-user layers, while project environments can add project-specific dependencies without turning them into permanent workstation state.

Boundary. Declarative configuration is intended state, not proof of current runtime state. It does not replace runtime observation, durable application state, or explicit recovery of mutable data.

State model. Versioned configuration describes desired system and user state. A rebuild materializes that intent; runtime observation determines what is actually active afterward.

dubctl

Purpose. Provide a coherent operator surface over Dubnium host workflows instead of requiring users to know every underlying Nix or system-service detail.

Boundary. dubctl is not a second policy engine. Reviewed configuration, registries, profiles, and capability policy remain authoritative. It does not own writable Home configuration, service-specific application data, or secret storage.

State model. Read-only commands inspect the endpoint. Mutating commands change only bounded selections or perform an explicit apply of declared configuration.

See Operator Tooling for the published responsibility model.

Runner Controller

Purpose. Turn configured self-hosted CI eligibility into admitted short-lived workers only when work exists and local policy permits it. The controller owns admission, transient worker lifecycle, bounded status, and cleanup/reconciliation rather than requiring one permanently running job worker for every configured repository.

Boundary. Workflow labels, matrix values, and other job-controlled input do not grant repository, profile, credential, or resource authority. Workers receive only the authority required for one admitted job and do not inherit the controller’s long-lived administration credentials.

State model. Configuration eligibility, administrative permission, admission, worker execution, completion, and reconciliation are separate states. Configured capacity therefore does not imply that idle job workers must remain active.

See Operator Tooling for the public dubctl runners surface.

modectl

Purpose. Select the runtime posture appropriate to the work happening now without installing new capabilities or rewriting the declarative system definition.

Boundary. A mode request cannot grant new authority, bypass capability policy, or silently turn an unavailable capability into an installed one.

State model. Desired mode, observed mode, transition guards, reconciliation, and post-transition observation are separate steps. Success requires the observed result to match the requested posture.

See Runtime Operating Modes.

configctl

Purpose. Give applications and users an explicit writable configuration boundary on top of reproducible Nix-managed defaults.

Boundary. configctl does not turn mutable user configuration into privileged host policy. Secrets, service authority, system security controls, and host-level declarations remain separate concerns.

State model. Managed, local, custom, and adopted layers make ownership and promotion explicit instead of relying on undocumented edits to generated files.

See Writable User Configuration.

Capability Gateway

Purpose. Separate a request for a consequential capability from authorization and effect execution. The contract makes request identity, state, policy decisions, bounded constraints, and resulting evidence explicit.

Boundary. Possessing a transport path or producing a valid request does not itself grant authority. The Gateway is not a general service bus and does not make model output, prior success, or network reachability equivalent to permission.

Maturity. Experimental. The published v1 contract and conformance assets establish a portable boundary without claiming that every production effect provider is openly implemented.

• Capability Gateway v1
• Conformance assets

Supervisor / LLM Gateway

Purpose. Expose a bounded interface for model and specialist execution with explicit capability negotiation, normalized errors, sanitized metadata, and execution lineage. The control-plane direction is local-first, with stronger remote or frontier execution treated as an explicit bounded escalation rather than an ambient fallback.

Boundary. Model or specialist output is proposal material, not ambient authority to mutate the host, deploy software, write durable memory, train or promote models, or bypass governance. Escalating model capability does not escalate effect authority.

Maturity. Experimental v1alpha.

• Supervisor / LLM Gateway v1alpha

Memory Service

Purpose. Provide an interoperability boundary for scoped reusable context and memory used by model-assisted and automated workflows.

Boundary. Memory is durable application data with scope and governance; it is not authorization, runtime truth, or an implicit channel for privileged effects. Where semantic retrieval is enabled, embeddings and indexes remain derived retrieval state and ranked results remain evidence rather than authority or proof of currentness. Repository, document, and live-runtime sources remain separate source-of-truth boundaries rather than being silently federated through memory.

Maturity. Experimental v1alpha.

• Memory Service v1alpha

Scheduler

Purpose. Represent scheduled and deferred automation through explicit requests and state rather than hidden background behavior.

Boundary. Scheduling decides when bounded work should be attempted. It does not automatically grant the scheduled task additional authority.

Maturity. Experimental v1alpha.

• Scheduler v1alpha

Model lifecycle boundary

Model training is an experimental governed capability rather than an extension of inference authority. The durable lifecycle keeps distinct authorities for training execution, resource enforcement, evaluation, promotion, catalog binding, and runtime activation.

reviewed training intent
-> governed training execution
-> candidate artifact
-> independent evaluation
-> promotion decision
-> approved model binding
-> inference runtime

Training success does not imply evaluation success, promotion authority, or runtime activation. This separation allows trainer implementations to evolve without making a model or specialist capable of approving its own replacement.

How the pieces fit

flowchart LR
    C[Declarative configuration] --> H[Engineering endpoint]
    D[dubctl] --> H
    M[modectl] --> H
    U[configctl] --> H
    H --> O[Runtime observation]
    H --> R[Runner control and transient CI workers]
    H --> A[AI and automation]
    A --> G[Governed capability boundary]
    A --> S[Memory and scheduling services]

The diagram shows responsibility, not production topology. Published documentation intentionally stops before machine identities, exact service wiring, credentials, resource assignments, policy thresholds, provider-selection heuristics, and privileged operating procedures.

Operator Journey

This chapter shows how the public Dubnium responsibilities fit together from an operator’s point of view. It is an illustrative workflow, not a production runbook: exact deployment values, privileged procedures, and private enforcement details remain outside the published surface.

Start by discovering the installed surface

Dubnium favors discoverable commands and semantic help over memorized implementation details. The operator should be able to identify what is installed before changing anything.

Representative read-only entry points include:

dubctl commands
dubctl service list
modectl status
configctl status
dubctl runners status

Read-only status, list, show, and diagnostic commands should remain side-effect free. Machine-readable forms are useful for automation when a stable JSON contract is available.

1. Inspect declared and observed state separately

The first question is not “what should be running?” but “what does this endpoint declare, and what is actually running now?”

An operator may inspect:

• the installed capability surface;
• current runtime posture;
• service and workload state;
• writable configuration ownership and drift;
• self-hosted CI eligibility and active worker state.

This prevents a common failure mode in managed environments: assuming that a successful build or declaration proves the runtime converged.

2. Change only the responsibility that actually needs changing

Dubnium intentionally keeps several operator surfaces separate.

The separation matters because each action has a different source of truth and authority boundary.

For example, selecting a runtime mode does not install a capability that was not declared. Likewise, changing a writable preference does not become a way to redefine privileged host policy.

3. Observe convergence after a change

A requested transition is only one piece of evidence. After a bounded change, the operator checks the resulting state rather than assuming success.

A generic control loop looks like:

inspect
  -> request bounded change
  -> reconcile
  -> observe resulting state
  -> report success, degraded state, or failure

This pattern appears across runtime modes, writable configuration, services, and CI worker lifecycle.

4. Treat automation as another caller

Scheduled jobs, workflows, and model-assisted tools follow the same authority rules as an interactive operator.

Automation may:

• read bounded status;
• propose intent;
• request a capability already available to it;
• consume structured results and evidence.

Automation may not infer additional authority from previous success, retrieved context, or the fact that a stronger model generated the request.

5. Inspect self-hosted CI without inferring from processes

For self-hosted CI, the controller owns the canonical lifecycle view. An operator can inspect it directly:

dubctl runners status
dubctl runners status --json

The important public semantics are eligibility, bounded capacity, occupancy, worker lifecycle, and reconciliation health. An empty worker list can be a healthy idle state when no work is owned; it is not evidence that capacity disappeared.

See Self-Hosted CI Runner Controller.

6. Use structured state for tooling

Operator-facing output can remain readable for humans while exposing versioned structured forms for scripts and dashboards. Structured consumers should use the same validated state contract rather than reparsing human-oriented output or reconstructing state from logs.

That gives the operator and automation the same answer to questions such as:

• what is eligible;
• what is active;
• what is owned;
• what is degraded;
• what requires reconciliation.

7. Escalate ambiguity without widening authority

When a task is ambiguous or difficult, Dubnium may route reasoning to a stronger model or require human review. That changes who helps interpret the request, not what the request is allowed to do.

The final effect still crosses the same policy and capability boundary.

What good operation looks like

A healthy operator workflow has a few recognizable properties:

• inspection precedes mutation;
• commands explain their responsibility and effect;
• requested state and observed state are both visible;
• failures remain explicit rather than being papered over by retries;
• structured evidence is bounded and reusable;
• no convenience surface silently becomes a new source of authority.

The objective is not to hide system complexity. It is to make the important complexity visible at the correct boundary while keeping implementation-specific machinery replaceable.

Operator Tooling

Dubnium separates host control, runtime posture, and writable user configuration instead of putting all three responsibilities behind one privileged command.

dubctl

dubctl is the host-operator façade for Dubnium. It provides one discoverable surface for system workflows that would otherwise require operators to know several lower-level implementation tools.

Its public responsibility model is deliberately narrow:

• inspect — report bounded host, workload, configuration, and diagnostic state;
• select — change only options or capabilities that are already registered by reviewed configuration;
• apply — evaluate and explicitly apply declared configuration;
• develop — enter or operate on declared development environments and inputs;
• discover — expose the installed command/capability surface without making documentation a static command inventory.

Representative command families include dubctl service, dubctl capability, dubctl runners, dubctl apply, dubctl inputs, and dubctl commands. The exact installed command tree may evolve as bounded components are added or removed.

Authority boundary

dubctl does not own source-controlled host policy. A CLI selection does not become an unrestricted configuration language, and an apply operation does not make the CLI the source of truth for the resulting system.

dubctl also does not own:

• Home/user configuration layering managed through configctl;
• runtime-mode state managed through modectl;
• secrets or credentials;
• service-specific workflows, indexes, databases, or other application data;
• policy decisions for governed effects.

The design goal is a coherent operator experience without collapsing independent trust boundaries into one command.

Runner operations

dubctl runners exposes bounded observation and control for self-hosted CI capacity. Its read-only status and watch surfaces report controller-owned state such as effective eligibility, capacity and occupancy, worker lifecycle, and reconciliation health instead of asking operators to infer runner state from labels or process lists.

Runner admission remains policy-bound. Repository identity, capability profile, credentials, and resource envelope come from reviewed configuration; workflow-controlled input cannot select a stronger profile or another repository’s authority. Admitted jobs execute in short-lived workers and do not inherit the controller’s long-lived credentials.

Administrative runner controls affect whether already-declared capacity may accept work. They do not edit the underlying registry, mint new capability, or turn a workflow request into authorization.

modectl

modectl manages the current runtime posture. It records requested mode, observes current state, applies transition guards, reconciles bounded runtime changes, and verifies the result.

This is intentionally different from dubctl apply: declarative configuration determines what the endpoint can run; modectl determines which already-declared posture should be active now.

See Runtime Operating Modes.

configctl

configctl handles the part of the user environment that legitimately needs to remain writable even when managed defaults come from immutable Nix-store-backed configuration.

It reports ownership and drift, establishes writable layers, supports reviewable promotion of useful changes, and handles bounded first-run state where declaring a file alone is insufficient.

See Writable User Configuration.

Why the tools stay separate

The separation gives each question a clear authority:

What should this endpoint be able to run?  -> declarative configuration
What host change should be applied?        -> dubctl + declarative apply
What CI capacity is eligible or active?    -> dubctl runners + controller observation
What runtime posture should be active now? -> modectl
Who owns this user preference?             -> configctl
What is actually active?                   -> runtime observation

Keeping these questions distinct makes state easier to explain and reduces the chance that a convenience CLI silently becomes a second configuration or authorization system.

Self-Hosted CI Runner Controller

Dubnium treats self-hosted CI capacity as a governed runtime resource rather than a collection of permanently waiting runner processes.

The public design goal is simple: keep controller authority persistent, but make ordinary job execution short-lived and bounded.

Responsibility split

flowchart LR
    A[Repository demand] --> B[Runner Controller]
    B --> C{Admission permitted?}
    C -- no --> D[Remain waiting or denied]
    C -- yes --> E[Short-lived worker]
    E --> F[One job]
    F --> G[Cleanup and reconciliation]
    G --> B

The controller owns lifecycle decisions and status. The worker owns one admitted job and then disappears.

Why not keep ordinary runners permanently idle?

A permanently waiting worker carries more ambient state than Dubnium needs for ordinary CI demand. Short-lived workers reduce the amount of time job execution environments exist and make ownership easier to reason about.

This does not make untrusted CI safe by itself. It provides a clearer lifecycle boundary that can be combined with reviewed repository policy, bounded resources, credential separation, filesystem isolation, and destination-side controls.

Admission happens before worker creation

A workflow asking for capacity does not get to choose arbitrary authority.

Before ordinary work is admitted, the controller evaluates already-reviewed eligibility and current host state. Publicly relevant inputs include:

• whether the repository is eligible for local execution;
• whether the requested class of work is already declared;
• whether bounded capacity is available;
• whether administrative policy currently permits work;
• whether existing worker ownership can be explained.

Only admitted work receives a worker.

The exact registry, thresholds, credentials, scheduling algorithm, and host-specific resource values are deployment details and are intentionally not published here.

The worker is intentionally disposable

An admitted worker has a narrow lifecycle:

created
  -> accepts one admitted assignment
  -> executes inside bounded job isolation
  -> reports terminal outcome
  -> cleanup
  -> gone

Ordinary workers do not become a durable source of configuration or identity. A future job is admitted again from current policy and current host state.

Controller credentials do not become job credentials

The controller may need authority to coordinate the runner lifecycle. That authority is not meant to become ambient authority inside the job environment.

This separation is important because the code under test should not inherit control-plane credentials merely because it runs on the same physical endpoint.

The public invariant is credential separation; exact credential material and transport remain private.

Capacity is a state model, not a process count

Operators should not infer capacity from the number of visible worker processes.

A useful conceptual model is:

configured eligibility
  + administrative permission
  + bounded host capacity
  - currently owned work
  = currently available capacity

The implementation may represent additional states, but this distinction explains an important behavior: zero active workers can be a healthy idle condition.

Likewise, configured capacity does not imply that idle workers must already exist.

Canonical observation

The controller exposes bounded status through the operator surface:

dubctl runners status
dubctl runners status --json

The status model is intended to answer questions such as:

• is self-hosted CI administratively permitted;
• what capacity is currently eligible;
• how much admitted work is owned;
• which workers are active;
• whether controller observation is healthy;
• whether reconciliation is required.

Scripts and dashboards should consume the structured state rather than derive lifecycle truth from process lists or logs.

Reconciliation is explicit

CI state can become stale or partially completed when a process crashes, a job disappears, or cleanup is interrupted. The controller therefore treats reconciliation as a first-class responsibility.

The goal is not to preserve a worker at all costs. The goal is to restore an explainable relationship between admitted work, owned resources, and observed runtime state.

Ambiguous ownership should fail safely rather than guessing that an unknown worker can be reused or deleted.

Queue priority does not create authority

When multiple already-authorized jobs are waiting for bounded local capacity, ordering may decide which job receives the next available slot.

Priority changes order, not eligibility. A lower-level workflow request cannot use queue manipulation to select another repository’s profile, stronger credentials, or additional capability.

Trust boundaries

The runner design preserves several separations:

What is deliberately omitted

This overview does not publish exact repository mappings, runner labels, service wiring, credential flows, filesystem paths, resource thresholds, scheduling heuristics, cleanup implementation, or production incident procedures.

Those details are not required to understand the public contract: reviewed eligibility becomes bounded short-lived execution through an observable controller-owned lifecycle.

Runtime Operating Modes

A reproducible endpoint does not need every declared capability active at the same time. Dubnium uses runtime operating modes to select which already-declared workload posture should be active now without treating an imperative mode change as a replacement for declarative configuration.

Modes versus capabilities

The distinction is intentional:

declarative configuration -> what the endpoint is allowed and able to run
runtime mode              -> which declared posture should be active now
observed state             -> what is actually active after reconciliation

A mode switch does not install new capabilities. A declared capability does not imply that its workload is currently active.

Current mode model

studio-local remains the current runtime identifier for media mode. Some implementation identifiers may retain older studio/audio terminology for compatibility; that does not narrow the intended media-mode semantics.

modectl responsibility

modectl is the operator surface for these transitions. Its observable behavior is a reconciliation loop rather than a collection of arbitrary service toggles:

1. record the desired mode;
2. observe the current runtime posture;
3. validate that the requested transition is allowed;
4. run guards that protect active work and resource safety;
5. reconcile bounded runtime changes;
6. observe again;
7. record success, blockage, or failure from the observed result.

The key invariant is that attempting a transition is not evidence that the transition succeeded. Success requires post-transition observation consistent with the requested mode.

Transition guards

Disruptive transitions are guarded by categories of runtime evidence such as:

• active workload state;
• CPU/load and memory headroom;
• graphical/display resource ownership;
• protected media activity, including latency-sensitive audio where applicable;
• whether a service can be safely drained before its resources are reassigned.

Exact guard names, thresholds, service wiring, hardware assignments, and machine-specific exceptions are deployment policy and are intentionally outside this technical overview.

Authority boundary

A mode request can change runtime posture only within capabilities already declared for the endpoint. It cannot:

• install a missing capability;
• widen authorization;
• bypass a governed-effect decision;
• rewrite the NixOS definition;
• redefine resource or security policy;
• turn a failed observation into success.

This keeps modectl useful for resource-sensitive work while preserving the separation between declarative intent, runtime control, and observed state.

Writable User Configuration

NixOS and Home Manager make managed configuration reproducible, and many managed files are materialized from immutable Nix-store content. Those files should be regenerated rather than edited in place.

That does not mean the user environment is globally read-only.

Dubnium keeps an explicit writable boundary for application preferences, machine-specific choices, and first-run state that legitimately changes outside a system rebuild. configctl makes ownership and drift visible so mutable user state does not become undocumented configuration history.

Layer model

The names describe ownership, not trust level. A writable fragment does not automatically become managed merely because it works locally.

configctl responsibility

configctl provides a generic reconciliation surface around those layers. Its useful operator vocabulary includes:

This is an ownership workflow, not an attempt to make every application configuration format identical.

Promotion rather than mutation

A portable preference can begin as a writable local/custom change. configctl can identify that the change is outside the managed layer and help move it into review. Once the reviewed declarative configuration represents the same intent, a rebuild can make it part of the managed default and the independent custom fragment no longer needs to carry authority.

That gives Dubnium both properties at once:

• managed defaults remain reproducible and reviewable;
• legitimate application and user preferences still have an explicit writable home.

First-run mutable state

Some tools need initialization rather than a static configuration file. configctl supports explicit first-run contracts so these changes are inspectable and risk-gated rather than hidden in shell startup, installer side effects, or ad-hoc bootstrap scripts.

The technical overview intentionally describes the contract shape, not tool-specific mutable paths or operational procedures.

Security boundary

Writable configuration is not an escape hatch from host policy. configctl does not grant authority over:

• secrets or credentials;
• privileged system state;
• service authorization;
• host security policy;
• deployment topology;
• governed effects.

Those concerns remain with their own declarative, runtime, secret-management, and governance boundaries.

Principles

Dubnium is guided by system-level principles that apply across workstation, client, compute, automation, and AI-assisted deployments.

Declarative intent before accumulated setup

Long-lived configuration should be declared, reviewable, and reproducible. A working machine should not depend on undocumented installation history.

Desired state is not observed state

Configuration says what should be true. Runtime observation says what is true now. A transition, deployment, or workflow is not successful merely because it was requested.

Local-first, not local-only

Endpoints should remain useful, diagnosable, and recoverable with local resources. Remote services may extend the system through explicit compatibility, privacy, security, and availability boundaries.

Capabilities instead of ambient authority

A caller should request a bounded capability rather than inherit broad host, network, data, device, credential, or tool access.

Reachability is not authorization

Network location, VPN membership, endpoint health, and authenticated identity are useful security inputs. None of them alone grants authority for an unrelated or privileged effect.

Durable domain state before log reconstruction

Workflows, approvals, automated operations, and other stateful domains should own their exact records. Logs and events provide evidence; they should not be forced to become a substitute database.

Structured evidence before generated narrative

Reports and summaries should be derived from bounded structured evidence. AI may help synthesize that evidence, but it should not decide what may be collected, retained, or exported.

Reproducibility is not supply-chain trust

Pinned inputs make behavior easier to reproduce. Trust still requires explicit provenance, verification, update, and dependency policy appropriate to the deployment.

Bounded resource use

Interactive development, background automation, builds, and AI workloads should coexist intentionally. Resource contention, disk growth, and runaway work are operational concerns to design for rather than surprises to tolerate.

Personal observability is not organizational surveillance

A system can help its operator understand work without covert productivity monitoring. Personal reports and journals require a separate ownership and sharing boundary from organizational endpoint posture.

Contracts before coupling

Public and private consumers should depend on versioned contracts, canonical behavior, and conformance evidence rather than production implementation details.

Safe public disclosure

Public artifacts should be independently useful while revealing no private topology, credentials, privileged implementation, policy internals, operator data, or private provenance. Publication is an irreversible security and intellectual-property decision.

Vision and Deployment Model

Dubnium’s long-term direction is a family of reproducible engineering environments built from shared contracts rather than one machine that must perform every role.

Product shape

Dubnium
├── Client environment / VM
│   └── small, replaceable development and access environment
├── Workstation
│   └── interactive environment with richer local device or compute access
├── Build / compute node
│   └── bounded non-interactive build, CI, cache, or compute capacity
├── Remote managed environment
│   └── sensitive work kept on infrastructure with an appropriate trust boundary
└── Security / administrative environment
    └── stronger isolation and access controls selected by threat model

These are deployment compositions, not identities or permission levels. A deployment should enable only the services and capabilities justified by its use case.

Why a smaller client environment matters

A small managed VM can make project setup, replacement, credential cleanup, and offboarding easier without forcing the user’s entire physical machine into one configuration model. It can also give teams a consistent development substrate while leaving heavyweight build, AI, or infrastructure workloads elsewhere.

A VM on an unmanaged physical host is not a confidentiality boundary against that host. If the host itself is outside the trust model, sensitive source, data, or credentials may require a managed endpoint or remote execution environment instead of stronger claims about the guest.

Identity, posture, and authority stay separate

The architecture intentionally distinguishes:

network reachable
identity authenticated
endpoint posture known
operation authorized

Each can inform policy, but one should not silently stand in for another.

Local operation remains important

Central inventory, observability, policy distribution, or remote services may be useful for larger deployments. They should extend local behavior rather than becoming the only way to inspect, diagnose, or recover an endpoint.

Direction, not a support claim

This page describes a public architectural direction. It does not claim that every deployment form, fleet function, identity system, or remote environment is currently implemented or generally available.

Conceptual Architecture

Dubnium treats an engineering endpoint as a governed operating environment rather than a collection of unrelated tools.

Conceptual layers

flowchart TB
    U[People and developer tools] --> E[Engineering endpoint]
    C[Reproducible configuration] --> E
    E --> G[Governed capability boundary]
    G --> D[Development and operating-system capabilities]
    G --> A[AI and automation capabilities]
    D --> S[Durable state and bounded evidence]
    A --> S
    E --> O[Runtime observation]
    O --> S

The diagram communicates responsibilities, not production topology.

• Reproducible configuration declares intended system, user, and project inputs.
• Engineering endpoint composes only the capabilities required by its deployment form.
• Governed capability boundary separates a request from authorization and effect execution.
• Development and operating-system capabilities perform bounded engineering work.
• AI and automation capabilities may assist reasoning and workflows without inheriting unrestricted authority.
• Runtime observation reports what is actually happening rather than assuming intended state succeeded.
• Durable state and bounded evidence preserve exact domain state and reviewable outcomes.

Runtime posture and writable state

Two responsibilities deliberately sit beside declarative configuration rather than inside it:

• Runtime Operating Modes choose which already-declared workload posture should be active now and require post-transition observation before declaring success.
• Writable User Configuration gives legitimate mutable preferences and first-run state an explicit ownership boundary instead of encouraging edits to generated configuration.

Neither responsibility changes the authority model: a runtime mode cannot install or authorize a missing capability, and writable user configuration cannot redefine privileged host policy.

Source-of-truth hierarchy

Different questions have different authorities:

declarative intent       -> versioned configuration
observed runtime state   -> operating-system/runtime observation
durable domain state     -> workflow and operation stores
event evidence           -> bounded logs and events
derived understanding    -> reports, dashboards, and journals

A dashboard does not become runtime truth. A log does not become authorization. A previous successful operation does not grant authority for a future one.

Endpoint and central responsibilities

A Dubnium endpoint should remain locally inspectable. Optional central services may aggregate posture, provide shared resources, or coordinate policy, but central state should carry freshness and uncertainty rather than overwrite contradictory endpoint facts.

Technical-overview boundary

The published architecture describes responsibilities, invariants, and observable state relationships. It intentionally omits machine identities, networks, ports/endpoints, exact service placement and wiring, provider selection, resource assignments, data schemas that are not published contracts, policy thresholds, credentials, and privileged recovery procedures.

Those are deployment and implementation concerns rather than requirements for understanding the architecture.

Reproducible Engineering

Dubnium aims to make engineering environments replaceable without turning every project dependency into permanent workstation state.

Layered ownership

A useful mental model is:

platform configuration
  -> operating system, security baseline, resource policy

portable user environment
  -> shell, editor, terminal, user-facing development preferences

project environment
  -> project-specific SDKs, compilers, dependencies, tools, and workflow requirements

trusted acceleration
  -> caches, builders, prebuilt artifacts, and remote capacity

The layers can use different tools, but their ownership should remain explicit.

Immutable managed configuration is not a read-only user environment

NixOS and Home Manager deliberately make managed configuration reproducible, and many managed files are materialized from immutable Nix-store content. That does not mean legitimate application preferences and user state must be forced through a system rebuild.

Dubnium treats writable user configuration as a separate ownership problem. Writable User Configuration describes the managed, local, custom, and adopted layers and the role of configctl in making drift and promotion visible.

The important reproducibility invariant is that writable state remains classified: a local preference does not silently become the managed source of truth, and a generated managed file is not edited in place merely because it is convenient.

Desired developer path

A project should increasingly be able to approach:

clone
-> enter declared environment
-> build
-> test
-> run

without depending on undocumented machine history.

Reproducible does not mean trusted

A perfectly reproducible malicious dependency is still malicious. Supply-chain policy may therefore include:

• pinned source and dependency identities;
• reviewed trust roots for caches or artifacts;
• signatures, provenance, or attestations where they add value;
• controlled update and rollback behavior;
• visible failure when required trust evidence is unavailable.

The exact mechanisms can vary by deployment and project.

Mutable state is classified, not ignored

Not everything should live in declarative configuration. Dubnium uses a conceptual state classification:

A replaceable environment should be reconstructed from declared inputs plus explicitly restored state rather than depend on an opaque machine image.

Performance is part of developer experience

Reproducibility should not require every task to rebuild the world. Shared immutable inputs, bounded caches, remote build capacity, and resource-aware scheduling can accelerate work as long as their trust and ownership boundaries remain explicit.

Observability and Evidence

Dubnium treats observability as part of the workstation contract: an environment should be able to explain what it expected, what it observed, what failed, and what evidence supports that conclusion.

Host observability

Local host observability should answer questions such as:

• what should be active;
• what is actually active;
• what failed, restarted, or became degraded;
• whether resource or storage pressure is affecting work;
• whether the endpoint’s security and exposure posture matches expectations;
• what changed recently enough to investigate.

The specific implementation may use operating-system service state, structured logs, runtime metrics, and local diagnostic tools. The public contract is the ability to inspect locally rather than dependence on a central dashboard.

Organizational observability

A managed environment may publish a bounded projection of endpoint posture to an organization. Useful categories can include configuration identity, update state, critical service health, security posture, resource pressure, and record freshness.

This is not a requirement to stream every workstation log. Central collection should be purpose-limited, freshness-qualified, and additive to local diagnosis.

Personal observability

The same evidence model can support private daily reports, journals, and retrospectives for the operator.

Personal observability is a separate plane from organizational telemetry. A useful default avoids covert collection of keystrokes, clipboard contents, screenshots, complete shell history, arbitrary browser activity, message bodies, or arbitrary file contents.

Even metadata can be sensitive. Repository names, work times, project activity, and failure patterns need explicit purpose, visibility, retention, and sharing rules.

Evidence before narrative

A reporting pipeline should prefer:

authoritative domain state
+ bounded runtime evidence
-> deterministic structured summary
-> optional narrative synthesis
-> explicit publication or sharing

An AI-generated summary should not hide missing evidence or invent success. The structured report should remain useful without a model.

Logs are evidence, not universal state

Logs and journals are valuable for runtime events and diagnosis. Workflows, approvals, deployments, and other stateful domains should retain their own durable records rather than require later reconstruction from log text.

AI and Automation

Dubnium supports AI-assisted development and automation without making a model the operating-system authority.

AI is optional capability

A Dubnium environment may use local models, remote models, or no model at all. Deterministic configuration, security boundaries, runtime observation, workflow state, and recovery should continue to work independently.

Model selection and provider choice are implementation concerns behind a stable caller-facing boundary. Changing a model must not silently widen access to data, tools, credentials, networks, or privileged effects.

Local-first model routing

Local execution is the default direction where it is sufficient for the task. A request may use a stronger remote or frontier model only through an explicit bounded escalation path that preserves policy, sanitization, lineage, provider constraints, and traceability.

Escalation changes available model capability. It does not transfer effect authority, grant additional tools or credentials, or convert unresolved policy into permission. A policy ambiguity or required human decision remains unresolved rather than being “solved” merely by selecting a stronger model.

The exact production triggers, provider configuration, and routing heuristics remain private implementation concerns.

Reasoning is not an effect

A useful separation is:

reasoning proposes intent
-> deterministic validation
-> policy / approval boundary
-> bounded capability
-> effect execution
-> durable outcome and evidence

Model output can propose an action. It cannot mint its own identity, approve itself, or turn previous success into future authority.

Retrieval is evidence, not authority

Where semantic memory retrieval is enabled, canonical memory records remain the authoritative stored state while embeddings and indexes are derived, rebuildable retrieval state. Similarity rank does not establish approval, permission, currentness, or operational truth.

The Memory Service owns retrieval over its own governed memory corpus; it does not become a generic search federation layer. Document or project search, repository state, and live runtime observation remain separate sources that the caller or Supervisor may consult according to the task and source-of-truth boundary.

Stateful automation owns state

Scheduled work, durable workflows, memory/context systems, and long-running operations should expose explicit lifecycle and state rather than exist only inside model context.

That makes retries, recovery, auditing, and replacement possible without asking a model to reconstruct what probably happened.

Training has separate authorities

Model training follows the same governed-effect model as other consequential automation. A backend-neutral training request can describe intent, but execution authority, resource enforcement, evaluation, promotion, catalog binding, and runtime activation remain separate responsibilities.

A successful training operation yields a candidate artifact. It does not by itself prove evaluation success, authorize promotion, select a production model, or activate that model for inference. Models and specialists cannot authorize their own training or promotion merely because they generated the proposal or candidate.

Resource-aware operation

AI inference, builds, tests, model training, background automation, and interactive work can all compete for CPU, memory, storage, network, and accelerators. Dubnium treats resource placement and isolation as operating concerns rather than model-routing side effects.

Evidence remains bounded

Automation should produce enough structured evidence to explain outcomes while avoiding indiscriminate capture of source, prompts, credentials, private messages, training data, or unrelated user activity.

Public interoperability

Public Dubnium contracts may describe model-independent request surfaces, capability envelopes, scheduling or state semantics, and conformance behavior when those interfaces are useful to external consumers. Private routing heuristics, production prompts, trusted identities, provider configuration, training implementation, and stored user data remain outside the public boundary.

Governance and Safety

Dubnium treats automation as a request for bounded capability, not as ambient permission to act.

Trust model

The conceptual flow is:

intent
-> contract validation
-> authenticated actor and context
-> policy / approval decision
-> bounded capability
-> effect
-> durable outcome and evidence

Each stage has a distinct responsibility:

• Intent states the requested outcome without granting authority.
• Contract validation rejects malformed, ambiguous, or incompatible requests.
• Identity and context bind the request to trusted transport or enrollment facts rather than model assertions.
• Policy / approval decision determines whether the exact request is allowed, denied, constrained, or requires approval.
• Bounded capability receives only the scope needed for the authorized operation.
• Effect execution performs the domain operation without widening the decision.
• Outcome and evidence record enough durable state to inspect what happened.

Security properties

Public Dubnium work emphasizes:

• deny-by-default capability access;
• least privilege and explicit effect boundaries;
• deterministic validation and canonicalization;
• clear separation between policy authority and effect execution;
• no automatic widening when a dependency is unavailable;
• synthetic adversarial fixtures and implementation-neutral conformance;
• reviewable compatibility and security changes;
• no-effect reference implementations where real effects would create unnecessary risk.

Identity and posture are policy inputs

Network reachability, authenticated identity, endpoint posture, and attestation can constrain a decision. They are not universal permission for privileged effects. Unsupported or stale posture should remain visible rather than being treated as success.

Public versus private governance

Public contracts may define request envelopes, decision references, authorized manifests, errors, evidence shapes, and compatibility rules.

Production policy, approval rules, thresholds, trusted identities, prompts, fallback behavior, provider wiring, audit records, and recovery procedures remain private. Publishing a contract does not publish the implementation or policy behind it.

Relationship to Anthesis

Where Dubnium integrates with Anthesis, Anthesis remains authoritative for governance decision and approval semantics. Dubnium transports and enforces bounded decisions through its capability boundary; it does not redefine Anthesis policy authority in the public Dubnium contracts.

Contracts and Conformance

Dubnium publishes contracts when interoperability is useful and disclosure does not require publishing the production implementation behind the boundary.

Suitable published material

• normative protocol and schema definitions;
• canonicalization and compatibility rules;
• request, response, error, state, and evidence envelopes;
• synthetic positive, negative, and adversarial fixtures;
• implementation-neutral conformance tests;
• thin clients, validators, and authoring helpers;
• minimal no-effect reference implementations;
• release checksums, software bills of materials, and published attestations.

Published contracts may eventually cover additional capability, scheduling, state, or model-independent interfaces when there is a stable interoperability need. Publication follows usefulness and disclosure review rather than mirroring internal APIs by default.

Material that remains private

• production planning, prompts, routing, retries, and fallbacks;
• production policy, approvals, thresholds, and trusted identities;
• private data ranking, retention, consolidation, retrieval, and stored content;
• privileged providers, deployment workers, and recovery behavior;
• host and fleet topology, credentials, operator configuration, and runbooks;
• real logs, incidents, traces, evidence, and operational measurements.

Compatibility model

Published contracts are versioned and classified by stability. Consumers should pin immutable releases, verify digests and provenance, and exercise conformance tests at their integration boundary.

A contract describes observable behavior. It does not promise a particular internal architecture, service layout, implementation language, deployment model, or provider.

Disclosure model

A contract crosses the publication boundary only when its external value exceeds the cost and risk of maintaining it openly. Private implementation details are not documentation debt merely because a published contract exists.

Source of truth

Specifications, schemas, conformance assets, reference implementations, release metadata, and community documentation are maintained in the Dubnium Community repository.

Status and Direction

This page describes the published product surface and directional architecture only. It is not an internal delivery schedule and does not imply publication of private implementation.

The repository remains in incubation, and no protected contract-v* release has yet been accepted as a consumer identity.

Current work

• maintaining the Community repository as the authoritative website, documentation, contract, and release surface;
• stabilizing experimental capability-boundary contracts and canonical behavior;
• hardening short-lived self-hosted CI admission, controller-owned status, and deterministic reconciliation boundaries;
• maturing local-first AI control boundaries, including bounded model escalation, scoped retrieval semantics, and governed model lifecycle transitions;
• expanding synthetic conformance, adversarial fixtures, validators, and no-effect references;
• maintaining an explicit source allowlist and guarded private-to-published documentation flow;
• improving architecture, governance, compatibility, security, and release guidance.

Current architectural direction

The published design treats Dubnium as a reproducible, observable, governed engineering environment rather than only a single workstation plus AI runtime.

Directional themes include:

• smaller replaceable client environments alongside richer workstations and build/compute nodes;
• project-local reproducible development environments and explicit supply-chain trust;
• self-hosted CI through reviewed eligibility, bounded admission, short-lived workers, and controller-owned observation rather than permanently active job workers;
• local-first observability with bounded organizational posture when appropriate;
• private operator-owned status reporting and journaling kept distinct from organizational telemetry;
• local-first AI routing where stronger model selection changes reasoning capability but never widens effect authority;
• scoped memory retrieval where canonical records remain distinct from derived ranking and index state;
• model lifecycle boundaries that keep training, evaluation, promotion, and runtime activation as separate authorities;
• AI and automation behind explicit state, resource, and governed-effect boundaries;
• recovery and replacement based on declared configuration plus classified mutable state.

These themes are architecture, not a claim that a production fleet service, every model lifecycle transition, or every deployment form is currently available.

Next published work

• keep generated publication and destination validation aligned with the explicit source allowlist;
• improve adopter documentation and contract integration examples;
• consume published contract releases immutably from downstream implementations;
• mature release checksums, software bills of materials, attestations, and deprecation guidance;
• document threat models and compatibility guarantees at stable interoperability boundaries;
• publish additional contracts only after their semantics are useful outside private implementation and have survived enough operational use to justify a compatibility commitment.

Later, evidence permitting

• additional adapters or language bindings justified by real consumers;
• thin validation and conformance commands;
• additional API families where an interoperability need stabilizes;
• fleet or endpoint contracts only when they are useful without exposing private topology, identity, or policy.

Explicitly outside this roadmap

The published roadmap does not imply disclosure of production prompts, routing heuristics, policy internals, trusted identities, private data, privileged provider implementation, host or fleet configuration, operational evidence, incidents, credentials, or private planning.

Community and Contributions

The Dubnium Community repository is the published source of truth for:

• the project website and generated Technical Overview;
• specifications, schemas, and API descriptions;
• conformance tests and synthetic fixtures;
• no-effect references, examples, and published tooling;
• compatibility, security, governance, contribution, and release policies;
• the bounded roadmap.

Contribution boundary

Contributions should target published contracts, conformance, examples, conceptual documentation, release integrity, and independently useful tooling. A contribution must not depend on private source, private services, private registries, credentials, host configuration, operator data, or production policy.

Private-to-public imports receive additional review because publication is irreversible. Review covers ownership, licensing, patents, trade secrets, third-party provenance, secrets, operational disclosure, synthetic test data, generated metadata, and Git history.

Documentation ownership

The Technical Overview is curated rather than mirrored. Every source file that enters the generated artifact must be explicitly allowlisted, and every Markdown page must be part of the reviewed navigation. Unlinked source files are not a supported disclosure mechanism.

Generated Technical Overview content is proposed into site/docs/ through a guarded publication workflow and validated again in the Community repository before deployment. The hand-maintained landing page and generated Technical Overview are separate artifacts with the same publication boundary but different detail levels.

Reporting security issues

Use the private reporting process documented in the Community repository. Do not open a public issue containing a vulnerability, secret, sensitive topology, exploit evidence, or private implementation detail.