Setup and Operations Guide

Infraveil operates compatible applications on infrastructure you control. A launcher identifies one Linux host and manages its assigned workload agents. Each workload agent can run several manifest services, such as an API and a worker. The hosted control plane coordinates their configuration, releases, received state and supported actions.

Choose the right operating mode. In managed deployment, the local agent prepares the approved package and owns its configured install/build/start and supervision. Existing-service attach observes a running systemd unit, permitted journal output and health without taking over that unit’s deployment or restart policy.

Application execution remains local. Selected operational data reaches the hosted plane, and managed-package uploads may include source; a manifest-only attach does not upload the application implementation. Read the architecture for the complete request, control and data paths.

Open your authenticated workspace and select the Linux server you intend to connect. The current path gives you a curl-based command to paste into that server’s terminal; there is no installer file to move between machines.

1. Get the command for the selected server

Open the server-connection / Trust Console flow and choose Get setup command. Complete the existing action authorization. The private command is tied to the selected workspace and host and expires after five minutes.

2. Copy and run it on that Linux host

Choose Copy command, paste the complete generated command into your normal non-root server terminal, and press Enter. Keep the terminal open and follow its prompts. Setup fetches pinned bytes over HTTPS, checks their SHA-256 before execution, and keeps the interactive terminal attached. It does not pipe a network response directly into a shell.

The command contains private setup authorization: do not post it in a ticket, chat or repository. If it expires, the selected server changes, or verification fails, request a fresh command from the workspace.

3. Review the named releases and complete local setup

Follow the local release-approval and launcher-installation prompts. Your customer signing key stays local. Approval applies to the reviewed release set; it is separate from host enrollment and from an MCP connection’s action policy.

4. Confirm the connection before assigning work

Return to Servers and check the selected host’s live connection and report age. A registered signing key or a copied setup command is not a connected launcher. If approval completed but the host is still offline, continue the server terminal flow and inspect its reported connection error.

This example is an ordinary Node.js HTTP API, not a special Infraveil application. Put these two files at the root of a managed workload’s source. The API answers /health and /api/status; the runtime contract describes how to start and check it.

server.mjs

import http from "node:http";

const port = Number(process.env.PORT || 5050);
http.createServer((request, response) => {
  const path = new URL(request.url, "http://localhost").pathname;
  response.setHeader("Content-Type", "application/json");
  if (path === "/health") {
    response.end(JSON.stringify({ ok: true }));
  } else if (path === "/api/status") {
    response.end(JSON.stringify({ service: "example-api", status: "ready" }));
  } else {
    response.statusCode = 404;
    response.end(JSON.stringify({ error: "Not found" }));
  }
}).listen(port, "127.0.0.1", () => {
  console.log(`Example API listening on ${port}`);
});

infraveil.json

{
  "version": 1,
  "mode": "process",
  "services": [
    {
      "name": "api",
      "runtime": "node",
      "cwd": ".",
      "start": "node server.mjs",
      "port": 5050,
      "health": "/health"
    }
  ],
  "routes": [
    {
      "path": "/*",
      "service": "api"
    }
  ],
  "gateway": {
    "engine": "aiohttp",
    "listen": 18443
  }
}

Choose the connected server and managed-deployment mode, add the files, review the runtime contract, and publish through the workspace’s release-approval flow. This example needs no dependency installation or build step; real applications can declare their supported install/build commands and environment requirements.

The process binds to loopback on port 5050. The declared gateway listens on 18443 and forwards its configured route to that service. Choose ports that are free on your host and configure public ingress deliberately. Keep secrets out of public source and logs.

After deployment, check both the process’s local health and its managed route. With this example’s ports, the read-only checks are:

Example local health and managed-route checks

curl --fail http://127.0.0.1:5050/health
curl --fail http://127.0.0.1:18443/api/status

A healthy launcher connection is only the first layer. Confirm the expected app release, service process, configured health result and report freshness in the workload view.

Review the runtime contract’s local service ports and managed routes before opening traffic. The gateway applies configured policy to traversing requests, then forwards allowed requests to the selected local service. The hosted control plane is not inherently an application-traffic proxy.

Configure policy in the intended scope

Set workspace policy and any workload-specific overrides. Review the effective WAF mode/rules, rate limits, IP/CIDR and geographic controls, method/body limits or honeypot routes you intend to use. Start with a deliberate test against your own non-production application; use Request Trace and pipeline decisions to confirm the configured path and result.

Keep the external boundary explicit

Configure DNS, public TLS, reverse proxy and host firewall as required by your environment. Restrict direct application-port bypass. Managed gateway policy covers configured traffic reaching it, not every packet, upstream volumetric attacks or arbitrary WebSocket frame content. Existing-service attach uses its supported loopback gateway contract.

When an API becomes unhealthy, select its workload and keep its server and release in view. Establish what the runtime actually observed before choosing an action:

1. Check process state, configured application health, reported version and observation age.
2. Open App Logs for application stdout/stderr; filter by service, level, stream or text. Use Runtime Logs for supervisor and control activity.
3. Review Request Trace for received managed-gateway observations and Control Trace for runtime communication. Check incidents and recent release/action history for related changes.
4. Choose a supported action in the explicit target scope. Workload commands include restart, stop, maintain, update and doctor; availability and effect follow the runtime mode.
5. Wait for the returned execution result, then check application health again. A queued or dispatched command is not proof of recovery.

Received observations and logs are bounded. If a host is offline, a report is stale or a queue has dropped data, keep that uncertainty visible rather than inferring the application’s present state.

Use Servers, Workloads and the fleet view to relate applications to hosts, compare connection freshness and inspect reported resources. Capacity diagnostics help explain pressure; they are estimates rather than reserved CPU/RAM or an admission guarantee.

Choose eligible placement using labels, region and workload-count settings. Set host/workload ordering and startup delays where needed. Draining a launcher excludes new assignments; explicit rebalance and supported maintenance actions report blocked or partial results when they cannot complete.

Before moving a workload that has already run, stop it and wait for both its completed stop result and a fresh original-server report confirming it is absent. An offline host does not establish safe ownership transfer. Existing systemd attachments stay tied to their original host, and assignment does not move persistent data.

For a group action, review the actual selected workload IDs/names and intended operation before confirming. Host commands have their own scope; do not treat selecting a server row as authorization to operate every application.

Open MCP Control in the workspace. Name the connection, choose the AI client and its computer’s platform, then choose read-only or control access, action approval policy and connection lifetime.

1. Choose Get setup command and copy its private, one-use command within five minutes.
2. Run it on the computer running the MCP-capable client, not automatically on the production server. Setup requires Python 3.11 or newer and configures the selected supported client; other clients receive bridge configuration instructions.
3. Connect the client and make a real inventory or log read. Copying a command does not prove the client connected; the connection’s last-use time reflects an API request.
4. For control, inspect the exact-target preview and requested change before applying it. The connection’s chosen approval policy determines whether each action also asks for a PIN/authenticator.

Supported tools cover fleet inventory, app logs, policies, pipelines, source/deployment operations, placement and named workload/host commands. Scope, one-use change confirmations, expiry, revocation and normal release gates still apply. MCP is not a general shell and cannot change billing, account authentication or your release-signing key.

Configure a supported event destination in the workspace, enable delivery and select its event subscriptions. Supported delivery paths include Slack, Teams, incident.io, GitHub and configured webhooks. Use an explicitly approved test destination when checking delivery; a saved setting is not a delivered event.

Paused delivery does not accumulate a replay backlog. The OpenTelemetry endpoint reference does not provide an OTLP exporter. Customer exports contain sanitized retained operating information; review redaction and retention boundaries before sharing them. MCP export tools return bounded pages rather than the complete signed download.

For a managed-process failure, inspect health, process state, recent output and release context. Configured restart budgets handle supported local restarts; an exhausted budget stops repeated retries. Local package cache and promoted known-good state support compatible package recovery.

Infraveil agent-runtime updates have separate canary/batch health progression and local candidate/previous slots. A failed candidate can roll back and halt progression. This is different from replacing a customer app package, which stops owned processes and still needs compatible configuration and persistent data.

Restoring code does not restore a database or migrate files across hosts. Maintain your application-data backups and continuity plan. During a control-plane reachability loss, existing local agents can keep running from their available state; fresh remote management and reporting remain limited until reconnection.

If setup authorization expires before enrollment, get a fresh server command. If a machine is compromised, follow your incident process and establish a trusted host before restoring traffic; a runtime restart is not host remediation.

Continue with the complete feature reference, the technical architecture and inspectable runtime source. Check current pricing and capacity units before expanding a workspace.

To understand the workflow without enrolling a server, explore the illustrative demo.