Skip to main content

​
Connector configuration

Connector settings can come from two places:
  • a TOML file passed to --connectors-config
  • the daemon-managed runtime connector store
This page covers the shared connector config model and the file-backed TOML shape.

​
Top-level structure

[[http_connectors]]
name = "webhook"

[[slack_connectors]]
name = "support"

[[telegram_connectors]]
name = "bot"

[[external_connectors]]
name = "discord-main"

​
HTTP connectors

HTTP connectors support:
  • name
  • fixed_session_id
  • actor_id
  • bearer_token, bearer_token_env, or bearer_token_secret_ref
  • allow_unauthenticated_ingress
  • default_reply_targets
  • default_binding_keys
  • session_policy
They are intended for generic webhook ingress and can derive fallback sessions from binding keys when needed.

​
Slack connectors

Slack connectors support:
  • name
  • bot_token, bot_token_env, or bot_token_secret_ref
  • signing_secret, signing_secret_env, or signing_secret_secret_ref
  • allow_unauthenticated_ingress
  • api_base_url
  • fixed_session_id
  • include_self_output
  • additional_reply_targets
  • additional_binding_keys
  • session_policy
Slack sessions can be derived from channel and thread context when a fixed session ID is not configured.

​
Telegram connectors

Telegram connectors support:
  • name
  • bot_token, bot_token_env, or bot_token_secret_ref
  • secret_token, secret_token_env, or secret_token_secret_ref
  • allow_unauthenticated_ingress
  • api_base_url
  • ingress_mode
  • polling_timeout_seconds
  • fixed_session_id
  • include_self_output
  • additional_reply_targets
  • additional_binding_keys
  • session_policy
ingress_mode can be webhook or polling. Polling requires a bot token.

​
External connectors

External connectors support:
  • name
  • platform
  • mode
  • base_url
  • shared_token, shared_token_env, or shared_token_secret_ref
  • allow_unauthenticated_ingress
  • fixed_session_id
  • include_self_output
  • additional_reply_targets
  • additional_binding_keys
  • session_policy
  • ingress_events_per_second
  • child_process
mode can be:
  • remote_http
  • child_process
child_process supports:
  • command
  • args
  • env
  • credential_slots
  • working_dir
Example: 
[[external_connectors]]
name = "discord-main"
platform = "discord"
mode = "child_process"
base_url = "http://127.0.0.1:8787"
shared_token_secret_ref = "connectors.external.discord-main.shared_token"
include_self_output = true
ingress_events_per_second = 100

[external_connectors.session_policy]
create_if_missing = true
credential_scope.route_allow = ["openai"]

[external_connectors.child_process]
command = "python3"
args = ["connectors/python/run_connector.py", "discord"]

[external_connectors.child_process.env]
DISCORD_REQUIRE_MENTION = "true"
Guidance:
  • use fixed_session_id when every inbound event should land in one known session
  • otherwise let the sidecar derive sessions from thread.path or routing_key
  • use credential_slots when the sidecar needs platform secrets without inheriting the daemon environment; the daemon now serves those slots through short-lived brokered leases rather than long-lived env injection
  • keep base_url loopback-only for child_process connectors

​
Secret-source precedence

For each connector secret field, the runtime resolves sources in this order:
  1. secret-store reference
  2. environment variable reference
  3. inline value
For daemon-managed connectors, the runtime control plane can also accept a write-only secret value, store it into the secret store, and keep the connector bound to the resulting secret_ref.

​
Runtime-managed connectors

Daemon-managed connectors use the same underlying config fields as file-backed connectors, but they are persisted under the daemon state root instead of one external TOML file. session_policy supports:
  • create_if_missing
  • persona_id
  • capability_scope
  • credential_scope
Use the runtime connector API when you want to:
  • create or replace one connector through HTTP or CLI
  • rotate a connector secret through the secret store
  • inspect the currently active connector inventory without reading files directly
For external connectors, also read External connectors protocol for the ingress and delivery contract.

​
Reply routing

Connector configuration is not only about ingress. It also shapes output routing through self-output behavior and additional reply targets, which are turned into normalized reply handles for the output pipeline.