Services reference

The Omnitron daemon exposes the RPC services below. Some are conditional on enabled modules or daemon configuration. All share the same auth model (see Daemon / Auth flow) and address the same socket / TCP / HTTP planes.

This page is the canonical inventory: service name, registered Netron service id, purpose, and key methods.

Re-check this page against the source with node scripts/check-services-reference.mjs <path-to-omni> — it reads @Service/@Public out of src/**/*.rpc-service.ts and diffs them against the index table below.

Quick index

Cluster participation is exposed on controllers, workers and standalone daemons:

Plus the core supervisor:

The daemon exposes its role-protected metrics facade and imports the Titan health service:

OmnitronMetrics requires authorization for every method. Use omnitron doctor to check which diagnostic methods a particular daemon exposes to an unauthenticated connection. It reports observed exposure as auth.anonymous-surface.

Naming convention

Most service ids use the Omnitron<Subsystem> PascalCase shape with no version suffix. Health@1.0.0 is the exception, and it is not going to be renamed: the id is Netron's own versioned form, declared by @omnitron-dev/titan-health for every application that imports the module, so it is not omnitron's to change. Query it with the suffix included.

What availableServices lists

When a query_interface fails, the daemon logs the ids it does have. That list is a superset of this page: managed applications register their own services into the same Netron registry. An application can register TransformWorker alongside the daemon's own services. A name in that list is not evidence of a daemon service, and its absence from this page is not evidence of a gap.

Query services via Netron's standard interface mechanism:

import type { IProjectRpcService } from '@omnitron-dev/omnitron/dto/services';

const peer = await netron.connect('unix://~/.omnitron/daemon.sock');
const project = await peer.queryInterface<IProjectRpcService>('OmnitronProject');
const projects = await project.listProjects();

The CLI and webapp do exactly this under the hood. Typed client interfaces are published from the @omnitron-dev/omnitron/dto/services subpath (IDaemonService, IProjectRpcService, IOmnitronAuthService, IOmnitronLogsService, IInfraService); other services can be queried untyped via queryInterface(serviceId).

Per-service summary

Each subsection lists the methods you can call directly. For full parameter and return types, refer to src/services/<name>.rpc-service.ts and the src/shared/dto/ types it imports.

OmnitronAlerts — alert.rpc-service.ts

Alert rules + delivery for operator-defined thresholds (metric exceeds value, app crashed N times, etc.).

OmnitronAuth — auth.rpc-service.ts

User authentication, session management, JWT issuance.

signIn, validateToken, validateSession, refreshSession, and signOut are all allowAnonymous (the session id / token is the credential). getActiveSessions and changePassword are @Public({ auth: true }) — any authenticated caller, operating on its own identity (not admin-gated).

OmnitronBackups — backup.rpc-service.ts

Database backup, restore, scheduling.

Driven by omnitron backup commands. Reads (listBackups, getSchedule, listSchedules, getBackupStatus) gate on viewer; every mutation requires admin.

OmnitronDeploy — deploy.rpc-service.ts

Compatibility access to legacy per-app operation records.

Historical strategy labels are retained as recorded requests, not evidence of an implemented rollout.

OmnitronDiscovery — discovery.rpc-service.ts

Discovery of Omnitron-managed targets across Docker and SSH.

Used by omnitron discover.

OmnitronEvents — event-broadcaster.rpc-service.ts

Cross-process event bus over Netron. Webapp subscribes here for live UI updates.

All three methods admit viewers. Publication is internal to the daemon.

OmnitronFleet — fleet.rpc-service.ts

Cross-node fleet operations: register nodes, drain, set roles.

Reads (listNodes, getNode, getSummary) gate on viewer; mutations (registerNode, removeNode, setRole, drainNode) on operator. The scheduler records local liveness against its own registration.

OmnitronHealth — health-check.rpc-service.ts

Active health probes — runs HTTP / TCP / DB checks on demand.

OmnitronInfra — infrastructure.rpc-service.ts

Provisioned infrastructure inventory, container control and host-owned ingress.

Reads gate on viewer; startContainer, stopContainer and removeContainer on operator. Ingress configuration, takeover rollback and recovery require admin or trusted service_role; check/apply/remove/owner restore use control-plane roles. Read the generated API signature and the method’s declared gate before composing an operational workflow.

OmnitronKubernetes — kubernetes.rpc-service.ts

Kubernetes integration.

Driven by omnitron k8s .... Every method requires admin.

OmnitronLogs — log-collector.rpc-service.ts

Log query + streaming.

omnitron logs calls queryLogs or streamLogs. Note the full-text filter is search, not grep, and streamLogs is a poll — it returns a page ending at now, it does not hold a subscription open.

OmnitronNodes — node-manager.rpc-service.ts

Node inventory, health history, bundle activation, managed rollout and recovery include 38 public methods.

Includes the uptime-bar machinery the webapp uses to draw green/yellow/red availability bars.

OmnitronPipelines — pipeline.rpc-service.ts

Xec and shell automation, shared by Console, CLI and local MCP. All methods require admin; a human session is revalidated at the service boundary. Mutations must record an audit intent before taking effect.

See Xec automation for execution limits, revision review, cancellation and failure recovery. A kind: "release" step carries a PipelineReleaseTarget: registered project, stack, app, producer artifact identity and package-relative compiled entry. The verified resident owner supplies the executable. Per-attempt PipelineReleaseExecution records keep observed installation and owner evidence separate from the saved definition. See pinned release steps. A child process is not a sandbox for untrusted agent code.

OmnitronProject — project.rpc-service.ts

refreshTopologyMetadata({ project, stack? }) is admin-only: it captures bootstrap declarations in bounded child processes and persists the last successful snapshot. It returns refreshed and per-application failures, retaining previous metadata on failure. Viewer getTopology and getTopologyWorkspace report declaration source, capture time and coverage warnings without importing bootstrap code. See declaration coverage.

inspectInstalledArtifacts({ project, stack }) is an explicit viewer operation. It compares retained archive hashes and byte counts with the release catalog, reports modified installed entry points and framework build metadata, and never creates launch receipts. Its node counterpart, OmnitronDaemon.inspectInstalledArtifacts({ names }), accepts canonical owner inventory keys and admits human readers plus authenticated cluster service identities. Both are read-only, bounded, and absent from status polling. See release evidence.

diagnoseStack({ project, stack }) is a viewer operation. It returns timestamped prerequisite checks, planned changes and explicit unverified coverage without provisioning or importing application bootstraps. Imported configuration names resolve to the same runtime scope as Start; the report retains the public project and stack names. Concurrent readers share an in-flight inspection. See readiness before start.

The project and stack registry exposes release checks, account operations, infrastructure ownership and per-node lifecycle receipts.

updateProject({ name, path }) changes the registered location while preserving the project name, registration history, enabled-stack settings and workspace namespace. The directory basename is not a rename request. Stop running/starting stacks before moving a project to another release directory. Configuration is reloaded from the new path on the next start. A rejected path leaves the registration unchanged. Use an immutable release directory for updates; a mutable current symlink can otherwise make process definitions and installed package identities disagree.

Roles: all reads (listProjects, getProject, scanRequirements, getProjectApps, getTopology, getTopologyInventory, getTopologyWorkspace, listStacks, getStack, getStackStatus, diagnoseStack, reviewStackStop) gate on viewer; startStack, stopStack and resumeInstalledStack on operator; project CRUD (addProject, updateProject, removeProject) and stack CRUD (createStack, deleteStack) on admin. Target mutations (saveTopologyDraft, planTopology, applyTopologyPlan) also require admin. They persist target intent, not executable deployment configuration. See the workspace contract.

reviewStackStop({ project, stack, keepInfrastructure? }) and stopStack({ project, stack, review?, keepInfrastructure? }) share the same strict boolean mode. Omitted or false removes the stack's containers after applications stop; true retains them and their ownership. Strings, numbers and null are invalid. The mode is part of the review digest, node plan and signed cluster permit; switching it invalidates the review. A confirmed retention receipt records keepInfrastructure: true, keptContainers and an empty removedContainers list. Public stopOperation.keepInfrastructure carries the selected mode across page and backend reloads. Retention preserves release selection but disables automatic application startup, just like a full stop. It does not add an administrator-only execution path or grant a viewer permission to mutate.

OmnitronSecrets — secrets.rpc-service.ts

Encrypted secret CRUD.

Always gated by admin role.

OmnitronSync — sync.rpc-service.ts

Cross-daemon state synchronisation (service-to-service, used in cluster mode).

drainBuffer and readUnverifiedMetrics accept administrators and authenticated machines. Only service_role can acknowledge a drained batch or settle historical evidence. Administrators inspect and repair records through OmnitronNodes.reconcileNodeMetrics on the controller. Inspection is the default. Pass restore: true for repair. The controller binds each batch to its authenticated node connection. All Console read roles and the authenticated machine can call getSyncStatus.

Production replication uses the master's authenticated mesh connection to pull drainBuffer batches from each slave. The master ingests a batch before calling ackDrained; pending entries remain available for retry until acknowledged. Rejected entries remain pending. Permanently discarded entries are logged as errors and acknowledged explicitly.

Inspect pending entries, the last acknowledgement, node reachability and mesh logs when diagnosing replication. An unavailable reading is unknown, not an empty backlog.

OmnitronSystemInfo — system-info.rpc-service.ts

Host inventory.

The webapp uses this for the host-info card.

OmnitronTelemetry — telemetry.rpc-service.ts

getRelayStats() returns relay statistics to authorized readers and machine peers on the master. Workers use the authenticated OmnitronSync protocol for log and metric replication. A controller acknowledges committed data. See replication evidence.

OmnitronCluster — cluster/cluster.rpc-service.ts

Controllers, workers and standalone daemons report their participation. An enrolled controller additionally reports its PostgreSQL lease.

All reads require viewer/operator/admin or a control-plane service identity. Step-down requires an administrator. The former anonymous vote and heartbeat methods have been removed. A lease observation is not a fence for remote effects; see cluster coordination.

OmnitronTraces — trace-collector.rpc-service.ts

Distributed trace ingestion + query.

Auth role recap

Methods on the same service can vary in role:

• OmnitronAuth.signIn is anonymous; OmnitronAuth.getActiveSessions requires any authenticated caller (@Public({ auth: true })), operating on the caller's own identity — not admin-gated.

• OmnitronProject.listProjects is viewer; OmnitronProject.startStack is operator; OmnitronProject.deleteStack is admin.

Querying a service from your code

import { Netron } from '@omnitron-dev/titan/netron';
import { createNullLogger } from '@omnitron-dev/titan/module/logger';
import type {
  IProjectRpcService,
  IDaemonService,
} from '@omnitron-dev/omnitron/dto/services';

// `Netron` takes a logger — pass your application's, or
// `createNullLogger()` to discard Netron's own output. `create` also
// starts it, which `connect` requires.
const netron = await Netron.create(createNullLogger());
const peer   = await netron.connect('unix://~/.omnitron/daemon.sock');

const project = await peer.queryInterface<IProjectRpcService>('OmnitronProject');
const projects = await project.listProjects();

// Services without a published interface are queried untyped:
const deploy = await peer.queryInterface('OmnitronDeploy');
const legacyOperations = await deploy.getHistory({ app: 'sample/test/api', limit: 20 });

The same code works against a remote daemon by swapping the URL (tcp://server:9700).

Anti-patterns

• Calling mutating methods over the public TCP plane without RBAC. Operator-level methods change app state — expose only behind proper auth.

• Long-running calls on RPC. Some methods (deploy, backup restore) can run for minutes — prefer fire-and-forget patterns (start the run; poll status) over a long-held RPC.

• Sending unauthenticated telemetry to the daemon. Managed workers retain replication entries in their outbox. Monitor delivery through the registered node and its persistence receipts.

• Treating OmnitronSync as a public API. It's daemon-to- daemon plumbing. The shape may change between releases without notice.

See also

• Daemon — the OmnitronDaemon service + auth model

• Architecture — where these services live

• CLI — most commands map directly to one method here

• Console — webapp uses the same services

Release and audit services

OmnitronRelease provides preflight, list, get, getLog, builds, getBuild, build, stopBuild, prune, attest, attestOnNode and deployments. Build execution and artifact state are separate from deployment history. See Releases and verification for the workflow.

OmnitronAudit exposes available and list, both gated to administrators. Check availability before interpreting an empty result as proof that no operation took place. The audit trail records who requested control-plane changes and their outcomes.

Console administration and SSH

OmnitronAccess: describe, listUsers, createUser, setRole, revokeSessions. See Console access for transactions, audit and revocation.

OmnitronTerminal: capabilities, inspectHost, trustHost, open, list, read, write, resize, close. See SSH workspace for ownership, host verification and bounded binary I/O. Both services are registered on a master; they are not application user-management APIs.

File workspace services

OmnitronFiles is the master-only administrator API: roots, archiveFormats, list, stat, readText, readChunk, saveText, mkdir, rename, trash, trashList, restore, beginUpload, uploadChunk, uploadStatus, finishUpload, acknowledgeUpload, abortUpload, copy, transfers, controlTransfer. Each call revalidates human authority; mutations and content reads require audit intent.

OmnitronFileNode.invoke runs on each node and accepts the v1 typed file protocol only for authenticated control-plane service peers. It implements OS access, private staging and durable write receipts. It is not a browser or application RPC proxy. See File workspace.

The six recipient lifecycle operations accept only an authenticated machine credential. stopStack and resumeInstalledStack coordinate them on behalf of an operator. Nodes verify ownership and admission before applying an effect. Their durable receipts are available to the controller after a transport interruption.