Skip to main content
Every supported VM that AcornOps observes runs the unprivileged AgentV. The agent opens an outbound WebSocket, reports bounded host snapshots, and executes strict VM tools. Production onboarding defaults to read-only. You can instead permit policy-governed restarts for an exact list of systemd services. The supported first-release host baseline is Ubuntu 24.04 LTS with systemd, Bash, curl, tar, sha256sum, and Node.js 22 or newer at /usr/bin/node. You need root or sudo access and outbound HTTPS access to both the configured AgentV release host and the AcornOps API. Other Linux distributions, including Rocky Linux, are not qualified for this release.

​
Register a VM

  1. Open a workspace in the management console.
  2. Go to Virtual Machines.
  3. Enter a VM name.
  4. Keep Read-only, or select Read-write and add each exact restartable .service unit.
  5. Copy the single generated command before its 15-minute countdown expires.
  6. Run the command on the intended Linux host.
  7. Confirm the VM shows as connected.
The registration response includes { virtualMachine, installInstructions }. The VM record contains the normalized host access mode, restart-service scope, and run permission mode. installInstructions.command contains a target-bound, one-use enrollment token; it does not contain the durable AgentV credential or a user-editable privilege policy. The root installer exchanges the token only after host and release validation, installs the enrollment-bound policy, stores the resulting credential in /etc/acornops/agentv.env, and commits it only after the candidate AgentV authenticates successfully. Treat the command as sensitive until the token is exchanged or expires. The copied command can remain in shell history, but it contains only the 15-minute, single-use enrollment token—not the durable AgentV credential—and becomes unusable immediately after a successful exchange. Clear the history entry if your host policy requires it. If the token expires, use Generate new command. Issuing a new command invalidates older outstanding enrollment commands for that VM. If you close onboarding before the VM connects, open that VM’s settings and use Finish AgentV setup to generate a fresh initial-enrollment command. You do not need to delete and register the VM again.

​
Agent behavior

The AgentV authenticates with the protected local credential and connects to:
Replace example.com with your deployment domain. The public demo agent route is wss://api.demo.acornops.dev/api/v1/agent/connect. Do not claim another distribution as supported until the same bootstrap and live-systemd canary passes there. For the initial bootstrap, the host’s curl and Node.js runtime must already trust the platform certificate. Install an organization-private root in the host trust store before running the generated command. After installation, ACORNOPS_AGENT_ADDITIONAL_CA_BUNDLE_FILE may point to an additional root-managed PEM bundle for the AgentV runtime; repair and replacement preserve that setting. Never disable certificate or hostname verification.

​
Repair and credential replacement

Use Upgrade or repair AgentV for a healthy installation that needs the pinned release reapplied or upgraded. Its command contains no enrollment token and reuses the root-owned local credential. It fails before modification if the local target, platform URL, environment ownership, or credential is missing or mismatched. Use Replace AgentV credential after suspected exposure or when rebuilding the VM. The replacement command has a fresh one-use token and preserves the VM’s registered access policy. The current credential and connection remain valid while the candidate is checked; the installer promotes the replacement only after provisional authentication. A failed cutover restores the previous release, environment, helper policy, socket state, credential, and service connection. The original installation command can also be rerun on the same correctly configured VM: its consumed token is ignored and the operation behaves like a repair.

​
Update host capabilities

You can change approval behavior directly in VM Settings without running a host command. Changing the exact restart-service allowlist is different because the policy and privileged socket are root-owned on the VM. Edit Host capabilities, then select Generate apply command. AcornOps records the requested policy as pending and returns one 15-minute, one-use command. Run it on the existing VM with sudo. The command does not contain the service list; its token is bound to the target and immutable pending policy. The applied policy remains visible separately from the pending policy. AgentV write tools are paused for both new and already-running sessions until the command commits. The installer reuses the transactional credential-replacement path, so it stages the helper policy, verifies the candidate, and only then activates the new policy and credential. If the update fails, the previous policy, credential, installation, and connection remain active. If you lose or expire the command, select Generate new apply command; this cancels the older outstanding command without changing the applied policy.

​
Run permissions

Open the VM’s Settings page to choose the same run permission modes available for Kubernetes targets:
  • Read only removes write-capable tools from VM runs.
  • Ask before changes is the production default and pauses every permitted write for approval.
  • Auto-run allowed changes permits administrator-reviewed, non-destructive writes to run without a per-call approval.
This setting never creates host capability. A service restart still requires read-write AgentV installation, an exact match in the root-owned local allowlist, a write-capable workspace role and run, and an enabled reviewed tool. High-risk or destructive tools remain approval-gated.

​
Inventory and findings

VM snapshots populate:
  • host summary and OS metadata,
  • mounted filesystem capacity,
  • process inventory,
  • systemd service inventory,
  • listening ports,
  • collector health and metrics history,
  • findings derived from host health signals.
The management console shows this data on the VM detail page. VM logs are fetched live through the connected agent and are bounded by source and limit.

​
Tools and MCP

The VM built-in tools include:
  • get_host_summary
  • list_filesystems
  • list_processes
  • get_process
  • list_services
  • get_service
  • query_logs
  • list_listeners
  • restart_service when all local, remote, and approval gates permit it
VM targets also support target-scoped remote MCP servers. Add servers from the VM detail page under MCP Servers, test discovery, then enable reviewed tools.

​
Troubleshooting chat

VM troubleshooting runs can only use tools enabled for that target and run mode. restart_service is excluded from read-only runs. Under Ask before changes it requires human approval; under Auto-run allowed changes the reviewed restart tool may run automatically, but only for a unit in the root-owned allowlist. For read-write onboarding, the root installer sets ACORNOPS_AGENT_WRITE_ENABLED=true, writes the selected exact units to /etc/acornops/agentv-actions.json, and enables the helper socket. The helper rejects every unit outside that list. Arbitrary commands, globs, AgentV’s own units, and unrestricted systemctl are not supported. After installation, run acornops-agentv-doctor. It checks configuration, required binaries, journal access, helper policy, filesystem access, and TLS. The installer adds the dedicated user to systemd-journal when available; otherwise log capability is reported as degraded instead of returning an empty successful result. VM conversations follow the same collaboration rules as Kubernetes target conversations. The creator can send follow-ups. Other users with target read access can open the conversation and watch active runs live, but the composer stays view-only. Starting a new VM conversation after recent target chat activity shows an inline warning so operators can review or continue the relevant investigation before creating a separate thread. If the VM stays disconnected, verify /usr/bin/node --version, the platform and release URLs, host CA trust, outbound HTTPS and WebSocket access, systemctl status acornops-agentv, journalctl -u acornops-agentv, and acornops-agentv-doctor. If a never-enrolled VM has no local configuration, use Finish AgentV setup. If the control plane already has an active credential but the host was rebuilt or its local configuration is missing or mismatched, generate a replacement-credential command rather than editing the durable credential manually.