Set Up an Edge Device

Install, enroll, assign, inspect, and revoke a Fentaris edge device.

Use fentaris edge on the computer that owns the filesystem, credentials, or local process you want an MCP client to use.

Quick Start

npx @fentaris/edge join https://fentaris.example \
  --name "Mac Studio" \
  --description "Local builds and Xcode" \
  --tag development \
  --tag xcode

Open the displayed verification URL and enter the user code. Join creates a random device keypair, proves possession, enrolls the device, and installs a per-user background service when the platform permits it. No global package installation is required for the npx form.

For an application using the integrated local control plane, approve the displayed code from the application project:

fentaris edge approve ABCD-EFGH --subject alice

Approval travels through an owner-only local operator socket. The CLI does not read or mutate the protected authority database. Enrollment, connection, desired-state reconciliation, and capability publication then happen without custom gateway wiring.

If native service installation is unavailable, the device stays enrolled and the command returns fentaris edge run as the foreground fallback. Pass --no-service to choose foreground operation or --service to fail unless persistent installation succeeds.

The local executable allowlist is deny-by-default. Set FENTARIS_EDGE_ALLOWED_EXECUTABLES for direct executables or FENTARIS_EDGE_ALLOWED_PACKAGES for packages launched through npx, pnpm, yarn, or bunx. Values are comma-separated exact names.

The hostname is a display label, not device identity. Copying non-secret config without the protected key cannot authenticate another installation as the device.

Define and Assign the Workload

The application defines the MCP. The edge CLI does not have an add command.

app.mcp("filesystem", {
  transport: stdio({
    command: "filesystem-mcp",
    args: ["--workspace", runtime.input("workspace")],
  }),
});

app.mcp("filesystem").setup({
  workspace: edge.folder({ access: "read" }),
});

app.target("personal", edge({
  device: edge.userDefaultDevice(),
}));

app.user("alice").mcp("filesystem").target("personal");

The local prompt shows the recipe digest and requested access. Approving a folder stores its canonical path locally and reports only an opaque grant ID.

Install an Assigned MCP Server

Declare installation separately from the launch recipe. Managed installation supports exact Node package versions with integrity, exact Python versions with hashes, immutable binary archives, container image digests, custom sources, and manual prerequisites.

const installer = edge.install.custom({
  source: {
    kind: "git",
    repository: "https://github.com/example/filesystem-mcp-installer.git",
    commit: "0123456789abcdef0123456789abcdef01234567",
  },
  entrypoint: "install.sh",
  interpreter: "sh",
}, {
  permissions: {
    network: "source-only",
    requireNetworkIsolation: true,
    executables: ["sh"],
  },
  verification: [{ kind: "executable", target: "bin/filesystem-mcp" }],
  outputs: [{ name: "server", kind: "executable", path: "bin/filesystem-mcp" }],
});

app.mcp("filesystem", {
  transport: stdio({ command: installedArtifact(installer, "server") }),
});

Git recipes require an exact 40-character commit. Archives, packages, distributions, and containers require immutable digests or hashes. Private source credentials are resolved from the local encrypted credential store and are never placed in command arguments, desired state, inventory, or review output.

Custom installers require local review of the exact source identity, entrypoint, arguments, permissions, outputs, verification, cleanup plan, and effective policy digest. Denial and revocation are sticky. Any effective-plan change creates a new approval identity. A custom cleanup with external side effects requires a separate --cleanup review and approval.

Fentaris rejects floating Git refs, credentials embedded in URLs, archive traversal, symlinks escaping staging, submodules, undeclared executables, elevation, and required isolation that the device cannot enforce.

Keep desktop applications as manual prerequisites:

const desktopApp = edge.install.manual({
  requirement: "Example Desktop MCP 3.2",
  detect: { kind: "executable", target: "example-desktop-mcp", expectedVersion: "3.2.0" },
  nextAction: "Install Example Desktop MCP 3.2 from the approved vendor package, then retry locally.",
}, {
  outputs: [{ name: "server", kind: "executable", path: "example-desktop-mcp" }],
  cleanup: { kind: "manual" },
});

Fentaris detects this prerequisite but does not download, elevate, install, update, or remove it.

Review and Recover Installations

fentaris edge installation status --json
fentaris edge installation review filesystem --json
fentaris edge installation approve filesystem --yes --json
fentaris edge installation retry filesystem --yes --json

For a custom external cleanup, review and approve the cleanup identity separately before removal:

fentaris edge installation review filesystem --cleanup --json
fentaris edge installation approve filesystem --cleanup --yes --json
fentaris edge installation cleanup filesystem --yes --json

Lifecycle states distinguish assignment, checking, approval, installation, verification, setup, startup, readiness, degradation, failure, removal, and rollback. Retried failures create a new attempt; they do not overwrite diagnostics. Updates install into a digest-addressed root and activate only after verification. Shared artifacts are deleted only after their final deployment reference is removed.

Protocol v3 carries correlated installation and launch digests. Older agents can continue compatible transparent execution, but a deployment requiring managed installation remains blocked with agent-upgrade-required until an eligible agent connects.

Inspect and Disconnect

fentaris edge status
fentaris edge list --as user:alice --compact --json
fentaris edge disconnect "Mac Studio" --yes

Status reports connection, desired deployments, readiness, and blocked counts. It does not print local paths, tokens, credentials, secrets, or full environments.

disconnect closes the channel and stops workloads according to shutdown policy. Existing pinned sessions fail with EDGE_UNAVAILABLE; they do not move to another device.

Use Edge Control From an Agent

After the application explicitly enables and governs Edge Control, an MCP client can discover eligible devices without knowing physical IDs:

{
  "name": "edge__select",
  "arguments": {
    "target": "personal",
    "selector": {
      "requires": { "features": ["filesystem"], "platforms": ["darwin"] },
      "prefer": ["lowest-load"]
    }
  }
}

Call the effective tool normally after selection. Use edge__call only when the agent must name one device explicitly, and use edge__call_many for a bounded parallel operation. Fan-out accepts either devices or selector, never both.

{
  "name": "edge__call_many",
  "arguments": {
    "selector": { "requires": { "pool": "build-workers", "features": ["xcode"] } },
    "tool": "builder__check",
    "arguments": { "project": "app" },
    "concurrency": 2,
    "deadlineMs": 60000,
    "failurePolicy": "collect"
  }
}

The result contains one terminal entry per resolved device. fail-fast stops new work and cancels cancellable children; it does not roll back completed mutations.

Revoke the Device

fentaris-edge revoke

Revocation removes the server-side device authorization, stops the local connection, and deletes local identity, grants, and setup secrets. Grant or workload denial is also sticky: replaying desired state cannot restart it until local consent is renewed.

Placement Examples

Personal filesystem

app.target("personal", edge({ device: edge.userDefaultDevice() }));
app.user("alice").mcp("filesystem").target("personal");

Group-scoped personal devices

app.target("member-device", edge({
  device: edge.sessionDevice().or(edge.userDefaultDevice()),
}));
app.group("developers").mcp("workspace").target("member-device");

Shared worker pool

app.target("team-workers", edge({
  device: edge.pool("team-workers"),
  strategy: "least-loaded",
}));
app.group("build-team").mcp("builder").target("team-workers");

Cloud fallback

Omit a placement binding to use implicit cloud, or bind it explicitly:

app.mcp("search").target("cloud");

Selector fallback can choose another eligible selector before pinning. It does not fail over after a session is pinned.

Troubleshooting

Setup remains pending

Run fentaris edge status. Approve every required field and the current recipe digest. A schema access change invalidates only affected grants.

Device reconnects but calls fail

An existing session is pinned to its original connection generation. Start a new downstream MCP session after reconnection.

Command is denied

Add the exact executable or package to FENTARIS_EDGE_ALLOWED_EXECUTABLES or FENTARIS_EDGE_ALLOWED_PACKAGES, reconnect the agent, then renew consent for the recipe digest. Do not allow a shell interpreter as a generic workaround.

Related Documentation

• Edge Execution
• Edge API Reference
• Troubleshooting