Config File

Configure Fentaris project discovery, runtime entrypoint, endpoint, and local auth directory.

Generated projects use fentaris.json at the project root. The CLI uses this file to discover the project, run scripts, validate local state, and build runtime metadata. When an app starts without explicit port or path options, @fentaris/core also searches upward from the current working directory and uses the nearest project config defaults.

SDK-only projects do not need fentaris.json for local auth and secrets commands. When fentaris auth or fentaris secrets cannot find a project config file, it can discover the nearest package.json that depends on @fentaris/core and use optional package.json metadata for the entrypoint and local runtime directory.

Quick Start

{
  "name": "my-proxy",
  "packageManager": "pnpm",
  "entrypoint": "src/index.ts",
  "port": 4000,
  "path": "/mcp",
  "authDir": ".fentaris",
  "edge": {
    "controlPlane": {
      "enabled": false,
      "mode": "local",
      "stateDir": "edge-control-plane"
    }
  }
}

Fields

name

Project name used in generated metadata and CLI output.

"name": "my-proxy"

packageManager

Package manager used for generated scripts. During fentaris init, the selected binary is also used for dependency installation unless --skip-install is passed.

"packageManager": "pnpm"

Allowed values:

• pnpm
• npm
• bun

entrypoint

Runtime entrypoint copied into build metadata.

"entrypoint": "src/index.ts"

The file must exist for project health checks to pass.

port

Local port printed by fentaris dev, used by runtime checks, and used by app.start() when the app does not pass an explicit port.

"port": 4000

path

MCP endpoint path served by the generated proxy. app.start() uses this path when the app does not pass an explicit path.

"path": "/mcp"

The default local endpoint is http://localhost:4000/mcp.

authDir

Directory for local encrypted credentials and CLI auth state.

"authDir": ".fentaris"

Generated projects include .gitignore entries for .fentaris/ because it contains local credentials and build output. The committed .fentaris/secrets.manifest.json schema is not ignored.

secrets

Optional secrets provider settings. Generated projects default to the local encrypted store.

"secrets": {
  "provider": "local"
}

fentaris

Optional Fentaris Cloud project metadata for forward-compatible cloud sync. Cloud sync is not available yet; keep using the local encrypted store.

"fentaris": {
  "projectId": "proj_123",
  "environment": "production"
}

SDK-Only Auth and Secrets Metadata

SDK-only projects can configure fentaris auth and fentaris secrets without creating fentaris.json:

{
  "dependencies": {
    "@fentaris/core": "^2.0.0"
  },
  "fentaris": {
    "entrypoint": "src/server.ts",
    "authDir": ".fentaris"
  }
}

Supported fields:

• entrypoint - TypeScript file scanned by fentaris secrets manifest.
• authDir - local runtime directory for secrets.manifest.json and credentials.enc.json, used by both auth and secrets commands.
• port, host, and path - optional defaults used by the synthetic secrets project model.

If entrypoint is omitted, fentaris secrets manifest checks src/index.ts, src/main.ts, and index.ts. Pass --entrypoint <path> when the file uses another name.

Application Config: cli.mcpAccounts

Agent-native tool discovery commands read cli.mcpAccounts from the Fentaris application config exported by the project entrypoint. Each MCP key declares the default selector and the selectors an agent may request with --as.

edge.controlPlane

The integrated device authority, enrollment routes, WebSocket gateway, planner, and reconciler are disabled by default. A minimal local development configuration is:

{
  "edge": {
    "controlPlane": {
      "enabled": true,
      "mode": "local",
      "publicOrigin": "http://127.0.0.1:4000",
      "basePath": "/_fentaris/edge",
      "stateDir": "edge-control-plane"
    }
  }
}

publicOrigin is the canonical origin used to generate enrollment and gateway URLs. Non-loopback origins must use HTTPS. basePath must not overlap the MCP path. stateDir is resolved beneath authDir and must not escape it.

Serializable configuration accepts only safe scalar fields. Approval callbacks, assignment resolvers, managed stores, and authorization services are TypeScript-only McpProxyOptions.edge.controlPlane adapters. Managed mode fails startup unless every required durable adapter is present.

The separate edge.control option enables agent-native inventory and explicit orchestration tools. It is independent from the integrated connection control plane and remains an explicit policy-governed opt-in. See Edge API Reference.

import { defineFentarisConfig, mcp, policy } from "@fentaris/core";

export default defineFentarisConfig({
  servers: [
    mcp("github", {
      transport: githubTransport,
    }),
  ],
  policy: policy("default").mcp("github").allow("*"),
  cli: {
    mcpAccounts: {
      github: {
        default: "user:alice",
        allowed: ["user:alice", "group:support"],
      },
    },
  },
});

cli.mcpAccounts.<mcp>.default

Default account selector used when fentaris tools ... --mcp <mcp> omits --as.

The selector must be present in allowed.

cli.mcpAccounts.<mcp>.allowed

Selectors the CLI may use for the MCP. Values use user:<id> or group:<id>.

cli.mcpAccounts bounds CLI discovery choices. It is not a security boundary by itself; effective access still comes from Fentaris policy and credential resolution.

Legacy Filename

The CLI can still discover fentaris.config.json, but generated projects use fentaris.json.

mv fentaris.config.json fentaris.json

Related Documentation

• Quickstart
• CLI Usage
• Environment variables