manual or template. Origin does not add capabilities, bypass authorization, alter readiness, or choose a different execution path. Workspace-owned starter definitions may be edited, disabled, duplicated, or deleted. A completed installation marker remains as a tombstone, so deleting starter content does not silently recreate it. Existing workspaces and operator edits are not overwritten when the shipped starter bundle changes. An explicit Use template reinstall is required to restore deleted starter content.
Readiness is explicit for every definition:
readymeans the saved definition and its assigned Agents can provide their reviewed capability ceiling.needs_setuplists missing live prerequisites such as a reviewed capability mapping or installed integration.blockedidentifies a policy or capability mismatch that an administrator must resolve.
Specialist Agents
Workspace administrators create specialist Agents through the editor or API. A specialist receives reviewed semantic capabilities and exact operational resources from the live catalog. New workspaces start with two workspace-owned specialists:- Kubernetes Agent specializes in Kubernetes operations. It can use reviewed read and write tools exposed through the generic Targets MCP server. Every write remains approval-gated.
- Virtual Machine Agent specializes in Linux virtual-machine diagnostics. It requests read-only diagnostic capability and does not request remediation capability, so it is ready without AgentV’s optional privileged helper.
targets MCP facade; Agents and Workflows do not store target IDs or target types. Each target is selected and validated from target_id and target_type only when the tool is called. An administrator can disable the built-in server or individual tools. If AgentV advertises restart_service, its catalog entry is enabled, but an administrator must explicitly grant remediation capability before an Agent can use it. The starter Agents also retain the PDF tool used by the current reporting Workflows.
Coordination is system-owned. The coordinator is a code-owned Workflow executor, not an Agent. Its profile is snapshotted into each new coordinator root attempt and is never exposed through Agent APIs.
A coordinated workflow asks AcornOps to perform work for a semantic capability. Delegation selects an eligible specialist from the Workflow’s assigned Agents by reviewed mapping priority and stable Agent ID. It intersects Agent capabilities, principal permissions, workspace policy, and connection readiness. If the specialist calls the generic targets MCP server, that individual call supplies the target identity. Semantic labels never authorize tools on their own.
Coordination is one level deep and allows at most four concurrent child runs and eight child runs total. These limits are server-owned. Writes require approval for the exact tool and arguments. AcornOps does not automatically retry after execution starts or after a write has an uncertain result. Successful child results remain available if another child fails; required and optional failures are reported separately.
Workflows
A Workflow contains a plain-text prompt, requiredagentIds, a semantic
capability policy, and optional schedule configuration. Agent selection is a set; array order has no routing
meaning and IDs must be unique and non-empty.
Select one Agent to run the Workflow directly. Select two or more Agents for AcornOps to coordinate. Workflow responses derive executionMode as direct or coordinated; it is not an authoring input.
Creating a Workflow session records a non-executable capability ceiling. The first structured launch message contains only kind: "launch" and an optional idempotency key. The control plane compiles the saved prompt and revalidates current authorization under the authenticated user. Semantic capability IDs such as infrastructure.diagnostics.read describe routing requirements but never authorize a tool by themselves. Existing runs keep their pinned execution mode and scope when you edit a Workflow. Future runs use the new definition and live provider state.
Saved prompts
Workflow prompts are saved plain text and do not accept runtime parameters. Launches from the console, schedules, webhooks, and external integrations all run the same saved definition. Literal{{...}} text has no template meaning.
Workflows do not bind targets. Name a target in the prompt when the task needs one. The model interprets that text and may call an eligible target MCP tool with the corresponding target_id. This is intentionally non-deterministic: an ambiguous, unknown, or unavailable target is reported only if the model attempts that tool call. Workflows that do not concern infrastructure targets, such as source-control automation, simply use the other tools on their assigned Agents.
The capability policy has two explicit modes:
inherituses the selected Agents’ current combined reviewed ceiling.semanticCapabilityIdsmust be empty. Each new session resolves and pins the effective set, so an Agent grant or revocation affects future sessions without expanding an existing run.restrictusessemanticCapabilityIdsas an explicit subset of the selected Agents’ combined ceiling. An empty array intentionally creates a zero-capability workflow.
AGENT_MAX_RUNTIME_MS sets the execution limit. GENERATED_DOCUMENT_RETENTION_DAYS sets document retention. Legacy API requests may still include maxRuntimeSeconds or retentionDays, but the control plane ignores those values and returns the effective deployment policy.
Direct readiness checks the selected specialist. Coordinated readiness requires an eligible selected specialist mapping for every effective capability. Each automatic health check selects its matching specialist directly. Kubernetes-only remediation selects the Kubernetes Agent, while Incident investigation coordinates both Agents.
Before Launch, the console requests a capability preview. Definition review
keeps semantic capabilities separate from direct MCP servers, installed skills,
and directly attached tools. It lists target MCP tools inherited from the
assigned Agents without selecting or evaluating a target. Write rows identify their
approval requirement. Credentialed MCP dependencies appear in a Required
auth row with the server name, personal or workspace ownership, credential
label, and required setup information. The preview never returns the credential
value. The preview does not create a session or reserve access;
launch revalidates current authority and the dispatched run’s compiled scope is
the final source of truth.
The signed run scope limits target MCP calls to exact generic Targets MCP tool
references allowed by reviewed mappings. The automatic VM health check and starter VM Agent remain
read-only even when AgentV advertises restart_service. The current opt-in
Infrastructure remediation template instructs its assigned Kubernetes specialist to
operate on a Kubernetes target named in the request; the Agent’s Targets MCP
policy remains authoritative.
The template drawer exposes these Workflow records:
Template manifests contain prose, safe policy defaults, semantic requirements, and symbolic relationships only. Provisioning generates record IDs and resolves relationships inside the workspace transaction. It does not contain workspace or target IDs, MCP server IDs or URLs, external tool aliases, skill installation IDs, credentials, or connection assumptions. Shipped bundle changes do not overwrite existing workspace-owned definitions.
Schedules store cadence and principal—not launch inputs or access grants. Every occurrence compiles the current active saved prompt and execution scope from the assigned Agent capabilities. An invalid definition, deletion, integration outage, membership change, or authorization failure auto-pauses the schedule with a bounded actionable reason; repair the cause and resume it manually.
Organize workflows and Activity
Open Workflows in the management console to use three views:- All Workflows contains installed Workflow definitions and manual launch.
- Schedules contains recurring Workflow dispatches.
- Incoming Webhooks contains signed endpoints that start Workflows from external systems.
- Configuration shows whether the schedule or webhook is enabled or paused.
- Last dispatch shows whether the latest occurrence dispatched, failed, was rejected, or was skipped.
- Latest execution shows the actual run state when dispatch created one.
Create a custom workflow
AcornOps does not install a repository-review Agent or workflow. When you need a repository-oriented or other external workflow:- Create a specialist Agent with the instructions and permission mode you need.
- Attach a compatible MCP server from the Agent’s MCP page.
- Connect personal authentication when required, discover its tools, and review each exact tool.
- Create a workflow and select that Agent.
- Preview the effective scope before activation.
GET /api/v1/workflow-executions/{executionId} includes an AcornOps coordination summary. Each child shows its capability, selected Agent, status, and a bounded failure when applicable. The response excludes internal coordinator identity, task prompts, compiled scopes, results, credentials, and tool arguments.
Target-native chat
Kubernetes and virtual-machine chat does not select, pin, or hand off to a workspace Agent. Each session automatically uses the target’s generic assistant. At run creation, AcornOps queries the live target capability registry and pins the exact native tools, target MCP tools, and target skill snapshots permitted by the user, requested tool-access mode, AgentK or AgentV advertisement, and current target/workspace policy. Configured third-party target MCP tools are eligible when their real connection is ready. Authorization is rechecked before every tool call, and target instructions come from the target adapter contract rather than a workspace Agent profile.External integration sessions
A linked external integration can launch an active Workflow when its client ceiling, user-approved workspace grant, and linked user role include the required capability. Ungated read-only Workflows requirecreate_read_only_runs. Read-write and approval-gated Workflows also require
create_read_write_runs.
The Workflow session is the persistent conversation. It accepts one successful
launch message, followed by ordinary follow_up messages. Every interactive
launch creates a fresh session. An idempotent retry of the same launch returns
the original execution; a second launch is rejected. A direct execution creates a specialist root run; a coordinated
execution creates a coordinator root and its specialist child runs. Keep the
session ID as the external thread mapping. Resource parameter IDs are retained
by the session and reauthorized on each follow-up. Replies after completion use
the same stored Workflow snapshot and retained history, but require a new
clientRequestId and fresh approvals.
Use the sanitized execution endpoint for current state and the aggregate
execution SSE stream for step/run discovery, approvals, safe outputs, and the
terminal event. Workspace readers may inspect these safe views regardless of
origin. Only the exact originating integration link/client may post external
replies, decide approvals, or retrieve reports.