Gateway¶

The gateway is SecondBrain's persistent runtime surface for channel-backed sessions, approvals, and outbound delivery state.

Purpose¶

run a long-lived gateway service over configured channels
inspect approval lifecycle and outbound queue state
diagnose runtime, identity, and event-log issues

Current CLI Surface¶

sb gateway init
sb gateway run
sb gateway doctor
sb gateway config-summary
sb gateway approvals
sb gateway identity
sb gateway outbound
sb gateway events

Use sb gateway --help and subcommand help for exact options.

Typical Operator Flow¶

1. Scaffold config¶

sb gateway init

2. Start the service¶

sb gateway run

3. Check health and effective config¶

sb gateway doctor
sb gateway config-summary

4. Inspect runtime state¶

sb gateway approvals
sb gateway outbound
sb gateway events
sb gateway identity

Teams Channel¶

Conversational Microsoft Teams traffic uses the same gateway channel runtime as other inbound surfaces. Configure the channel in ~/.secondbrain/gateway.yaml:

channels:
  teams:
    enabled: true
    host: 127.0.0.1
    port: 3978
    path: /api/messages
    auth_mode: token
    auth_token: local-dev-token

Expose that path through Azure Bot Service or a trusted tunnel, then run:

sb teams bot-status
sb gateway run

The Teams channel adapter normalizes Bot Framework Activity payloads into gateway MessageEnvelope objects, so session routing, approvals, lanes, and runtime events stay shared with the rest of SecondBrain. It stores conversation references from inbound turns, and gateway outbound delivery can reuse those references for proactive Teams sends when TEAMS_BOT_APP_ID and TEAMS_BOT_APP_PASSWORD are configured.

What The Gateway Owns¶

persistent channel/session runtime
approval lifecycle operations
outbound queue inspection and retry flows
identity linking between external peers and internal people/session scopes
typed session-event inspection

Implementation Pointers¶

brain/gateway/
brain/cli/gateway.py