synapse

name	synapse
description	Use when the user needs to inspect or manage Synapse-managed Docker/Compose infrastructure via flux, or SSH/local host files, processes, logs, ZFS, and allowlisted commands via scout. Prefer MCP tools first, CLI second, REST last; use write or confirmation-gated actions only when explicitly requested or necessary.

synapse

Two MCP tools: flux for Docker/host inspection, scout for SSH/local host operations. Start with read-only inspection. Use write-scope or confirmation-gated actions only when explicitly requested or clearly necessary.

Use these tools before falling back to direct SSH or Docker API calls.

Quick Action Table

Tool	Action	Key Params	Use When
flux	docker, info	host?	Check Docker availability / host info
flux	docker, df	host?	Check Docker disk usage
flux	docker, images	host?, dangling_only?	List Docker images
flux	docker, networks	host?	List Docker networks
flux	docker, volumes	host?	List Docker volumes
flux	docker, pull	host, image	Pull a Docker image
flux	docker, build	host, context, tag	Build a Docker image
flux	docker, rmi	host, image, force=true	Remove a Docker image
flux	docker, prune	host, prune_target, force=true	Remove unused resources
flux	container, list	host?, state?, name_filter?	List containers
flux	container, inspect	container_id, summary?	Inspect a container
flux	container, logs	container_id, lines?, grep?	Read container logs
flux	container, stats	container_id?	CPU/mem/network stats
flux	container, top	container_id	Show running processes
flux	container, search	query	Search containers by name/image/label
flux	container, start	container_id	Start a stopped container
flux	container, stop	container_id	Stop a container (destructive)
flux	container, restart	container_id	Restart a container
flux	container, pause	container_id	Pause a container
flux	container, resume	container_id	Resume a paused container
flux	container, pull	container_id	Pull container's image
flux	container, recreate	container_id, pull?	Recreate with image pull (destructive)
flux	container, exec	container_id, command (array)	Run command in container (destructive)
flux	host, status	host?	Check Docker connectivity
flux	host, info	host?	OS/kernel/arch info
flux	host, uptime	host?	System uptime
flux	host, resources	host?	CPU/mem/disk usage
flux	host, services	host, state?, service?	Systemd service status
flux	host, network	host?	Network interfaces
flux	host, mounts	host	Mounted filesystems
flux	host, ports	host, protocol?, limit?	Port mappings
flux	host, doctor	host, checks?	Run diagnostic checks
flux	compose, list	host	List Compose projects
flux	compose, status	host, project, service?	Compose project status
flux	compose, up	host, project	Start a Compose project
flux	compose, down	host, project	Stop a Compose project (destructive)
flux	compose, restart	host, project	Restart a Compose project (destructive)
flux	compose, recreate	host, project	Recreate Compose containers (destructive)
flux	compose, logs	host, project, lines?, service?	Compose project logs
flux	compose, build	host, project, service?	Build Compose images
flux	compose, pull	host, project, service?	Pull Compose images
flux	compose, refresh	host	Refresh compose project cache
flux	help	topic?, format?	Flux documentation
scout	nodes	—	List all configured SSH hosts
scout	peek	host, path, tree?, depth?	Read file or directory
scout	find	host, path, pattern	Find files by glob
scout	ps	host, sort?, grep?, user?	List processes
scout	df	host, path?	Disk usage
scout	delta	source_host, source_path, ...	Compare files/content
scout	exec	host, command	Run allowlisted command (destructive)
scout	emit	targets, command	Multi-host command (destructive)
scout	beam	source_host, source_path, dest_host, dest_path	File transfer (destructive)
scout	zfs, pools	host, pool?	List ZFS pools
scout	zfs, datasets	host, pool?, dataset_type?, recursive?	List ZFS datasets
scout	zfs, snapshots	host, pool?, dataset?, limit?	List ZFS snapshots
scout	logs, syslog	host, lines?, grep?	Read syslog
scout	logs, journal	host, unit?, priority?, since?, until?	Read systemd journal
scout	logs, dmesg	host, grep?	Read kernel ring buffer
scout	logs, auth	host, lines?, grep?	Read auth log
scout	help	topic?, format?	Scout documentation

For the full parameter table, use references/action-reference.md in this skill package or the live MCP help topics (flux(action="help"), scout(action="help")).

Critical Gotchas

• Read ops fan out across all configured hosts when host is omitted; destructive ops always require an explicit host.
• container exec vs scout exec: container exec runs inside a Docker container (literal argv array, so --command sh -c "..." is valid when you explicitly want a shell inside the container); scout exec runs on the host via SSH (allowlisted commands only, no shell).
• scout exec has typed command policies for: cat, head, tail, grep, rg, ls, tree, wc, uniq, diff, stat, file, du, df, pwd, hostname, uptime, whoami. git is explicitly denied. Per-host custom commands are zero-argument only; use the dedicated scout find action for filesystem search.
• scout beam is bounded and root-confined — both endpoints must be under configured Scout/Compose roots; sensitive/symlinked paths are rejected and one transfer is capped at 64 MiB.
• For scout exec, never pass shell metacharacters (|, >, &&, ..); host command execution is execvp-style and does not run through sh -c.
• Destructive ops need confirmation via the MCP elicitation gate; declining returns an error without performing any IO. SYNAPSE_MCP_ALLOW_DESTRUCTIVE defaults to false. If enabled on a non-loopback bind, startup refuses to run.
• Responses are token-budgeted — very long log tails or large directory trees may be truncated. Use lines/limit/depth params to control size.

Safety Matrix

Action family	Write scope	Confirmation gated	Operator risk
flux docker info/df/images/networks/volumes	no	no	Read-only Docker inventory.
flux docker pull	yes	no	Downloads an image; can consume bandwidth/disk.
flux docker build/rmi/prune	yes	yes	Builds, removes, or prunes Docker resources.
flux container list/inspect/logs/stats/top/search	no	no	Read-only container inspection.
flux container start/restart/pause/resume/pull	yes	no	Changes container runtime state or image cache.
flux container stop/recreate/exec	yes	yes	Stops/replaces containers or executes inside them.
flux host status/info/uptime/resources/services/network/mounts/ports/doctor	no	no	Read-only host diagnostics.
flux compose list/status/logs	no	no	Read-only Compose inspection.
flux compose up/build/pull	yes	no	Starts services or changes image/build state.
flux compose down/restart/recreate	yes	yes	Stops, restarts, or replaces services.
scout nodes/peek/find/ps/df/delta/zfs/logs	no	no	Read-only SSH/local inspection.
scout exec/emit/beam	yes	yes	Host command execution or file transfer.

Response Shapes

Representative response keys:

{"hosts":[{"name":"local","protocol":"local"}]}
{"containers":[{"host":"local","id":"...","name":"..."}],"partial":false}
{"tool":"flux","topics":["container:list"],"actions":{"docker":["info"]}}

---

Common Workflows

Use neutral tool-call examples in shared skill docs: flux(action="...", subaction="...") and scout(action="..."). Codex may expose these as mcp__synapse__flux and mcp__synapse__scout.

Investigate a host's Docker stack

# 1. Check connectivity
flux(action="host", subaction="status", host="myhost")

# 2. List running containers
flux(action="container", subaction="list", host="myhost", state="running")

# 3. Inspect a container
flux(action="container", subaction="inspect", host="myhost", container_id="abc123")

# 4. Read recent logs
flux(action="container", subaction="logs", host="myhost", container_id="abc123", lines=100, grep="ERROR")

# 5. Check overall disk usage
flux(action="docker", subaction="df", host="myhost")

Diagnose a failing Compose stack

# 1. List all compose projects
flux(action="compose", subaction="list", host="myhost")

# 2. Get project status
flux(action="compose", subaction="status", host="myhost", project="mystack")

# 3. Read logs
flux(action="compose", subaction="logs", host="myhost", project="mystack", lines=200)

# 4. Inspect resource pressure before mutating anything
flux(action="host", subaction="resources", host="myhost")

# 5. Only if explicitly approved: restart the stack
flux(action="compose", subaction="restart", host="myhost", project="mystack")

Investigate a remote host via SSH

# 1. List all nodes
scout(action="nodes")

# 2. Check processes
scout(action="ps", host="myhost", sort="cpu", limit=20)

# 3. Read a config file
scout(action="peek", host="myhost", path="/etc/nginx/nginx.conf")

# 4. Read system logs
scout(action="logs", subaction="journal", host="myhost", since="-30m", priority="err")

Check ZFS pool health (Unraid / TrueNAS)

scout(action="zfs", subaction="pools", host="myhost")
scout(action="zfs", subaction="datasets", host="myhost", pool="tank")
scout(action="zfs", subaction="snapshots", host="myhost", dataset="tank/data")

Fallback Tiers

Tier 1: MCP tools

Use MCP first whenever the flux and scout tools are available.

scout(action="nodes")
flux(action="docker", subaction="info")

Tier 2: CLI binary

Use the synapse binary when MCP transport is unavailable but local shell access exists:

synapse scout nodes --response-format json
synapse flux docker info --response-format json
synapse doctor --json
synapse setup check

Tier 3: REST API

When the MCP transport is unavailable, use POST /v1/synapse with a bearer token:

curl -sX POST "http://${SYNAPSE_MCP_HOST:-127.0.0.1}:${SYNAPSE_MCP_PORT:-40080}/v1/synapse" \
  -H "Authorization: Bearer $SYNAPSE_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"flux.docker.info","params":{}}'

Error Handling

Error type	Cause	Recovery
invalid_params	Missing required param or unknown action/subaction	Check param names; use help action
invalid_request	Destructive op denied at confirmation gate	User declined; no state changed
unauthorized	Missing or bad bearer token / OAuth token	Check SYNAPSE_MCP_TOKEN, auth mode, and plugin settings
internal_error	Service error (Docker unavailable, SSH timeout)	Run diagnostics, check host connectivity, retry

Recovery commands:

flux(action="help")
scout(action="help")

synapse doctor --json
synapse setup check