Reference

$ fisk run --config nats.yaml "report on the ORDERS stream"

# agent.yaml - drive the NATS CLI as an agent

application_path: /usr/local/bin/nats

llm:
  model: claude-sonnet-4-6
  budget:
    max_tokens: 500000
    max_iterations: 50
    call_timeout: 120s

system_prompt: |
  You manage NATS JetStream Streams using tools.

# agent.yaml - answer questions from a local knowledge base, no wrapped app

llm:
  model: claude-sonnet-4-6

system_prompt: |
  You answer questions using the knowledge_search tool over the indexed docs.

harness:
  knowledge:
    enabled: true

# The name of the agent. Used in discovery and reused as a NATS queue
# group, so it must contain only letters, digits, "-" or "_". If you
# leave it out it defaults to the application binary's base name, or to
# "fisk-ai" when no application_path is set; set it explicitly when the
# derived name carries a dot, a space, or other characters, which are
# rejected, or to keep memory/knowledge stores separate between agents.
identity: nats

# Path to the Fisk application binary to introspect and run. OPTIONAL.
# When set, the binary is introspected once at startup to obtain its
# command tree and per-command JSON schemas. Leave it out to run an agent
# on the built-in tools (knowledge, memory, human_in_the_loop) and the
# tools remote_tools and mcp_clients import, with no wrapped application.
# Required only when expose.agent.a2a.serve_tools exposes the wrapped
# application's tools.
application_path: /usr/local/bin/nats

# The system prompt describing what the agent should do. REQUIRED for a
# "run" and for a channel that runs one, ignored by "mcp" mode and by the
# a2a endpoint. Think of it as a one-file SKILL: describe the goals and
# give broad guidance.
system_prompt: |
  You manage NATS JetStream Streams using tools.

# Keep only the commands whose tool name or tag matches. When "include" is
# present, a command must match it to be exposed.
include:
  # Regular expressions matched against the tool name: the command path
  # joined with underscores, so the "stream info" command is "stream_info".
  tools:
    - ^stream_
    - ^consumer_info$
  # Match commands by fisk tag. An empty string "" matches untagged
  # commands. The reserved ai:deny tag is always active and can never be
  # included back in.
  tags:
    - scope:read

# Remove matching commands. Applied as a filter: a command that matches
# "exclude" is dropped even if "include" allowed it.
exclude:
  tools:
    - ^stream_rm$
  tags:
    - scope:system

llm:
  # The model identifier. REQUIRED. Accepts any value the Anthropic API
  # accepts; the well-known identifiers are listed under "Models" below.
  model: claude-sonnet-4-6

  # The model backend. Defaults to "anthropic" when unset, so most agents
  # never set it. Set it only to target a different backend that has been
  # built in; naming one that is not available fails at run start with the
  # list of providers that are.
  provider: anthropic

  # Limits on the agent loop so it cannot run without end. The two caps
  # have different scopes: max_iterations is per turn, max_tokens is
  # cumulative over a conversation.
  budget:
    # Tokens a whole conversation may process, counted across every turn
    # of it. Default 500000. A conversation that reaches it takes no
    # further turn; start a new conversation or raise this. It counts
    # tokens rather than money: cache reads weigh the same as uncached
    # input here and are priced at a fraction of it.
    max_tokens: 500000
    # Cap on the tokens a single response may generate, distinct from the
    # cumulative max_tokens. Left unset it uses a built-in default that is
    # raised when thinking is on. Set it only to fit an endpoint whose
    # per-response limit is lower than that default; an explicit value wins.
    max_output_tokens: 0
    # Agent loop iterations one turn may take, a fresh allowance per
    # turn. Default 50.
    max_iterations: 50
    # Per-call timeout as a Go duration string, for example "60s" or
    # "2m". Default "120s".
    call_timeout: 120s

  # Controls whether the model exposes its reasoning, which some providers
  # call reasoning rather than thinking. The whole block is optional and
  # leaving it out is the default: nothing is sent and the model uses its own
  # behavior. Including it states a preference either way, so omitting it and
  # setting enabled false are different requests.
  #
  # Older models that predate adaptive thinking (Sonnet 4.5, Haiku 4.5) reject
  # the parameter, and so may a proxy behind ANTHROPIC_BASE_URL. Both explicit
  # states send one, so remove the block for those rather than setting false.
  thinking:
    # true asks the model to think and surfaces its reasoning separately from
    # the answer (thought-bubble lines on stderr in shell mode, folding blocks
    # in the TUI). false asks it not to think, which changes only a model that
    # would otherwise reason unaided.
    enabled: true

  # How hard the model works, which governs how deeply it reasons and how many
  # tokens it spends overall. Unset asks for nothing and the model uses its own
  # default. It sits beside the thinking block rather than inside it, so an
  # effort can be set without sending a thinking parameter.
  #
  # The value is passed to the provider as written and is not checked against a
  # list of levels, because the levels belong to the model: Anthropic takes low,
  # medium, high, xhigh and max, other providers name their own, and a model
  # released after this build may take one Fisk AI has never heard of. A level
  # the model does not take is refused at the first model call, naming it.
  reasoning_effort: high

  # When true, disables Anthropic prompt caching for the run. Left off,
  # Fisk AI caches the stable prefix of each request to lower cost and
  # latency on multi-turn runs.
  no_prompt_cache: false

  # When true, disables server-side tool search: every tool is sent to the
  # model directly instead of being deferred behind a search tool at ten or
  # more tools. Left off, tool search is used automatically when the provider
  # supports it and the tool count crosses the threshold. Set true only for an
  # endpoint that does not implement it.
  no_tool_search: false

harness:
  # Opt-in built-in tools that let the model ask the operator a question
  # at the terminal (agent mode only).
  human_in_the_loop:
    # When true, offers the model the ask_human_confirm, ask_human_select,
    # and ask_human_input tools. Off by default.
    enabled: true

  # Command tags that, in addition to the always-on ai:confirm tag, gate a
  # command behind operator approval before it runs. Matching is exact, not
  # a regex, and additive to ai:confirm. An entry that matches no loaded
  # command is reported as a warning at startup.
  confirm_tags:
    - ai:destructive
    - impact:rw

  # Limits a single tool call, at a terminal and on a worker alike.
  # Unset uses the default of 5m; set 0s for no limit at all, which is
  # what a command that legitimately runs for hours needs.
  #
  # The timeout cancels the call. A command is killed along with its
  # process group; an in-process tool stops only if it checks. A call
  # waiting on your answer runs as long as it needs. Separate from
  # expose.agent.mcp.tool_timeout and expose.agent.a2a.tool_timeout,
  # which limit a served call.
  tool_timeout: 5m

  # A hard off switch for the full-screen terminal UI: the agent always
  # uses line-by-line output, even on an interactive terminal, and the
  # command line cannot turn the UI back on. Use the --no-tui flag for a
  # one-off run instead. Negative switch, no effect in the line UI.
  no_tui: false

  # The full-screen UI rings the terminal bell each time a run blocks
  # waiting on you (an approval gate or an ask_human_* prompt). On by
  # default; set true to silence it. Negative switch, no effect in the
  # line UI.
  no_bell: false

  # Opt-in built-in key/value store that survives across runs (agent mode
  # only).
  memory:
    # When true, offers the model the memory_list, memory_read,
    # memory_write, and memory_delete tools. Off by default.
    enabled: true
    # The store implementation. Defaults to "file", which keeps each
    # memory in a markdown file under a directory; it is the only backend
    # today.
    backend: file
    # By default the stored keys and descriptions are injected into the
    # system prompt at run start so the model knows what it has saved. Set
    # true to keep the store's contents out of the prompt. Negative switch.
    no_index: false
    # Serve memory_list and memory_read only, withholding memory_write and
    # memory_delete, so a run uses what earlier runs saved without changing
    # it. The store is untouched: anything else writing to it still does.
    read_only: false
    # Backend-specific settings. For the "file" backend: "directory", the
    # path memory files live under, defaulting to "memory/<identity>". A
    # relative directory resolves under the store base when a deployment
    # sets one and against the working directory otherwise; an absolute
    # directory is used as-is.
    options:
      directory: memory

  # Scans prompts and tool results for personal data before the model, the
  # session store or telemetry sees them. Alone in this block it acts
  # without being asked for: leave it out and it redacts.
  pii:
    # redact replaces each value found with a placeholder naming its type
    # and the run continues. reject refuses the text instead: a prompt is
    # denied and a tool result is withheld from the model. off scans
    # nothing. Defaults to redact.
    mode: redact

  # Where run journals are stored, which is what --resume continues.
  # Optional; absent it uses the "file" backend under the XDG state
  # directory. Sessions cannot be disabled: every run is a conversation.
  sessions:
    # The store implementation. "file" (the default) keeps each session as a
    # JSON-lines journal under a directory. "jetstream" keeps them on a NATS
    # JetStream stream shared over a broker, using the nats_context above.
    backend: file
    # Backend-specific settings. For "file": "directory", the path journals
    # live under, defaulting to the XDG state directory; --state-dir
    # overrides it. For "jetstream": "stream", the name of an
    # operator-created stream to bind, for which --state-dir does not apply.
    options:
      directory: /var/lib/fisk-ai/runs

expose:
  agent:
    # The opt-in block that enables MCP serving. Must be present, even if
    # empty ({}), for "fisk mcp" to start.
    mcp:
      # Default listen port, used when neither --port nor the
      # FISK_AI_MCP_PORT environment variable is set. Default 8080.
      port: 8080

      # Host or IP to bind to, used when neither --address nor the
      # FISK_AI_MCP_ADDRESS environment variable is set. Defaults to the
      # loopback address 127.0.0.1, so the server serves only local clients
      # unless you set this; use 0.0.0.0 to listen on all interfaces.
      address: 127.0.0.1

      # Free-text guidance sent to clients when they connect. A client may
      # pass it to the model as a hint about how to use the server, a good
      # place for orientation the terse per-tool descriptions cannot carry.
      instructions: |
        These tools wrap the NATS CLI. Prefer stream_info before
        stream_edit, and treat all subjects as relative to the FOO account.

      # How confirmation-gated commands (ai:confirm or a confirm_tags tag)
      # behave when the connected client cannot be asked through
      # elicitation:
      #   auto   - default; ask clients that can elicit, run ungated for
      #            clients that cannot
      #   always - ask clients that can elicit, refuse for clients that
      #            cannot be asked
      #   never  - never ask, run gated commands ungated, delegating
      #            approval to the client's own UI
      confirm_over_mcp: auto

      # Maximum tool calls run at once. 0 or unset uses the default 2, a
      # negative value is rejected, and the ceiling is 1024. It is separate
      # from the a2a knob because the MCP port can be network-reachable
      # (address 0.0.0.0), a wider trust boundary than a2a's NATS peers.
      max_concurrent_tools: 2

      # How long a single served tool call may run, e.g. 60s. Unset uses
      # the default 30s. Named tool_timeout, not call_timeout, to avoid
      # colliding with llm.budget.call_timeout, which limits a different
      # unit of work. Config-only; there is no flag or environment override.
      tool_timeout: 30s

    # Optional: narrow the served set further, within the top-level
    # include/exclude selection. With neither, every selected command is
    # served (subject to the tag rules). Same regex-over-tool-name and tag
    # matching as the top-level filters.
    tools:
      include:
        tools:
          - ^stream_
      exclude:
        tools:
          - ^stream_rm$

# Name of a NATS context (as managed by "nats context" and resolved by
# jsm.go) used to connect to NATS. REQUIRED when remote_tools is set or
# when serving tools to other agents.
nats_context: ngs

expose:
  agent:
    # What this agent answers for other agents over NATS, and how long it
    # waits on the calls it makes to them. Opt-in: without the block nothing
    # answers, and a block must set serve_tools or prompts unless it holds
    # request_timeout and nothing else. Both endpoints use one connection under one
    # identity. Its knobs are separate from the mcp block's because the two
    # servers sit on different trust boundaries (NATS peers vs anything
    # reaching a TCP port).
    a2a:
      # When true, "fisk serve" answers tool calls from peers, serving one
      # tool per call and running no agent loop. It needs only
      # application_path, identity, nats_context and the tool selection: no
      # prompt and no model. Confirmation-gated commands are never served,
      # since there is no operator to approve them.
      serve_tools: true

      # Maximum tool calls run at once. A call arriving with every slot in
      # use is refused at once with a "capacity" code and no command is
      # started for it. 0 or unset uses the machine's CPU count clamped to
      # between 2 and 8 (a container's own limit, not the host's), a
      # negative value is rejected, and the ceiling is 1024.
      max_concurrent_tools: 4
      # How long a single served tool call may run, e.g. 60s. Unset uses
      # the default 30s. Config-only, no flag or environment override.
      tool_timeout: 30s

      # How long this agent waits for a peer to say anything, e.g. 30s,
      # where tool_timeout limits a call it answers. A served call is
      # answered with an acknowledgement, a message every ten seconds
      # while the tool runs, and then the reply, so this applies to the
      # gap between messages while harness.tool_timeout limits the call. A
      # card fetch is one message, so for discovery the
      # two are the same number. Unset uses the default 120s; 0s and a
      # negative are rejected, and a value under 30s is raised to it. An
      # agent that only calls other agents sets this with nothing else in
      # the block, which is valid.
      request_timeout: 120s

      # Answers prompts from peers by running the agent loop over each one
      # and streaming the run back. Its presence enables the endpoint and an
      # empty block works. Answering a prompt runs the whole loop, so
      # identity, system_prompt and llm.model are all required, and the run
      # reaches every tool include and exclude selected, not the served set.
      prompts:
        # How many prompts this process answers at once, and the number
        # above which a caller is refused rather than made to wait.
        # Default 1. The --workers flag does not reach it: that sizes the
        # queue.
        workers: 2

        # Lets a run put its questions to the caller that sent the prompt:
        # an approval for a confirmation-gated command, or a
        # human-in-the-loop question. Default false: the worker refuses
        # every gated command. Anyone permitted to answer this identity's
        # questions can approve a gated command, and an answer carries no
        # verified caller identity. The worker holds a question for
        # request_timeout, and its worker slot with it. A caller answers
        # waiting before the window runs out to restart it, for as long as
        # somebody is reading the question.
        elicit: true

# Import tools from one or more remote fisk agents over NATS and expose
# them to this agent alongside its local tools.
remote_tools:
  - # The remote agent's identity (also the NATS subject key). REQUIRED.
    name: nats
    # A prefix for the imported tool names. Applied only when a bare name
    # would clash with a local tool or another remote's tool. Defaults to
    # "name".
    alias: nats
    # Select which of the remote agent's tools to import, matched against
    # the tool name only. A "tags" filter cannot be honored, since
    # discovery does not carry tags, and an exclude-by-tag is rejected at
    # startup.
    include:
      tools:
        - ^stream_
    exclude:
      tools:
        - ^stream_rm$

mcp_clients:
  - # Identifies the server in errors and prefixes every tool imported from
    # it. REQUIRED, and limited to letters, digits, "-" and "_".
    name: filesystem
    # A shorter prefix used in place of "name" on imported tool names, under
    # the same character rules. Defaults to "name".
    alias: fs
    # The program to start. Setting it selects the stdio transport; "url" and
    # "headers" may not be set alongside it.
    command: npx
    # Arguments to "command", one per entry. Both are literal text: a
    # "${VAR}" written in either reaches the program as it stands.
    args:
      - -y
      - "@modelcontextprotocol/server-filesystem"
      - /srv/data
    # Environment variables for the child, applied on top of the environment
    # a command tool gets: this process's environment with the credential
    # variables removed.
    env:
      FS_STATE_DIR: ${HOME}/.cache/fs-mcp
    # How long the server gets to start, finish the initialize handshake and
    # list its tools. Unset uses the default 30s; 0s and a negative are
    # rejected.
    timeout: 30s
    # Which of the server's tools to import. Regular expressions matched
    # against the server's own tool name, before the alias prefix. Include
    # runs first and exclude drops from what it kept. A "tags" filter is
    # rejected on either: MCP has no tag vocabulary, so a tag filter could
    # never be honored.
    include:
      tools:
        - ^read_
    exclude:
      tools:
        - ^read_media_

  - # A server that is already running, reached over streamable HTTP.
    name: docs
    # The endpoint. Setting it selects the HTTP transport; "command", "args"
    # and "env" may not be set alongside it.
    url: https://mcp.example.net/mcp
    # Sent on every request to the endpoint's host, and dropped from a
    # redirect that leaves it, so a server cannot redirect an Authorization
    # header to a host of its choosing.
    headers:
      Authorization: Bearer ${DOCS_TOKEN}
    timeout: 15s

expose:
  agent:
    jobs:
      # The work queue to consume. It must already exist: the worker binds
      # to it and creates nothing, so its run time, retry cap and
      # concurrency stay with whoever owns the queue. Default "FISK_AI".
      queue: FISK_AI

      # The asyncjobs task type this worker handles. A task of another
      # type on the same queue is left alone, so a task submitted under a
      # type no worker handles stays queued until it expires, with no
      # error logged at either end. Default "fisk-ai:run".
      task_type: fisk-ai:run

      # How many jobs this process runs at once, default 1. The --workers
      # flag overrides it. It cannot raise throughput past the queue's own
      # concurrency, which limits every worker on that queue together.
      workers: 1

      # The NATS context the queue is reached over, defaulting to the
      # top-level nats_context. It is dialed separately from the shared
      # connection, so the queue may live on a different cluster from the
      # session store and remote tools.
      nats_context: production

      # Caps a task payload in bytes before anything decodes it, default
      # 524288. It is the only limit on a third party's input to an endpoint
      # whose sole access control is permission to write to the queue.
      max_payload: 524288

telemetry:
  enabled: true
  endpoint: http://127.0.0.1:4318
  service_name: ""
  sample_ratio: 1.0
  no_metrics: false
  capture:
    enabled: false
    messages: delta
    max_bytes: 8192