Extension surfaces: mcp.*, skills.*, plugins.*, and canvas.*.

For the full key index and the other top-level config domains, see Configuration reference.

MCP

Apus-managed MCP server definitions live under mcp.servers for embedded Apus and other runtime adapters. apus mcp list, show, set, and unset manage this block without connecting to the servers. The Fetch example requires uv/uvx.

{
  mcp: {
    servers: {
      docs: {
        command: "uvx",
        args: ["mcp-server-fetch"],
      },
      remote: {
        url: "https://example.com/mcp",
        transport: "streamable-http", // streamable-http | sse
        requestTimeoutMs: 20000,
        connectionTimeoutMs: 5000,
        supportsParallelToolCalls: true,
        headers: {
          Authorization: "Bearer ${MCP_REMOTE_TOKEN}",
        },
        auth: "oauth",
        oauth: {
          identity: "per-requester", // shared | per-requester; default: shared
          scope: "docs.read",
        },
        sslVerify: true,
        clientCert: "/path/to/client.crt",
        clientKey: "/path/to/client.key",
        toolFilter: {
          include: ["search_*"],
          exclude: ["admin_*"],
        },
        // Optional Codex app-server projection controls.
        codex: {
          agents: ["main"],
          defaultToolsApprovalMode: "approve", // auto | prompt | approve
        },
      },
    },
  },
}

See MCP and CLI backends for runtime behavior.

Skills

{
  skills: {
    allowBundled: ["gemini", "peekaboo"],
    load: {
      extraDirs: ["~/path/to/agent-scripts/skills"],
      allowSymlinkTargets: ["~/path/to/skills"],
    },
    install: {
      preferBrew: true,
      nodeManager: "npm", // npm | pnpm | yarn | bun
      allowUploadedArchives: false,
    },
    entries: {
      "image-lab": {
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string
        env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" },
      },
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
  },
}

Plugins

{
  plugins: {
    enabled: true,
    allow: ["voice-call"],
    deny: [],
    load: {
      paths: ["~/path/to/oss/voice-call-plugin"],
    },
    entries: {
      "voice-call": {
        enabled: true,
        hooks: {
          allowPromptInjection: false,
        },
        config: { provider: "twilio" },
      },
    },
  },
}

Codex harness plugin config

The bundled codex plugin owns native Codex app-server harness settings under plugins.entries.codex.config. See Codex harness reference for the full config surface and Codex harness for the runtime model.

codexPlugins applies only to sessions that select the native Codex harness. It does not enable Codex plugins for Apus provider runs, ACP conversation bindings, or any non-Codex harness.

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          codexPlugins: {
            enabled: true,
            allow_all_plugins: true,
            allow_destructive_actions: "auto",
            plugins: {
              "google-calendar": {
                enabled: true,
                marketplaceName: "openai-curated",
                pluginName: "google-calendar",
                allow_destructive_actions: false,
              },
            },
          },
        },
      },
    },
  },
}

Each admitted plugin app that uses "ask" routes that app's approval requests to the human reviewer. Other apps and non-app thread approvals keep their configured reviewer, so mixed plugin policies do not inherit "ask" behavior.

codexPlugins.enabled is the global enablement directive. Explicit plugin entries written by migration preserve durable curated install and repair eligibility. An owner or operator.admin can add other discovered plugins with /codex plugins install <plugin>@<marketplace>; Codex still controls upstream installation and connector authentication. Plugins without exact identity, installation, or accessible app ownership fail closed. plugins["*"] is not supported, and local marketplacePath values are intentionally not config fields because they are host-specific. See Native Codex plugins for app-server version and readiness requirements.

app/installed readiness checks (with authorized metadata from batched app/read) are cached for one hour and refreshed asynchronously when stale. Codex thread app config is computed at Codex harness session establishment, not on every turn; use /new, /reset, or a gateway restart after changing native plugin config.

codexPlugins.allow_all_plugins snapshots every currently accessible account app into each new native Codex thread. It does not install plugins or apps, and inaccessible apps stay excluded. Account apps use the global codexPlugins.allow_destructive_actions policy. Explicit plugin entries take precedence when the same app is present in both paths. If app/installed cannot be read, account-wide exposure fails closed.

See Plugins.

Canvas widget presenter

{
  plugins: {
    entries: {
      canvas: {
        config: {
          host: {
            enabled: true, // set false, or use APUS_SKIP_CANVAS_HOST=1
          },
        },
      },
    },
  },
}