Infrastructure

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, 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 ("<senderId>": 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 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, 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

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. The session_key is optional for this action: omit it (or pass "self") to compact your own current session — you do not need to construct or guess your session key (delete/reset/export still require an explicit key).

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:

Primary model attempt (with resettable timeout)
Cache-aware short retry on 429/529 (preserves prompt cache)
Auth key rotation if authProfiles configured (same provider, different key)
Ordered fallback model loop (different provider + model)
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

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

Overview

Tool Guides

Platform Actions

Infrastructure

gateway — Configuration and Control

Gateway Actions

background_tasks — Long-Running Task Queue

mcp_manage — MCP Server Lifecycle

Supervisor Tools

Supervisor Tool Details

Config Reference

Security Approvals

Agent Tools Overview

Tool Policy

​gateway — Configuration and Control

​Gateway Actions

​background_tasks — Long-Running Task Queue

​mcp_manage — MCP Server Lifecycle

​Supervisor Tools

​Supervisor Tool Details

​Related

Config Reference

Security Approvals

Agent Tools Overview

Tool Policy

gateway — Configuration and Control

Gateway Actions

background_tasks — Long-Running Task Queue

mcp_manage — MCP Server Lifecycle

Supervisor Tools

Supervisor Tool Details

Related