NATS JetStream operations
v0.1.0Inspect authenticated NATS connectivity and JetStream account, stream and consumer state, then govern narrow topology, retention, delivery, leadership and deletion operations. Fixed API subjects and typed bodies expose no arbitrary request, publication, subscription, message payload read, server control or account administration.
nats
python3
Install
New to emisar? Follow the quickstart to connect your host and AI agent, then install this pack below. Agents can use its actions through the CLI or MCP.
emisar pack install
downloads and checks the pack, then compares its content hash with the
--hash
below before copying it into the runner's packs directory. The hash identifies
the exact pack shown on this page. If the download was changed, the command rejects
it. It also reloads a running runner, so you do not need to restart it yourself.
sudo emisar pack install nats --hash sha256:096e107379661d50010c66f3990291b9c9ae78f0413b6fd4b03137d7e5e04c1d
Setup
Install the native NATS CLI and Python 3 on the runner, provision dedicated read/admin username-password identities in the NATS server authorization.users configuration, and supply the TLS endpoint and public CA. The script chooses credentials from its fixed action mode; credentials enter only the native child environment and private configuration bodies use stdin, never argv.
Environment
Set these on the runner host, then add each name to
execution.inherit_env
so the value reaches the action.
-
NATS_URLrequiredOne to four comma-separated tls:// seed URLs, with no userinfo, path or query.
-
NATS_CArequiredReadable path to the public CA chain that verifies the NATS servers.
-
NATS_READ_USERrequiredDedicated metadata-reader username created in the NATS server user configuration.
-
NATS_READ_PASSWORDrequiredOriginal password for that reader from the deployment secret store; the server stores its bcrypt hash.
-
NATS_ADMIN_USERDedicated narrow JetStream-administrator username; required only for mutating actions.
-
NATS_ADMIN_PASSWORDOriginal administrator password from the deployment secret store; never reuse an application or unrestricted server-admin identity.
Notes
- NATS CLI 0.5.1 is tested; install its checksum-verified binary from official NATS CLI releases . Install Python 3 using the runner distribution package manager. The pack declares both prerequisites; installing a pack does not install native binaries.
- Create dedicated users in the NATS server authorization.users configuration with passwords managed by the deployment secret store and bcrypt hashes on the server. The runner needs the original passwords. Allowlist exactly NATS_URL, NATS_CA, NATS_READ_USER, NATS_READ_PASSWORD, NATS_ADMIN_USER and NATS_ADMIN_PASSWORD in execution.inherit_env. TLS verification is mandatory; existing CLI contexts, other native auth and proxy/TLS overrides are not inherited by the child.
-
Reader publish allowlist:
$JS.API.INFO,$JS.API.STREAM.NAMES,$JS.API.STREAM.INFO.*,$JS.API.CONSUMER.NAMES.*,$JS.API.CONSUMER.INFO.*.*. Subscribe only to_INBOX.emisar.read.>; the script fixes its inbox prefix to_INBOX.emisar.read. -
Administrator publish allowlist adds
$JS.API.STREAM.CREATE.*,$JS.API.STREAM.UPDATE.*,$JS.API.STREAM.LEADER.STEPDOWN.*,$JS.API.STREAM.MSG.DELETE.*,$JS.API.STREAM.PURGE.*,$JS.API.STREAM.DELETE.*,$JS.API.CONSUMER.CREATE.*.*,$JS.API.CONSUMER.PAUSE.*.*,$JS.API.CONSUMER.LEADER.STEPDOWN.*.*,$JS.API.CONSUMER.DELETE.*.*to the reader subjects. Subscribe only to_INBOX.emisar.admin.>. These grants cover all resource names admitted by each subject pattern. Direct application publication/subscription and$SYS.>are excluded, but the administrator configuration API can arrange indirect message delivery into its permitted inbox. Protect that credential as message-reading authority. The signed pack creates only pull consumers and has no message payload read, publish or subscribe action. - Python starts in isolated mode, ignoring user-site modules and PYTHON* startup variables. The CLI uses --no-context, a fixed inbox prefix, a five-second protocol timeout and request templates disabled. Empty output, unexpected response types, JSON API errors, false acknowledgements and invalid RTT results fail even if the CLI exits zero. Capture is limited to 4 MiB; child deadlines are eight seconds per RPC and 25 seconds for the connection check.
- Full int64/uint64 counters and capacities use decimal strings in results and relevant arguments to preserve precision. Names use subject-safe ASCII letters, digits, underscores and hyphens up to255bytes. Selected subjects and replica labels are bounded with explicit flags; descriptions, metadata and message bodies never leave the host.
- Stream-limit changes, purge, stream deletion and consumer deletion are critical because they can irreversibly discard data. Deleting the last consumer of an interest-retention stream purges all stored messages. The shipped default policy denies critical actions. Terraform-managed runtime changes can be reconciled by the initializer; durable desired-state changes belong in Terraform.
- This remote-target pack has no automatic host detection or protected-host grant recipe. Server-level monitoring and system-account administration are outside its contract.
Verify it works
Runs nats.account_info, a low-risk
read that confirms the pack can reach its target. Run it on the host once the pack
is installed; pack install runs it for
you.
sudo emisar pack verify nats
Install and configure a pack walks through the whole sequence on a host.
Actions 18 total
View on GitHub-
nats.account_info script low Low: read-only or trivially reversible
Show JetStream account usage
Show selected JetStream memory, storage, reservation, stream, consumer, quota and API counters. Return exact decimal strings for 64-bit values; exclude account metadata and arbitrary configuration.
Link to this action View source on GitHub -
nats.connection_check script low Low: read-only or trivially reversible
Check NATS TLS connectivity
Check authenticated TLS connectivity and one native RTT per resolved address of each configured seed. Fail when a transport succeeds but RTT JSON contains a zero or absent result. This is a connection check, not application delivery proof.
Link to this action View source on GitHub -
nats.consumer_info script low Low: read-only or trivially reversible
Show a JetStream consumer
Show selected consumer delivery and ack settings, filters, backlog, redelivery counters, sequence floors, pause state and replication. Omit descriptions, metadata and message content; never pull or acknowledge a message. Return 64-bit counters and nanosecond durations as exact decimal strings.
Link to this action View source on GitHubArguments Name Type Required stream string Yes consumer string Yes See the action source for defaults, validation, and limits.
-
nats.consumer_names script low Low: read-only or trivially reversible
List JetStream consumer names
List up to ten exact consumer names for one stream from one native names page. Return total, offset and next_offset advanced only by emitted names; no message delivery or acknowledgement occurs.
Link to this action View source on GitHubArguments Name Type Required stream string Yes offset integer No See the action source for defaults, validation, and limits.
-
nats.create_consumer script high High: can disrupt service
Create a durable pull consumer
Create one named durable pull consumer with an explicit filter, explicit acknowledgements and bounded delivery settings. Never create a push-delivery subject or read a message. Use the server's create-only consumer action. Terraform-managed definitions can be reconciled by the initializer.
Link to this action View source on GitHubArguments Name Type Required stream string Yes consumer string Yes filter_subject string Yes deliver_policy string No ack_wait_seconds integer No max_ack_pending string Yes max_deliver string No replicas integer Yes See the action source for defaults, validation, and limits.
-
nats.create_stream script high High: can disrupt service
Create a bounded JetStream stream
Create one stream with an explicit subject, storage, retention, capacities and replica count. No mirrors, sources, arbitrary metadata or raw configuration are accepted. This creates topology and may begin retaining matching application publications; no message payload is returned. Terraform-managed topology can be reconciled by its initializer.
Link to this action View source on GitHubArguments Name Type Required stream string Yes subject string Yes storage string Yes retention string Yes max_bytes string Yes max_messages string Yes replicas integer Yes max_age_seconds integer No See the action source for defaults, validation, and limits.
-
nats.delete_consumer script critical Critical: data loss or irreversible
Delete a JetStream consumer
Delete one consumer and its delivery/ack state. On interest-retention streams, remove messages for which that consumer was the final interest; deleting the last consumer purges all stored messages in the stream. Other retention policies retain messages according to their limits, and recreation may redeliver them. Terraform-managed topology can be recreated by the initializer.
Link to this action View source on GitHubArguments Name Type Required stream string Yes consumer string Yes See the action source for defaults, validation, and limits.
-
nats.delete_message script high High: can disrupt service
Delete one JetStream message
Irreversibly delete one explicit stream sequence without reading its content. Preserve all other messages; stream_info shows the new message count.
Link to this action View source on GitHubArguments Name Type Required stream string Yes sequence string Yes See the action source for defaults, validation, and limits.
-
nats.delete_stream script critical Critical: data loss or irreversible
Delete a JetStream stream
Irreversibly delete one stream, its stored messages and associated consumer topology. Terraform-managed topology can be recreated by the initializer, but deleted data is not recovered.
Link to this action View source on GitHubArguments Name Type Required stream string Yes See the action source for defaults, validation, and limits.
-
nats.pause_consumer script high High: can disrupt service
Pause a JetStream consumer
Pause one consumer until now plus the requested seconds. Stop new delivery while retaining consumer state; already delivered messages can still be acknowledged. Return the server's pause state without reading any message payload.
Link to this action View source on GitHubArguments Name Type Required stream string Yes consumer string Yes pause_seconds integer Yes See the action source for defaults, validation, and limits.
-
nats.purge_stream script critical Critical: data loss or irreversible
Purge every message in a JetStream stream
Irreversibly purge all stored messages from one stream while retaining the stream and consumer definitions. Return the acknowledged purge count; no content is read.
Link to this action View source on GitHubArguments Name Type Required stream string Yes See the action source for defaults, validation, and limits.
-
nats.resume_consumer script high High: can disrupt service
Resume a JetStream consumer
Clear one consumer's pause deadline and verify the API reports paused=false. Delivery can resume; no message is pulled or acknowledged by this action.
Link to this action View source on GitHubArguments Name Type Required stream string Yes consumer string Yes See the action source for defaults, validation, and limits.
-
nats.step_down_consumer_leader script high High: can disrupt service
Step down a JetStream consumer leader
Request a replicated consumer leader step-down. Delivery may pause during election. Return acceptance; consumer_info shows the replacement leader and replica catch-up.
Link to this action View source on GitHubArguments Name Type Required stream string Yes consumer string Yes See the action source for defaults, validation, and limits.
-
nats.step_down_stream_leader script high High: can disrupt service
Step down a JetStream stream leader
Request a replicated stream leader step-down. Briefly interrupt delivery while the cluster elects a replacement. Return an acceptance acknowledgement; stream_info shows the resulting leader and replica catch-up.
Link to this action View source on GitHubArguments Name Type Required stream string Yes See the action source for defaults, validation, and limits.
-
nats.stream_info script low Low: read-only or trivially reversible
Show a JetStream stream
Show one stream's selected storage/retention limits, counts, sequence range, subject summary and leader/replica state. Omit descriptions, metadata and message content. Return exact decimal strings for 64-bit values; subject and replica displays are bounded with explicit truncation or omission flags.
Link to this action View source on GitHubArguments Name Type Required stream string Yes See the action source for defaults, validation, and limits.
-
nats.stream_names script low Low: read-only or trivially reversible
List JetStream stream names
List up to ten exact stream names from one native 1024-name page. Return total, server offset, omitted-response count and next_offset advanced only by emitted names; no automatic page fan-out. Names use the documented subject-safe syntax.
Link to this action View source on GitHubArguments Name Type Required offset integer No See the action source for defaults, validation, and limits.
-
nats.update_consumer_limits script high High: can disrupt service
Update JetStream consumer ack limits
Update only selected maximum ack-pending, maximum delivery and ack-wait settings after privately reading current configuration. Preserve identity, filters, delivery settings, unknown fields and integer precision. At least one change is required. The API has no compare-and-swap guard; concurrent edits can race. Terraform-managed definitions can be reconciled by the initializer.
Link to this action View source on GitHubArguments Name Type Required stream string Yes consumer string Yes new_max_ack_pending string No new_max_deliver string No new_ack_wait_seconds integer No See the action source for defaults, validation, and limits.
-
nats.update_stream_limits script critical Critical: data loss or irreversible
Update JetStream stream retention limits
Update only selected stream byte, message and expiry limits after reading its current configuration. Preserve all other fields and integer precision privately; never return the complete configuration. Lowering limits can immediately discard stored messages. At least one change is required. The API writes the full configuration without a compare-and-swap guard, so concurrent edits can race. Terraform-managed limits can be reconciled by the initializer.
Link to this action View source on GitHubArguments Name Type Required stream string Yes new_max_bytes string No new_max_messages string No new_max_age_seconds integer No See the action source for defaults, validation, and limits.