Architecture and transparency

How Infraveil operates your backend.

Infraveil is a backend operations platform built around the runtime on customer-controlled Linux servers. A hosted control plane connects releases, process supervision, health, output, managed traffic and supported operating actions. Local launchers and workload agents carry out that work beside the applications.

This is the complete technical account shared by Architecture and Transparency: what runs where, how requests and commands move, what recovery does, and which responsibilities remain with your team.

On this page

01 / Topology

Hosted coordination. Customer-controlled execution.

The control plane holds workspace configuration, desired releases and received operating state. It presents the dashboard and supported API/MCP operations. The launcher and agents run on your Linux servers; your application processes execute there.

Component topology — location and responsibility
  1. Hosted by Infraveil: workspace control plane
    Operator dashboard or scoped MCP client → workspace settings, release selection and requested actions.
    ↑ Receives selected machine, workload and gateway observations. ↓ Returns desired state and supported commands during authenticated synchronization.
  2. Customer Linux server: launcher host
    One enrolled host identity → launcher → separate agents assigned to this host. The launcher starts and supervises those agent processes.
  3. Customer Linux server: workload agent
    One workload identity → its manifest services → native application processes, configured health and optional local gateway. An application may have an API and a worker in the same workload.

Four identities to keep distinct

Workspace: the customer operating scope. Launcher host: an enrolled server. Workload: an independently identified agent assignment and application package. Manifest service: one configured process or observed external service within that workload.

A host can carry several workloads; an agent can supervise several manifest services. A connected server does not by itself establish that every assigned application is healthy.

Where the hosted plane stops

The hosted plane is not inherently an application-traffic proxy. In the managed request path, traffic reaches the gateway and application on the customer host. Selected observations then travel to the hosted plane.

The supported hosted implementation uses an application process with threaded concurrency and SQLite-backed operating storage. This architecture does not imply an active-active control plane, automatic cross-host failover or unlimited capacity.

02 / Execution ownership

The launcher manages agents. Agents operate workloads.

Launcher responsibilities

The launcher reconciles its assigned workload roster with local agent processes. It identifies each agent with its workspace, launcher host and workload, starts the selected agent runtime and supervises that process. Host connectivity, assignment and runtime-update state are separate from application health.

Linux setup registers the launcher service using privileged installation steps and runs new automatic installations under the chosen non-root identity. Existing privileged installations need their own review; installation does not retroactively change their execution identity.

Managed application responsibilities

The agent verifies and extracts the selected package into a workload workspace, connects declared local persistent paths, prepares the service environment, executes configured install/build steps and starts the declared native processes. It captures application output, observes exits and performs configured local health checks.

This is process supervision under the host's permissions. It is not a VM or container sandbox and does not make an application or dependency safe merely by launching it.

Existing-service observation

Attachment is a different mode. A manifest-only package identifies an existing systemd service and permitted local observations. The agent can observe unit/process state, permitted journal output and configured health without taking over its deployment or restart ownership.

External-service definitions reject install, build and start commands. The existing service manager and your release process retain those responsibilities.

03 / Setup and releases

Preparation, approval, delivery and execution are distinct transitions.

Connect the target server using the documented setup flow. The local Trust Console prepares its environment, establishes the customer release key through a challenge and lets you review the runtime components selected for installation. Enrolling a server and approving a release are separate operations.

Managed release flow — from preparation to observed result
  1. Hosted release preparation
    Application source/package + runtime contract → exact selected release identity and pending approval where the path requires it.
  2. Customer-controlled approval
    Local customer-held Ed25519 key → signature over the exact release hash, under manual, exact-hash allowlist or automatic policy.
  3. Delivery to the customer host
    Encrypted managed package + expected digest and vendor/customer signatures → local verification before extraction and execution. A failed required verification blocks that package from running.
  4. Local execution and reporting
    Agent prepares services → starts processes → observes configured health and output → reports state. Downloaded, dispatched, running and healthy remain different outcomes.

Release-signing modes

Manual: review a pending exact hash before signing. Exact-hash allowlist: hashes you previously approved may be signed without a fresh prompt. Automatic: sign pending hashes while enabled; this removes the per-release human review step.

These modes describe release signing. They do not grant every operating command or MCP action. Protecting the customer key and choosing the intended signing policy remain customer responsibilities.

What a signature establishes

A digest establishes byte equality; vendor signatures identify the expected release signer; a customer signature establishes approval of an exact hash. None establishes harmlessness, successful execution or correct application behavior.

Managed application-package replacement stops the existing owned services before starting the replacement. Do not plan this mechanism as a zero-downtime or blue/green application deployment.

04 / Runtime contracts

Describe an ordinary application outside its business logic.

The root infraveil.json contract describes the services in a workload: runtime and startup commands, working directories, environment, local ports and health, routes, gateway configuration and local persistence. An ordinary Node API and Python worker can share a workload without embedding Infraveil SDK calls in their application logic.

Managed process mode

Use this mode when the agent should prepare and own the application's process lifecycle. The package, start command, dependencies, permissions and health definition must fit the host. Required Node/native executables still need to be available; a declared runtime does not install every language toolchain.

Install/build commands use parsed arguments, rejected shell operators and bounded timeouts. Shell pipelines are not an unrestricted execution interface. A manifest version label is not by itself a promise of schema or migration compatibility.

External process mode

Use attachment to observe a supported existing systemd service while its current owner continues deployment and process management. This can avoid application-source upload, but operational metadata and permitted observations can still leave the host.

The same dashboard vocabulary does not erase the mode boundary: a supervised managed process and an observed external unit have different supported controls.

05 / Application request path

Policy applies where traffic crosses the configured gateway.

The agent's gateway can route an allowed request to a local manifest service. Workspace policy and workload overrides supply supported WAF rules/modes, IP/CIDR and geography controls, rate limits, method/body constraints, honeypots and configured pipeline behavior.

Managed request flow — data stays on the customer request path
  1. Visitor → customer public ingress
    Your DNS/TLS/edge and host exposure determine how traffic reaches the configured gateway.
  2. Gateway on customer host → policy decision
    A rejected or limited request receives the configured response here. It is not forwarded to the application's local route.
  3. Allowed request → local application → gateway → visitor
    The selected route forwards to its configured local service. The application response returns through the gateway.
  4. Selected telemetry → hosted control plane
    Observed gateway decisions, request/control context and bounded reports support investigation. The hosted dashboard is not an obligatory hop for each application response.

Traffic sent directly to an exposed application port can bypass the gateway. Restrict that exposure deliberately. Gateway behavior also varies by integration: managed listeners, the Caddy inspection path and external-service observation have distinct binding and forwarding arrangements.

WebSocket forwarding has size/rate limits, not general frame-content WAF inspection. Host firewalling, public TLS, upstream volumetric DDoS protection and application-level authorization remain separate controls. Request Trace describes observed managed traffic, not every packet or database transaction.

06 / Control path

Requested intent meets reported local state.

The dashboard stores intended configuration and supported actions against explicit host/workload identities. Local components authenticate their synchronization, obtain relevant settings, policy and requested actions, and return heartbeats and observations.

Control flow — direction, authority and interruption
  1. Operator or authorized MCP client → hosted plane
    Choose the target and supported action. Authentication, scope and relevant confirmation/action-factor checks apply.
  2. Hosted desired state → local synchronization
    Launcher assignment and workload configuration/commands travel through their authenticated control paths. The launcher manages agent processes; the agent applies its supported workload behavior.
  3. Local observation → hosted operating views
    Reported package identity, process state, health and timestamps are reconciled with the requested state. A queued request is not proof of execution.
  4. If the hosted plane becomes unreachable
    The launcher keeps local agents running using available local state. Hosted views become stale; new coordination is unavailable until connection returns. Disconnection is not an explicit stop or revocation.

Cached operation gives continuity for the local work already supported and available. It is not full offline administration. A stop or revocation recorded in the hosted plane cannot establish that a disconnected host has received it. After reconnect, inspect reported target state and freshness before treating the requested action as complete.

07 / Operating visibility

Different observations answer different questions.

The runtime relationship connects output and health to the same workload and host that an operating action targets. It does not turn every input into one infallible measurement.

Application output

App Logs show captured service stdout/stderr with service, runtime and stream context. This is the application's own output, distinct from supervisor diagnostics.

Runtime diagnostics

Runtime Logs describe launcher/agent activity such as synchronization, package handling, startup and process supervision. They help establish what the operating layer attempted and observed.

Request and control traces

Request Trace covers observed application gateway traffic. Control Trace covers runtime-control traffic. Neither is a universal distributed tracing system or a raw-payload archive.

Connected operating views

Operations, incidents, service catalog and fleet rollups combine received connectivity, health, runtime errors and supported traffic/security/pipeline events. Shareable status pages derive component state from those observations and have rotatable/revocable links.

Derived status is not independent external uptime probing. Incident grouping does not establish root cause or provide a complete human on-call/paging system. Stale, missing and dropped observations must remain visible as uncertainty.

08 / Fleet operation

The same model operates one workload or a selected fleet.

Each launcher gives the control plane an independently identified host and assigned workloads. Inventory, placement, host maintenance, ordering, capacity diagnostics and scoped commands build on those relationships.

Assignment and placement

Placement considers eligible hosts, labels, preferred region, workload-count limits, draining/stopping state, connectivity and external-service host affinity. Explicit rebalance and drain operations can have blocked or partial outcomes.

Moving a previously runnable workload requires its completed stop receipt and a fresh report from the original online host confirming that the workload is absent. Offline ownership cannot be transferred safely. An assignment updates desired ownership and the per-host roster; it does not migrate data or reserve CPU/RAM. Automatic cross-host recovery remains unavailable.

Ordering, maintenance and action scope

Configure supported placement, startup ordering and delays. Keep a host out of new assignments while planning maintenance. Select one workload or an explicit group for supported commands such as restart, stop, maintain, update and doctor. Host actions have their own supported vocabulary.

Inspect eligible targets, requested change and each reported result. Selecting rows, changing assignment and requesting a process command are distinct operations; a partial batch must not appear as universal success.

Capacity in context

Host diagnostics and reported safe/burst capacity estimates help compare pressure and candidate placement. Workload allowances and count limits are not physical resource reservations or an admission-control guarantee. Validate memory, disk and dependencies for the actual application.

09 / Health and recovery

Several recovery mechanisms, with different objects.

A useful health result combines current package identity, process/service observations and configured endpoint checks, with gateway liveness where required. Host connection alone is insufficient; an application without a meaningful health definition cannot acquire one from a green dashboard badge.

Process restart

Configured health failures can recycle a managed process; exits then pass through the supervisor. Managed process exits consume a configured restart budget and apply delay. Exhausting the budget stops repeated retries and surfaces the failure. It does not repair an application bug or authorize a database restore.

Known-good application package

The local encrypted, versioned, signature-checked package cache retains promoted known-good state. Candidate stability handling can promote the candidate, restore an available known-good package or stop. Recovery depends on available valid state and compatible application/persistent-data behavior.

Agent-runtime rollout

Infraveil agent-runtime updates have candidate/previous slots, health windows and canary/batch progression. A rolled-back candidate halts progression for review. This updates the operating agent, not a customer's application through blue/green release traffic.

Failure transitions — local operating behavior
  1. Managed process exits → budget and delay → restart or stop
    The configured retry budget bounds repeated attempts.
  2. Application candidate → stability observation → promote, restore known-good or stop
    Package recovery needs a valid compatible local recovery candidate.
  3. Agent-runtime candidate → health window → promote or previous-runtime rollback
    A blocked candidate pauses broader rollout.
  4. Control plane unreachable → retain running local agents → reconcile after reconnect
    This preserves available local operation; it does not create a second host or migrate persistent data.

Process restart, package restoration and agent-runtime rollback are real operating controls. Database recovery, replicated storage, automatic cross-host failover and business continuity are separate systems and responsibilities. Test data migrations and recovery procedures before relying on code rollback.

10 / Storage and reporting

Persistent paths, recovery cache and telemetry queues serve different jobs.

Application persistence

Declared local persistent paths reconnect selected files to the workload workspace across package replacement. They remain on the customer infrastructure. This is not replicated storage, a database-consistent backup or automatic data migration between hosts.

Package cache

Verified local cache entries support package availability and known-good recovery. The cache is finite and needs disk headroom; missing, corrupt or incompatible entries can prevent recovery. A cached application package does not include an independent recovery copy of every mutable application file.

Queued reports and retention

Local reporting queues and hosted history are bounded. Connection loss, pressure and retention/queue limits can delay or drop observations. Inspect backlog, drop counters, freshness and the available interval rather than assuming lossless capture or complete historical coverage.

The hosted plane persists selected account/configuration/operating records. Review applicable retention, redaction, residency, backup and deletion arrangements for the current offering; local execution does not mean no information leaves the host.

11 / MCP and integrations

An AI client uses supported operations, within the same product boundaries.

Connect a compatible MCP client through the documented local bridge to the hosted HTTPS MCP service using a workspace-scoped, expiring connection. Named tools cover inventory, logs, traffic, policy/pipelines, deployment/source operations, placement, scoped process commands, integrations and sanitized exports.

Preview and apply

Supported changes use a preview/confirmation path tied to arguments, target scope, connection, current revision, impact and expiry. The connection policy chooses confirm-mode action authentication or explicitly authorized automatic actions; both retain scoped preview/confirmation and expiry. The adapter invokes the normal product handlers and middleware rather than creating a separate unrestricted shell.

A client does not receive the customer release-signing key through this interface. A prompt saying a human approved something is not itself a cryptographic attestation of that person's intent. Release approval and action confirmation remain separate controls.

What integrations do

Supported Slack, Teams, incident.io, GitHub and webhook event delivery requires enabled delivery and subscriptions. Paused delivery does not build a paused backlog. Pipeline analysis hooks are bounded configured hooks; hook responses are not arbitrary code or remote policy authority.

The reviewed product does not provide a working OpenTelemetry exporter or a built-in autonomous AI repair service. MCP gives an authorized client access to named product operations; it does not expand the runtime's authority.

12 / Data and keys

Source custody depends on the operating mode.

Managed source/package path

Managed deployment can store uploaded application source and packages on the hosted side before verified delivery. The running processes and declared local persistent files reside on customer infrastructure. “No SDK in application logic” does not mean “Infraveil never receives source.”

Manifest-only attachment

Attachment can avoid uploading the existing application's implementation. It still sends the contract and permitted operational observations needed for the selected visibility. Review logs and reporting settings for secrets and sensitive application data.

Operational data and release keys

The hosted plane receives selected configuration, machine identity, heartbeat, health, log and managed-traffic/control records. The customer-held release private key stays under the customer's control in the local approval flow; hosted verification data and release signatures serve a different purpose.

Protect local credentials and release keys, review automatic approval deliberately and plan offboarding/revocation. A record of revocation cannot make a disconnected host immediately observe it.

13 / Responsibilities and validation

Inspect the mechanism. Validate the behavior that matters.

The launcher and agent source installed on your servers is inspectable through the runtime-source material and local installation. That visibility does not make the private hosted implementation public, establish independent certification or replace a deployment-specific review.

Customer-owned responsibilities

Your team retains infrastructure accounts, OS hardening, application correctness and authorization, dependencies, secrets, persistent-data protection, public exposure/TLS, database backups and business continuity. Decide who may request powerful actions and how the release key is protected.

Confirm workload compatibility, required host executables, health semantics, available storage and recovery candidates. Fine-grained enterprise RBAC, SAML/SCIM, multiparty approval, active-active management and full air-gap operation are not implied by this architecture.

A useful evaluation sequence

  1. Connect a supported test host and identify its launcher, workload and manifest services.
  2. Exercise the intended release-signing mode and distinguish pending approval from execution.
  3. Inspect app output, runtime diagnostics, configured health and gateway decisions for the same workload.
  4. Try one supported scoped command, then compare requested and reported results.
  5. Exercise restart exhaustion, a compatible known-good package and agent-runtime rollback in an authorized test environment.
  6. Interrupt control-plane connectivity and observe local continuity, stale hosted views and reconnection.
  7. Test persistent-data backup/restore separately and review queued/dropped observations.

These are evaluation steps, not a claim that a particular customer's environment has passed them. Implementation descriptions establish mechanisms; scenario receipts establish behavior only within their tested scope.