Edge API Reference

Reference for targets, setup, routing, adapters, protocol, errors, events, and agent commands.

Use these APIs to declare governed edge placement and replace reference single-process infrastructure in managed deployments.

Quick Start

import { edge, runtime, stdio } from "@fentaris/core";

app.mcp("custom", {
  transport: stdio({
    command: "custom-server",
    args: ["--workspace", runtime.input("workspace")],
    env: { API_TOKEN: runtime.secret("token") },
  }),
});

app.mcp("custom").setup({
  workspace: edge.folder({ access: "read-write" }),
  token: edge.secret(),
});

Targets and Selectors

app.target(name, target)

Registers a reusable logical target. cloud is built in and reserved.

edge(options)

Creates an edge target with a device selector and optional pool strategy.

Selectors:

• edge.sessionDevice()
• edge.userDefaultDevice()
• edge.namedDevice(alias)
• edge.pool(name)
• selector.or(fallback)

Pool strategies are least-loaded, round-robin, and random.

.target(name)

Available on global, group, and user MCP handles:

app.mcp("custom").target("cloud");
app.group("developers").mcp("custom").target("personal");
app.user("alice").mcp("custom").target("personal");

app.user(id) records subject-scoped configuration. It does not create or authenticate an identity.

Runtime Inputs and Setup

Use runtime.input(name) for local/scalar values and runtime.secret(name) for secrets.

Setup builders:

• edge.folder({ access })
• edge.file({ access })
• edge.secret()
• edge.string()
• edge.boolean()
• edge.number({ min, max })
• edge.select({ options })

Cloud execution rejects unresolved runtime tokens with EDGE_UNRESOLVED_RUNTIME_INPUT. StdioTransportOptions.runtimeValues can provide explicit cloud-side string values.

Managed Installation

edge.install provides builders for nodePackage, python, binary, container, custom, and manual providers. Every recipe is canonicalized and digest-addressed. Use installedArtifact(recipe, outputName) in a launch recipe so the agent starts only a declared, verified output.

Custom sources support exact Git commits, integrity-bound archives, bounded inline content, locally approved grants, and enterprise resolvers. InstallationProviderAdapter, InstallationSourceResolver, store, mutation-lock, approval, verification, and telemetry contracts are replaceable. The default local coordinator persists attempts, lifecycle, active pointers, retention references, and approvals before reporting success.

EdgeInstallationTelemetry emits redacted source, approval, attempt, verification, activation, rollback, and cleanup events. edgeInstallationHealth(...) adds checks for interrupted attempts, stale lifecycle, storage pressure, isolation support, orphaned artifacts, and agent upgrade requirements.

Core Runtime Adapters

McpProxyOptions.edge accepts:

• deviceResolver
• sessionBindingStore
• sessionBindingExpiry
• sessionBindingListener
• transport
• capabilityCache
• telemetry
• sessionSelectionStore
• childBindingManager
• control

Reference implementations include EdgeTransport, EdgeWebSocketGateway, InMemorySessionBindingStore, control-plane stores, and EdgeCapabilityCache.

Integrated Control Plane

Set McpProxyOptions.edge.controlPlane to let app.start() own device authorization, enrollment, the WebSocket gateway, desired-state planning, reconciliation, inventory reports, capability publication, health, and shutdown.

const app = new McpProxy({
  servers: [workspaceServer],
  targets: { personal: edge({ device: edge.userDefaultDevice() }) },
  setup: { workspace: { root: edge.folder({ access: "read-write" }) } },
  placements: [
    { serverName: "workspace", scope: "global", targetName: "personal" },
  ],
  edge: {
    controlPlane: {
      enabled: true,
      mode: "local",
      publicOrigin: "http://127.0.0.1:4000",
    },
  },
});

await app.start();

At startup Fentaris compiles an immutable catalog from MCP transports, setup schemas, installation recipes, targets, placements, and subject scopes. Enrollment, connection, inventory, readiness, assignment, and revocation events reconcile canonical per-device desired state. Versions advance only when the effective set changes.

Local mode uses an atomic owner-only authority store and protected operator channel. It is durable across restarts but deliberately single-process. Managed mode requires durable device, desired-state, setup, manifest, connection, presence, readiness, assignment, authorization, token, and enrollment adapters; startup fails closed if any required adapter is absent.

Public routes live under basePath (default /_fentaris/edge): device authorization and polling, refresh, enrollment, self-revocation, verification, and /ws. URLs are derived only from publicOrigin, never request host or forwarded headers. Non-loopback deployments require HTTPS/WSS.

Dispatch is allowed only when authorization, assignment, connection generation, desired recipe, readiness, and manifest support all agree. Ambiguous or incomplete deployments are withheld with bounded diagnostics. Revocation removes desired state, rotates or invalidates credentials, evicts capability state, and terminates the active generation.

Health exposes only bounded counts and redacted component status. A local runtime is reported degraded with a single-process warning; an unavailable required managed adapter is an unhealthy startup failure.

In-memory stores and the gateway active-socket map are single-process references. Multi-instance deployments require shared session bindings, device/desired/setup/manifest stores, and a distributed EdgeChannelBroker.

Edge Control configuration

edge.control is explicit opt-in configuration. It requires the policy-filtered EdgeInventoryService and EdgeSessionSelectionService used by the control plane.

const proxy = new McpProxy({
  policy: policy("agents")
    .mcp("edge").allow("list")
    .mcp("edge").allow("get")
    .mcp("edge").allow("select")
    .mcp("edge").allow("call")
    .mcp("edge").allow("call_many"),
  edge: {
    transport: edgeTransport,
    sessionSelectionStore,
    childBindingManager,
    control: {
      enabled: true,
      inventory,
      selections,
      defaultTargetName: "personal",
      limits: {
        maxDevices: 8,
        maxConcurrency: 4,
        maxDeadlineMs: 120000,
        maxSelectorCandidates: 100,
        maxChildBytes: 1000000,
        maxAggregateBytes: 4000000,
      },
    },
  },
});

The namespace edge is reserved. Individual tools remain hidden or denied unless effective policy allows them.

Edge Control result contracts

Discovery uses public { name, inventoryVersion } references. edge__call returns the selected public device, a server-generated correlation ID, a terminal status, and the sanitized MCP result. edge__call_many returns stable counts and exactly one succeeded, failed, cancelled, or not-started entry per resolved device.

Explicit input order is preserved. Declarative results are ordered by normalized public name. User limits can only reduce configured limits.

Agent APIs

@fentaris/edge exports:

• EdgeAgent and EdgeEnrollmentService
• LocalSetupManager and TerminalSetupProvider
• EdgeWorkloadSupervisor
• ExecutableAllowlistPolicy
• platform, credential, process, and connection adapter contracts

The initial process model is one local MCP process/client per { deployment, downstream session }.

Protocol Compatibility

EDGE_PROTOCOL_VERSION is 3; EDGE_MCP_ENVELOPE_VERSION remains 1. Hello negotiates the highest mutually supported protocol version. Version 1 agents retain transparent Edge execution, version 2 adds bounded observed facts and orchestration correlation, and version 3 adds managed-installation desired state, lifecycle, approval, retry, removal, installation digest, and launch digest correlation. Every accepted connection is bound to tenant, edge node, credential, protocol version, and a monotonically increasing connection generation.

Messages cover hello, heartbeat, desired state, setup status, capability manifests, lifecycle, MCP requests/results/errors, and cancellation.

Servers must reject routing claims that do not match server-side device, deployment, subject, target, and session state.

Agent	Transparent execution	Presence and facts	Agent-native orchestration
Protocol v1	Supported	Legacy heartbeat only	Not eligible for v2 fact/readiness selectors
Protocol v2	Supported	Bounded facts, capacity, load, freshness, readiness	Supported when Edge Control is enabled and policy allows it
Protocol v3	Supported	Installation, setup, workload, and digest-correlated readiness	Supported, including managed installation

Roll out the control plane first, then proxies, then upgrade agents. The gateway negotiates the highest mutual version, so v1, v2, and v3 agents can coexist. To roll back, stop assigning managed-installation recipes, disable edge.control and new selectors, then roll back agents. Transparent legacy routing continues. Do not downgrade stored identity, inventory, installation, or approval records during rollback.

The fentaris-edge compatibility commands remain available during the migration window and map to the new services with warnings. New automation should use fentaris edge. A future major release may remove the legacy command names after a documented deprecation period.

Stateful failover and automatic mutation retry are not supported. Lost non-idempotent calls are reported as indeterminate and are never automatically replayed.

Errors

Stable edge codes:

• EDGE_PLACEMENT_AMBIGUOUS
• EDGE_UNAUTHORIZED_TARGET
• EDGE_SETUP_REQUIRED
• EDGE_UNAVAILABLE
• EDGE_CAPACITY
• EDGE_SESSION_PINNED
• EDGE_INPUT_INVALID
• EDGE_INVENTORY_CONFLICT
• EDGE_NAME_CONFLICT
• EDGE_PROTOCOL
• EDGE_WORKLOAD
• EDGE_GRANT
• EDGE_UNRESOLVED_RUNTIME_INPUT

Events and Health

EdgeTelemetry emits structured redacted events for target resolution, session binding, connection generations, desired-state reconciliation, setup, workloads, request duration, timeout, cancellation, failure, and parent/child orchestration lifecycle.

edgeHealth(...) adds checks for gateway, target resolution, device/pool availability, deployment readiness, capability cache age, inventory stores, presence expiry, selections, child cleanup, distributed routing, protocol distribution, and stale readiness.

Sensitive metadata is removed by redactEdgeProtocolValue(...) before telemetry reaches its sink. serializeEdgePublicValue(...) additionally bounds depth, collection size, string length, circular references, and encoded bytes.

Managed adapters can implement EdgePoolSelectionStore and EdgeResultCorrelationStore. Use diagnoseEdgeProductionAdapters(...) before production rollout. EDGE_DISTRIBUTED_CONSISTENCY_REQUIREMENTS documents the required compare-and-set, atomic-take, expiry, pool-selection, and channel-delivery semantics.

Agent CLI

fentaris edge join https://fentaris.example --name "Mac Studio"
fentaris edge run
fentaris edge service restart
fentaris edge list --as user:alice --json
fentaris edge status
fentaris edge disconnect "Mac Studio" --yes
fentaris edge revoke "Mac Studio" --yes

There is no MCP add/configuration command. Definitions and assignments remain controlled by Fentaris.

Related Documentation

• Edge Execution
• Set Up an Edge Device
• Observability