synadia-ai/synadia-agents/configure

/nats-channel:configure - NATS Channel Configuration

Configures the NATS channel plugin: connection context, session name, sender identity, inbound sender trust, and permission handling. State lives in ~/.claude/channels/nats/config.json.

Arguments passed: $ARGUMENTS

Dispatch on arguments

No args - status, list, and offer to change

Read state and give the user a complete picture, then ask:

1. Current config - read ~/.claude/channels/nats/config.json. Show:

• Selected context name (or "none - using demo.nats.io")
• Owner override (if set)
• Session name override (if set)
• Sender identity mode (off or signed; default off)
• Minimum sender trust (any or signed; default any)
• Connection URL and description from the context file
• Permission mode (terminal or query) and whether permission prompts

will be relayed as NATS query chunks or handled in the local terminal

1. Available contexts - run the list-contexts.sh script bundled

alongside this skill file to list all NATS CLI contexts with their URL and description.

1. Ask the user - show the numbered list of available contexts and

ask if they'd like to switch. Example:

• "Currently using `<name>`. Available contexts:"
• (numbered list)
• *"Would you like to switch? Enter a context name or number, or

'no' to keep the current selection."* If no config is set, skip straight to asking them to pick one.

list - list available NATS contexts

Two separate steps - do NOT combine into one Bash call:

1. Bash: run the list-contexts.sh script bundled alongside this skill

file. It produces no stdout - it writes to a file.

1. Read: open ~/.claude/channels/nats/.contexts and present the

markdown table to the user.

<context-name> - select a context

1. Treat $ARGUMENTS as the context name (trim whitespace).
2. Verify ~/.config/nats/context/<name>.json exists. If not, show

available contexts and error.

1. Read the context file. Show the URL and description so the user can

confirm it's correct.

1. mkdir -p ~/.claude/channels/nats
2. Read existing config.json if present; update/add the context field,

preserve other fields (like sessionName, permissions). Write back.

1. Confirm, then show the status view so the user sees where they stand.

session <name> - set session name override

1. The session name is the 5th token in the v0.3 verb-first subject

agents.prompt.cc.<owner>.<name>. It defaults to the working directory basename. This command overrides it.

1. Read existing config.json (or start fresh). Set sessionName field.

Write back.

1. Confirm the override.

session clear - remove session name override

Remove the sessionName field from config.json so the default (CWD basename) is used.

owner <name> - set owner override

1. The owner is the 4th token in the v0.3 verb-first subject

agents.prompt.cc.<owner>.<name>. It defaults to the sanitized $USER. This command overrides it — useful for service accounts or deployment-scoped owners.

1. Read existing config.json (or start fresh). Set the owner field.

Write back.

1. Confirm the override. Note: the SYNADIA_CLAUDE_CODE_OWNER and

SYNADIA_OWNER env vars take precedence over this config field.

owner clear - remove owner override

Remove the owner field from config.json so the default (sanitized $USER) is used.

identity off - disable host identity

Set senderIdentity to "off". The channel performs no host identity lookup and registers no identity metadata. This is the default and works with token/password authentication and servers where user-info lookup is not permitted. It does not change inbound sender policy.

identity signed - use the connection identity

Set senderIdentity to "signed". The selected NATS context must contain a user seed (creds, nkey, or user_jwt plus user_seed). The same immutable credential snapshot supplies both connection authentication and signing; never ask for or add a second identity credential. Signed startup fails rather than downgrading when the connection cannot be bound to that signer.

NATS_SENDER_IDENTITY overrides this config field. A plugin reload or Claude Code restart is required after changing it.

trust any - accept all sender trust classes

Set minSenderTrust to "any". Headerless, claimed, and verified prompts are admitted. This is the backward-compatible default and is independent of the channel's own identity.

trust signed - require verified senders

Set minSenderTrust to "signed". Headerless, claimed, malformed, stale, and replayed requests are rejected before an acknowledgement and before Claude sees the prompt. NATS_MIN_SENDER_TRUST overrides this config field.

permissions terminal - use terminal for permission prompts

Set permissions.mode to terminal. Permission prompts will appear in the Claude Code terminal session. This is the simplest option when the operator has direct terminal access, and the default when no permissions block is set.

1. Read existing config.json (or start fresh).
2. Set permissions to { "mode": "terminal" }.
3. Write back and confirm.

permissions query - relay permissions as query chunks

Set permissions.mode to query. When Claude needs permission to use a tool during an active NATS prompt, the plugin emits a protocol query chunk (§7 of the Synadia Agent Protocol for NATS) on the active stream's reply subject. The caller replies with yes/no on the query's dynamic reply inbox, and the plugin forwards the decision back to the Claude Code harness. The legacy value "nats" is accepted as an alias for backward compatibility.

If Claude asks for permission while no NATS request is active, the request is denied (there is no open stream to carry a query chunk on). Operators who need terminal-style prompting in that case should use permissions terminal instead.

1. Read existing config.json (or start fresh).
2. Set permissions to { "mode": "query" }.
3. Write back and confirm.

permissions clear - reset to default

Remove the permissions field from config.json, restoring the default behavior (terminal-mode prompts).

clear - remove config

Delete ~/.claude/channels/nats/config.json.

Implementation notes

• The channels dir might not exist if the server hasn't run yet. Missing

file = not configured, not an error.

• The server reads config.json once at boot. Config changes need a

session restart or /reload-plugins. Say so after saving.

• NATS CLI contexts live in ~/.config/nats/context/<name>.json. Each

file contains url, description, creds, nkey, user, password, token, cert, key, ca, and other fields.

• Do not modify NATS CLI context files - only read them.
• senderIdentity and minSenderTrust are independent. Do not enable strict

inbound policy merely because signed host identity was enabled.

• Legacy configs with "mode": "nats" are still accepted and treated as

the new "query" mode; they do not need to be rewritten.

• Legacy configs with permissions.subject are silently ignored - query

chunks use a dynamic reply inbox per request, not a fixed subject.