> ## Documentation Index
> Fetch the complete documentation index at: https://comis-fix-skill-import-vetting-gate.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Infrastructure
> Configuration management, gateway control, and supervisor administration tools
**What it does:** Lets agents manage the Comis daemon itself -- read and write configuration, restart, store secrets, inspect long-running tasks, and (for supervisor agents) manage the entire system.
**Who it's for:** Admin or supervisor agents that need to operate the platform from inside a conversation. These tools are gated behind the `supervisor` tool policy profile or an explicit allow list -- they should not be exposed to general-purpose agents.
The `browser` tool also lives at the platform-management layer, but it has its own deep-dive page since it has 16 actions and 11 `act` sub-kinds. See [Browser](/agent-tools/browser) for that.
## gateway -- Configuration and Control
The `gateway` tool is the Swiss Army knife for system management, with **11 actions** -- `read`, `patch`, `apply`, `restart`, `schema`, `status`, `history`, `diff`, `rollback`, `env_set`, and `env_list` -- covering configuration, daemon restarts, change history, and the encrypted secret store.
### Gateway Actions
Read the current value of any configuration setting.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | --------------------------------------------------------------------------------------------------------- |
| `action` | string | Yes | `"read"` |
| `section` | string | No | Config section name to read (e.g., `"agents"`, `"channels"`, `"memory"`). Omit to read the entire config. |
Returns the current in-memory value for the specified section. Useful for checking settings before making changes.
Update a single configuration value in memory. The change does not take effect until you call `apply`.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | -------------------------------------------------------------------------- |
| `action` | string | Yes | `"patch"` |
| `section` | string | Yes | Config section name (e.g., `"agents"`, `"channels"`, `"security"`) |
| `key` | string | Yes | Dot-notation key within section (e.g., `"maxSteps"`, `"budget.maxTokens"`) |
| `value` | any | Yes | The new value to set (string, number, boolean, object, or array) |
Changes from `patch` are held in memory only. Call `apply` to write them to disk and reload the configuration. Immutable security-sensitive config paths are rejected before confirmation.
Replace an entire config section atomically, writing changes to disk and triggering a restart.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------ |
| `action` | string | Yes | `"apply"` |
| `section` | string | Yes | Config section to replace |
| `value` | any | Yes | The complete new section value |
This is a destructive action that requires user confirmation via the `_confirmed` parameter. After calling `apply`, the daemon restarts and new settings are active immediately.
Restart the Comis daemon process. Use this after significant configuration changes that require a full restart.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ----------- |
| `action` | string | Yes | `"restart"` |
The daemon shuts down gracefully and restarts. Connected channels will briefly disconnect and reconnect. This is a destructive action requiring user confirmation.
View the JSON Schema for a specific config section, showing available options, types, and defaults.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ----------------------------------------------------------- |
| `action` | string | Yes | `"schema"` |
| `section` | string | No | Config section to inspect (omit for the full config schema) |
Check the health status of the daemon and gateway, including uptime, connected channels, and resource usage.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ----------- |
| `action` | string | Yes | `"status"` |
View a log of recent configuration changes, showing what was changed, when, and by whom.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------------------------- |
| `action` | string | Yes | `"history"` |
| `section` | string | No | Filter history to a specific config section |
| `limit` | number | No | Maximum number of entries to return (default: 10) |
Compare the current in-memory configuration against a previous version. Useful for reviewing changes before calling `apply`.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------------------------------------------------------------- |
| `action` | string | Yes | `"diff"` |
| `sha` | string | No | Git commit SHA to compare against. Omit to compare against the version saved on disk. |
Revert the configuration to a previous version from the change history.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ----------------------------------------------------------------- |
| `action` | string | Yes | `"rollback"` |
| `sha` | string | Yes | The git commit SHA to revert to (visible in the `history` output) |
This is a destructive action requiring user confirmation. Triggers a daemon restart after rollback.
Store a secret or environment variable in the daemon's encrypted secret store. After storing, reference the secret in config YAML as `${VAR_NAME}`.
| Parameter | Type | Required | Description |
| ----------- | ------ | -------- | ---------------------------------------------------------------------- |
| `action` | string | Yes | `"env_set"` |
| `env_key` | string | Yes | Environment variable / secret name (uppercase, e.g., `OPENAI_API_KEY`) |
| `env_value` | string | Yes | Secret value to store. Write-only: cannot be read back. |
Setting environment variables requires security approval and user confirmation. The stored value is write-only and cannot be retrieved. Reference it in config as `${VAR_NAME}` (e.g., `GEMINI_API_KEY: ${GEMINI_API_KEY}`). Never write raw API keys into config files.
List the names of secrets stored in the daemon's encrypted secret store. Read-only and admin-trust gated -- the values themselves are never returned. Use before asking the user for a key to check whether it is already configured.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | -------------------------------------------------------------------------------------------------------- |
| `action` | string | Yes | `"env_list"` |
| `filter` | string | No | Glob filter on secret names (e.g., `"GEMINI*"`, `"*_API_KEY"`). Case-insensitive, supports `*` wildcard. |
| `limit` | number | No | Maximum names to return (default: 100, max: 500). |
## background\_tasks -- Long-Running Task Queue
The `background_tasks` tool lets agents inspect and manage the daemon's durable queue for eligible long-running tool calls that were automatically promoted out of a foreground turn. Spawned sub-agents use the `subagents` tool, while execution graphs use `pipeline`.
| Action | Description |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `list` | List this conversation's background tasks with status and timestamps |
| `get` | Get status metadata for a single task by ID |
| `cancel` | Cancel a running task |
| `read_output` | Wait for a running promoted tool call and return its terminal output for acknowledgement after successful session journaling |
Use `background_tasks` to inspect a promoted tool call, consume its eventual
result with one `read_output` call, or cancel a runaway job. Do not poll
`read_output`: when the task is still live, the call waits on the original
execution and emits bounded progress heartbeats so prompt stall detection does
not mistake a healthy long-running wait for an unresponsive turn. A successful
`read_output` is acknowledged only after its tool result crosses the session
journal boundary at turn end. If the journal or protected consumption receipt
cannot be persisted, the pending result remains eligible for continuation
delivery; an existing delivery owner remains authoritative.
The tool is conversation-scoped rather than admin-gated. Every action requires
an active request context matching both the owning agent and the exact
originating conversation; tasks owned by another conversation are not exposed.
## mcp\_manage -- MCP Server Lifecycle
The `mcp_manage` tool controls connections to external Model Context Protocol (MCP) servers. It is also referenced in the [Supervisor](#supervisor-tools) section below; conceptually it sits in both buckets because MCP servers are infrastructure (the daemon's external tool surface) but management is admin-trust gated.
| Action | Description |
| ------------ | ----------------------------------------------------------------------------------------------------------- |
| `list` | List configured MCP servers with their transport (stdio / SSE / HTTP), URL/command, and enabled flag |
| `status` | Per-server connection status (connected / connecting / disconnected / error) and last health check |
| `connect` | Open a connection to a configured server (also discovers tools and qualifies them as `mcp:{server}/{tool}`) |
| `disconnect` | Close the connection without removing the server config |
| `reconnect` | Tear down and re-establish the connection (use this when an SSE transport gets wedged) |
Tools discovered from MCP servers are subject to the same [tool policy](/skills/tool-policy) as built-in tools -- per-agent allow/deny lists, group expansion, and the standard `applyToolPolicy` filtering all apply.
## Supervisor Tools
Supervisor tools are admin-level capabilities for managing the entire Comis installation. They require the `supervisor` tool policy profile or an explicit `allow` list in your agent's configuration, **and** the turn must carry **admin trust** — they are admin-scoped (deny-by-origin), so an agent serving a non-admin user is rejected at the dispatch chokepoint. Grant admin trust to a specific operator via [`elevatedReply.senderTrustMap`](/reference/config-yaml) (`"": admin`); a turn for that user inherits admin and the agent can run these tools on their behalf.
Supervisor tools can make significant changes to your system. They are intended for administration agents and admin-trust operators, not regular conversation agents — a non-admin turn can never reach them.
| Tool | Actions | What It Manages |
| ------------------ | -------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `agents_manage` | create, get, update, delete, suspend, resume | Agent system -- create new agents, modify settings, suspend or resume them |
| `obs_query` | diagnostics, billing, delivery, channels | Observability -- system diagnostics, cost tracking, and delivery metrics |
| `sessions_manage` | delete, reset, export, compact | Session lifecycle -- clean up, export, and compact conversation data |
| `memory_manage` | stats, browse, delete, flush, export, pin, unpin | Memory lifecycle -- view stats, browse entries, clean up memory, pin/unpin always-inject entries |
| `channels_manage` | list, get, enable, disable, restart, configure | Channel adapters -- manage connected chat platforms |
| `tokens_manage` | list, create, revoke, rotate | Gateway tokens -- manage API authentication tokens |
| `models_manage` | list, test | Model catalog -- view available models and test connections |
| `skills_manage` | list, import, delete | Skill lifecycle -- manage custom skills |
| `providers_manage` | list, get, create, update, delete, enable, disable | LLM provider endpoints -- register and manage custom model providers |
| `mcp_manage` | list, status, connect, disconnect, reconnect | MCP connections -- manage external tool servers |
### Supervisor Tool Details
Create, configure, suspend, and remove agents in your Comis installation. Each action targets a specific agent by ID. Create and delete operations take effect immediately without a daemon restart -- the new agent is routable within seconds. Update operations still require a daemon restart to apply configuration changes.
**Actions:**
* **create** -- Create a new agent with a specified configuration
* **get** -- Retrieve an agent's current settings
* **update** -- Modify an agent's configuration (model, provider, system prompt, etc.)
* **delete** -- Permanently remove an agent
* **suspend** -- Temporarily disable an agent (stops responding to messages)
* **resume** -- Re-enable a suspended agent
When creating a new agent, customize its workspace files after creation -- write ROLE.md for role-specific behavior, TOOLS.md for environment details, and IDENTITY.md for the agent's name and character. AGENTS.md and SOUL.md are read-only platform files.
Query system diagnostics, cost tracking, message delivery metrics, and channel health.
**Actions:**
* **diagnostics** -- System health overview (memory usage, uptime, error rates)
* **billing** -- AI provider cost tracking and budget usage
* **delivery** -- Message delivery success rates and latency
* **channels** -- Per-channel health and connection status
Manage conversation sessions across all agents and channels.
**Actions:**
* **delete** -- Permanently remove a session and its history
* **reset** -- Clear a session's conversation history while keeping the session active
* **export** -- Export a session's conversation data
* **compact** -- Compress a session's history to reduce storage
Every action requires `tenant_id`, `agent_id`, and the opaque
`conversation_ref` returned by `sessions_list`.
Manage the agent memory system, including stored knowledge and conversation summaries.
**Actions:**
* **stats** -- View memory usage statistics (entry count, storage size, index health)
* **browse** -- Browse stored memory entries with filters
* **delete** -- Remove specific memory entries
* **flush** -- Clear all memory for an agent
* **export** -- Export memory entries for backup or analysis
Control the chat platform connections (Discord, Telegram, Slack, etc.).
**Actions:**
* **list** -- List all configured channels and their status
* **get** -- Get detailed information about a specific channel
* **enable** -- Enable a disabled channel
* **disable** -- Disable a channel without removing its configuration
* **restart** -- Restart a channel's connection
* **configure** -- Update a channel's configuration
Manage the API tokens used to authenticate with the Comis gateway.
**Actions:**
* **list** -- List all active tokens
* **create** -- Generate a new authentication token
* **revoke** -- Revoke an existing token
* **rotate** -- Replace a token with a new one (revokes the old token and creates a new one)
Query and test the AI models available to your Comis installation.
**Actions:**
* **list** -- List all configured models with their providers and capabilities
* **test** -- Test a model connection by sending a simple prompt
Manage custom skills with per-agent scope control.
**Actions:**
* **list** -- List all discovered skills with their status and metadata
* **import** -- Import a skill from a file or URL
* **delete** -- Remove a custom skill
All mutation actions (import, delete) accept an optional **scope** parameter:
* `"local"` (default) -- operates on the calling agent's workspace skills directory
* `"shared"` -- operates on the global skills directory (default agent only)
The scope defaults to `"local"`, so an agent's skill mutations are isolated to its own workspace unless explicitly targeting the shared directory.
**Admin required.** Manage custom LLM provider endpoints.
**Actions:**
* **list** -- View all configured providers (name, type, status, model count)
* **get** -- Read full provider configuration for a specific provider
* **create** -- Register a new provider (requires approval)
* **update** -- Modify an existing provider's configuration
* **delete** -- Remove a provider (requires approval, blocked if agents reference it)
* **enable** -- Activate a disabled provider
* **disable** -- Deactivate a provider (warns if agents reference it)
**Parameters:**
| Parameter | Type | Required | Description |
| ------------- | ------ | ------------------- | ---------------------------------------------------------- |
| `action` | string | Yes | One of: list, get, create, update, delete, enable, disable |
| `provider_id` | string | For all except list | Provider identifier (e.g., "nvidia", "deepseek") |
| `config` | object | For create/update | Provider configuration (type, baseUrl, apiKeyName, models) |
**Example -- Cloud provider (NVIDIA NIM):**
```json theme={}
// Step 1: Store the API key
gateway({ action: "env_set", env_key: "NVIDIA_API_KEY", env_value: "nvapi-..." })
// Step 2: Create the provider (minimal -- only id required in models)
providers_manage({
action: "create",
provider_id: "nvidia",
config: {
type: "openai",
name: "NVIDIA NIM",
baseUrl: "https://integrate.api.nvidia.com/v1",
apiKeyName: "NVIDIA_API_KEY",
models: [{ id: "moonshotai/kimi-k2.5" }]
}
})
// Step 3: Switch agent to use the new provider
agents_manage({ action: "update", agent_id: "default", config: { provider: "nvidia", model: "moonshotai/kimi-k2.5" } })
```
**Example -- Local inference server (Ollama, no API key needed):**
```json theme={}
providers_manage({
action: "create",
provider_id: "local-ollama",
config: {
type: "ollama",
name: "Local Ollama",
baseUrl: "http://localhost:11434",
models: [{ id: "llama3.3" }, { id: "qwen3:32b" }, { id: "deepseek-r1:14b" }]
}
})
```
**Example -- Multi-model cloud provider (DeepSeek):**
```json theme={}
providers_manage({
action: "create",
provider_id: "deepseek",
config: {
type: "openai",
baseUrl: "https://api.deepseek.com/v1",
apiKeyName: "DEEPSEEK_API_KEY",
models: [{ id: "deepseek-chat" }, { id: "deepseek-reasoner" }]
}
})
```
**Example -- Self-hosted vLLM / LM Studio endpoint:**
```json theme={}
providers_manage({
action: "create",
provider_id: "my-vllm",
config: {
type: "openai",
name: "Self-hosted vLLM",
baseUrl: "http://gpu-server:8000/v1",
models: [{ id: "meta-llama/Llama-3.3-70B-Instruct" }]
}
})
```
**Example -- Multi-provider gateway (OpenRouter):**
```json theme={}
providers_manage({
action: "create",
provider_id: "openrouter",
config: {
type: "openrouter",
name: "OpenRouter",
baseUrl: "https://openrouter.ai/api/v1",
apiKeyName: "OPENROUTER_API_KEY",
models: [{ id: "google/gemini-2.5-flash" }, { id: "anthropic/claude-sonnet-4" }]
}
})
```
**Example -- Rich model entry (with optional metadata):**
```json theme={}
providers_manage({
action: "update",
provider_id: "nvidia",
config: {
models: [{
id: "moonshotai/kimi-k2.5",
name: "Kimi K2.5",
reasoning: true,
contextWindow: 262144,
maxTokens: 16384,
input: ["text", "image"]
}]
}
})
```
API keys are never stored in provider config. Always store keys via `gateway env_set` first,
then reference the key name in `apiKeyName`. The provider config only holds the key name,
not the value.
Configure automatic model failover on any agent via `agents_manage update`. When the primary model fails, the agent automatically tries fallback models in order.
**Failover pipeline:**
1. Primary model attempt (with resettable timeout)
2. Cache-aware short retry on 429/529 (preserves prompt cache)
3. Auth key rotation if `authProfiles` configured (same provider, different key)
4. Ordered fallback model loop (different provider + model)
5. Exhaustion event if all attempts fail
**Example -- basic fallback chain:**
```json theme={}
agents_manage({
action: "update",
agent_id: "default",
config: {
modelFailover: {
fallbackModels: [
{ provider: "deepseek", modelId: "deepseek-chat" },
{ provider: "local-ollama", modelId: "llama3.3" }
]
}
}
})
```
**Example -- auth key rotation for rate limits:**
```json theme={}
// Step 1: Store backup API key
gateway({ action: "env_set", env_key: "ANTHROPIC_API_KEY_2", env_value: "sk-ant-..." })
// Step 2: Configure rotation
agents_manage({
action: "update",
agent_id: "default",
config: {
modelFailover: {
authProfiles: [
{ keyName: "ANTHROPIC_API_KEY_2", provider: "anthropic" }
]
}
}
})
```
**Example -- full resilience (fallback + auth rotation + custom cooldown):**
```json theme={}
agents_manage({
action: "update",
agent_id: "default",
config: {
modelFailover: {
fallbackModels: [
{ provider: "deepseek", modelId: "deepseek-chat" },
{ provider: "local-ollama", modelId: "llama3.3" }
],
authProfiles: [
{ keyName: "NVIDIA_API_KEY_2", provider: "nvidia" }
],
maxAttempts: 8,
cooldownInitialMs: 30000,
cooldownMultiplier: 3,
cooldownCapMs: 1800000
}
}
})
```
Each fallback model must reference a provider that has been created via `providers_manage`.
If a referenced provider does not exist or is disabled, that fallback step is skipped.
`fallbackModels` and `authProfiles` are replaced wholesale on update -- the array you send
becomes the complete new state. To **add** a fallback (not replace the chain), first call
`agents_manage get` to read the existing array, append the new entry, then call
`agents_manage update` with the full list. Scalar fields (cooldownInitialMs, maxAttempts)
are preserved across partial updates via a top-level merge inside the handler.
Manage connections to external Model Context Protocol (MCP) servers that provide additional tools.
**Actions:**
* **list** -- List all configured MCP servers
* **status** -- Check the connection status of MCP servers
* **connect** -- Establish a connection to an MCP server
* **disconnect** -- Disconnect from an MCP server
* **reconnect** -- Restart the connection to an MCP server
## Related
Complete configuration reference for all settings
How the approval workflow protects sensitive operations
See all available agent tools
Control which tools your agents can use