vis.yml

# vis.yml — project config (snapshotted when an environment is created).
#
# Everything below is commented out: this file documents every knob and its
# default. To enable a block, copy the config lines (the ones indented under a
# heading) and remove their single leading "# ". Lines that are plain prose stay
# comments.
#
# Master switch: the OS jail + egress proxy are OFF by default. Opt in with
# `jail.enabled: true` in the jail block below; omit it (or set false) to run
# children unconfined — full filesystem, open network.


# ── Workspace filesystem catalog ─────────────────────────────────────────────
# One documented list of every filesystem root Vis knows about. Each entry:
#   id          stable handle referenced by jail.filesystem.allow
#   path        the root (bare path or ~-relative)
#   description shown in the session access view so the agent knows its purpose
#   access      read-write (default) | read-only
#   search      true (default) = walked by the default rg/find_files sweep;
#               false = kept OUT of the default sweep (explicit paths still reach it)

workspace:
  filesystem:
    - id: fff
      path: ~/fff
      description: Blockether FFF fork — high-performance fuzzy file finder and grep engine.
    - id: clj-fff
      path: ~/clj-fff
      description: Blockether Clojure bindings for FFF.
    - id: clj-parinferish
      path: ~/clj-parinferish
      description: Sibling repo — conservative structural balancing for Clojure edits.
    - id: clj-ruff
      path: ~/clj-ruff
      description: Blockether Clojure bindings for ruff — bump ruff + release there, then move the com.blockether/ruff pin in deps.edn.
    - id: lanterna
      path: ~/lanterna
      description: Blockether Lanterna fork — release there, then move the com.blockether/lanterna pin in the TUI extension.
    - id: tree-sitter
      path: ~/tree-sitter-language-pack
      description: Sibling repo — tree-sitter grammars for syntax highlighting and the patch parse gate.
    - id: tree-sitter-clojure
      path: ~/tree-sitter-clojure
      description: Blockether fork of sogaiu/tree-sitter-clojure — THE Clojure grammar (grammar.js + queries/highlights.scm + queries/tags.scm). The language pack pins it by rev in sources/language_definitions.json; bump the grammar here, tag v0.0.13-blockether.N, then move that rev.
    - id: spel
      path: ~/spel
      description: Sibling repo — Spel CLI and runtime.
    - id: svar
      path: ~/svar
      description: Sibling repo — structured LLM output + routing library.
    - id: skjema
      path: ~/skjema
      description: Sibling repo — Blockether JSON Schema 2020-12 validator, reflection-free and native-image safe, validating EDN directly.
    - id: clj-imaging
      path: ~/clj-imaging
      description: Sibling repo — Blockether AWT-free imaging (decode/encode/transforms/SVG) over a first-party Rust cdylib.
    - id: vis-python-runtime
      path: ~/vis-python-runtime
      description: Sibling repo — first-party embedded Python runtime for the sandbox, replacing GraalPy in the native image; prebuilt per platform and pinned from vis' deps.edn.
    - id: infrastructure
      path: ~/infrastructure
      description: Sibling repo — private operations automation. Nothing about it belongs in this repository.
    - id: blockether-com
      path: ~/blockether.com
      description: Sibling repo — source for the Blockether website.
    # (`~/.vis` — Vis' own session folder — is granted implicitly by the engine.)
    # Managed REPL / test-runner dependency caches. Granted so a jailed JVM/Node
    # resolves already-cached artifacts, but kept OUT of the default search sweep.
    - id: m2
      path: ~/.m2
      description: Maven/Clojure dependency cache.
      search: false
    - id: clojure
      path: ~/.clojure
      description: tools.deps config + cache (deps.edn) read at JVM startup.
      search: false
    - id: clj-tslp
      path: ~/.cache/clj-tslp
      description: Extracted tree-sitter native library loaded by the patch parse gate and the TUI highlighter.
      search: false
    - id: graal
      path: ~/.sdkman/candidates/java/25.1.3-graalce
      description: GraalVM CE 25.1.3 (SDKMAN, see .graalvm-version) — the jailed JVM reads its runtime dylibs.
      access: read-only
      search: false
    - id: npm
      path: ~/.npm
      description: Node/Vite/Capacitor cache for the apps/vis-companion universal build.
      search: false

# ── Feature toggles ──────────────────────────────────────────────────────────
# Built-in extension toggles. Omit a key to use its default.
toggles:
  # Default false. ON here because this repo IS vis: the agent needs to read its
  # own gateway event journals and session transcripts to debug them.
  introspection: true
#   # Default true. Set false to remove the Exa/GitHub/arXiv live-research extension.
#   web_search: false


# ── Jail ─────────────────────────────────────────────────────────────────────
# The single confinement switch. When `enabled: true`, Vis enforces BOTH axes
# together — filesystem admission and network egress. When false (the default),
# neither applies: open filesystem, open network.
#
# jail:
#   enabled: true
#
#   # Which workspace ids enter the OS jail. Deny-by-omission: an id NOT listed
#   # here is not confined-granted. Access (RW vs read-only) comes from the
#   # catalog entry above.
#   filesystem:
#     allow: [fff, clj-fff, clj-parinferish, clj-ruff, lanterna, tree-sitter, tree-sitter-clojure, spel, svar, skjema, clj-imaging, vis-python-runtime, infrastructure, blockether-com, m2, clojure, clj-tslp, graal, npm]
#
#   # Outbound egress allowlist. A bare host also matches its subdomains, so
#   # `github.com` covers `api.github.com`, and `githubusercontent.com` covers
#   # `raw.githubusercontent.com`. Empty / unset allowlist = any host (minus the
#   # SSRF deny-floor).
#   network:
#     allowed_domains:
#       - github.com
#       - githubusercontent.com
#       - exa.ai
#
#     # Extra local ports on which a confined shell child may accept connections.
#     # Empty / unset = no extra inbound ports (the secure default).
#     inbound_ports:
#       - 5273
#
#   # What of the OPERATOR's ambient environment a confined child keeps:
#   #   declared (default) nothing but a non-secret basics allowlist
#   #                      (PATH, HOME, USER, SHELL, LANG/LC_*, TERM, TZ, TMPDIR …)
#   #   inherit            the whole ambient environment, secrets included, with
#   #                      filesystem, network, exec and Mach confinement untouched.
#   # The PROJECT's own variables (.env and the `environment:` block below) reach
#   # the child in BOTH modes; LD_*, DYLD_*, PERL*, BASH_ENV … are refused in both.
#   environment: declared


# ── Environment ──────────────────────────────────────────────────────────────
# The workspace's `.env` and `.env.local` are loaded BY DEFAULT — the whole file,
# with nothing declared — and reach every child Vis spawns: shell(...) (confined
# or not), managed REPLs, test runners and Python extensions.
#
# `environment:` is for what a dotenv file cannot say. It names the SOURCE of a
# value, never the value itself (a literal is refused: config is rewritten to
# disk, and a secret typed here would land there in plaintext).
#
# Resolution order for any name, everywhere:
#   `environment:` declaration → .env, then .env.local → the environment that
#   started Vis.
#
# environment:
#   # another process variable, passed through or renamed
#   OPENAI_API_KEY: {env: WORK_OPENAI_KEY}
#   # a dotenv name under a different name (a plain .env entry needs nothing)
#   STRIPE_KEY: {dotenv: STRIPE_TEST_KEY}
#   # the OS credential store (macOS Keychain; secret-tool elsewhere)
#   EXA_API_KEY:
#     keychain: vis-exa
#     account: alice
#   # a helper command — argv, never a shell line; trimmed stdout IS the value
#   GITHUB_TOKEN: {command: [gh, auth, token]}