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 fleet.

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 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 -- Read configuration values

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.

patch -- Update a configuration value

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.

apply -- Save and reload configuration

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 -- Restart the daemon

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.

schema -- View configuration schema

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)

status -- Check system health

Check the health status of the daemon and gateway, including uptime, connected channels, and resource usage.

Parameter	Type	Required	Description
action	string	Yes	"status"

history -- View recent config changes

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)

diff -- Compare config versions

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.

rollback -- Revert to a previous config

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.

env_set -- Set an environment variable

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.

env_list -- List configured secret names

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 background task queue — the in-flight execution surface for spawned sub-agents, async pipelines, and long-running tool calls.

Action	Description
list	List active background tasks with status, age, and task type
get	Get full state of a single task by ID
cancel	Cancel a running task (destructive; requires _confirmed)
read_output	Tail recent stdout/stderr output for a task

Use background_tasks to triage a stuck async sub-agent, peek at incremental output without waiting for completion, or kill a runaway job. Permissions are gated to admin-trust agents because cancellation can affect other users’ work.

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 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 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.

Supervisor tools can make significant changes to your system. They are intended for administration agents with elevated privileges, not regular conversation agents.

Tool	Actions	What It Manages
agents_manage	create, get, update, delete, suspend, resume	Agent fleet — 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	Memory lifecycle — view stats, browse entries, and clean up memory
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

agents_manage -- Agent fleet management

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.

obs_query -- Observability and metrics

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

sessions_manage -- Session lifecycle

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

memory_manage -- Memory lifecycle

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

channels_manage -- Channel adapter management

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

tokens_manage -- Gateway token management

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)

models_manage -- Model catalog

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

skills_manage -- Skill lifecycle

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.

providers_manage -- LLM provider management

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):

// 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):

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):

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:

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):

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):

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.

Model failover -- automatic recovery from provider outages

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:

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:

// 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):

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.

mcp_manage -- MCP server management

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

Config Reference

Complete configuration reference for all settings

Security Approvals

How the approval workflow protects sensitive operations

Agent Tools Overview

See all available agent tools

Tool Policy

Control which tools your agents can use