Skip to content
DuckAgent

Gateway Overview

Gateway lets external chat surfaces send messages into DuckAgent and receive responses from the same Agent Loop used by the TUI. It is profile-scoped, configuration-driven, and shares session-control commands with the terminal UI.

What Gateway provides

Section titled “What Gateway provides”
AreaBehavior
Channel adaptersEach platform has a dedicated adapter under src/gateway/channels/.
Shared dispatchPolling, websocket, callback, and bridge-backed adapters submit inbound messages through the same gateway path.
Session routingSessions are keyed by channel, conversation, and thread so multiple platforms do not collide.
Media handoffAttachments are copied through gateway attachment storage and staged under $TMPDIR for tool use.
ApprovalsNative buttons or cards are used when possible; text fallback uses /approve and /deny.
Service lifecycleduck gateway service start, log, and stop manage the profile gateway service.

Gateway state

Section titled “Gateway state”

Gateway runtime state belongs to the active profile:

~/.duckagent/profiles/<name>/gateway/
  state/
  attachments/
  service/

Gateway does not use cache/ for durable routing state. Cache should remain disposable.

User flow

Section titled “User flow”
  1. Run duck gateway channels to inspect available channels.
  2. Configure a channel through guided setup or profile config.
  3. Start the service with duck gateway service start.
  4. Watch newly routed messages with duck gateway service log.
  5. Stop the service with duck gateway service stop.

When channel config is missing, service start should guide the user into setup instead of requiring raw bind or channel flags.

Use Configure Channels for field defaults, auth.json boundaries, stable bind behavior, and manual config examples.

Shared session commands

Section titled “Shared session commands”

Gateway channels share these commands with the TUI:

/new
/resume
/resume <number>
/rewind
/rewind <number>

These commands append routing changes instead of editing old session files.

/rewind <number> also shares the TUI’s tracked file restore behavior for files changed through built-in file mutation capabilities. See Session Rewind for the checksum guard and limits.