VaultOre

by CronAI
5
4
3
2
1
Score: 42/100

Description

An Obsidian plugin making workflows belong.

Reviews

No reviews yet.

Stats

0
stars
76
downloads
1
forks
32
days
3
days
9
days
118
total PRs
2
open PRs
30
closed PRs
86
merged PRs
110
total issues
45
open issues
65
closed issues
123
commits

Latest Version

9 days ago

Changelog

Upgrading

  • parser: A note is refused before anything runs when a cell's timeout is not a number above zero, or when cells depend on each other in a circle. Correct the timeout, or the depends list the error names.
  • cli: An option the command line does not know is a usage error (unknown option --name, exit code 2); before, it was ignored. Correct the option where a script calls vaultore.
  • cli: vaultore agent runs a scheduled note only after vaultore schedules approve <note.md>, and nothing until one is approved. An approval holds for the note's front matter and cells as they are: after changing either, approve again. vaultore schedules list shows what the agent may run.
  • parser: A note is refused when a limit has a value that cannot be enforced: runtime.timeout and a cell's timeout must be above 0 and at most 86400 seconds, cpuLimit above 0, and memoryLimit an amount above zero such as 512m. Correct the value the error names.
  • executor: vaultore run <note.md> --cell <id> fails for an id the note does not have; before, it ran nothing and reported a completed run. In a TypeScript cell, cell(id) throws for a name that is no cell's output, such as constructor.
  • parser: A cell id is 1 to 64 characters from the letters A-Z and a-z, digits, _ and -, and starts with a letter or digit. run and the Windows device names (con, prn, aux, nul, com0 to com9, lpt0 to lpt9) are reserved, and two ids that differ only in letter case are refused. Rename the cell the error names, also where depends, cell() and {{id}} use its id.

Features

  • cli: The agent runs only scheduled notes that were approved (#220)

Bug Fixes

  • parser: Refuse invalid timeouts, cycles and colliding ids; match output ids exactly (#214)
  • cli: Read --config-dir and refuse unknown flags (#217)
  • parser: A note cannot switch off its time, memory or CPU limit (#225)
  • executor: Cell() answers only for real outputs, and an unknown target cell is an error (#226)
  • parser: Cell ids follow Ore 0.2: form, reserved names and letter case (#230)

Dependencies

  • deps: Bump @babel/parser from 7.29.9 to 7.29.11 in the production-dependencies group across 1 directory (#188)
  • deps-dev: Bump @vitest/coverage-v8 from 4.1.10 to 5.0.5 (#176)
  • deps-dev: Bump the dev-dependencies group across 1 directory with 2 updates (#183)
  • deps: Move fast-uri to 3.1.9 (#198)
  • deps: Build core and cli with tsup 9 (#199)
  • deps: Move to TypeScript 6.0 with bundler module resolution (#200)
  • deps-dev: Bump the dev-dependencies group with 2 updates (#203)
  • deps-dev: Bump the dev-dependencies group with 4 updates (#236)

README file from

Github

VaultOre

MIT License Obsidian

VaultOre runs workflows written as Markdown notes: a note holds TypeScript, shell and AI cells, and VaultOre runs them in order, each code cell in its own container, and writes every result back under the cell. Workflows can read and write your notes, call OpenAI or Anthropic with your own key, and run on a cron schedule while Obsidian is open. The note format is Ore, an open format with its own specification.

[!WARNING] VaultOre runs code from your notes. A workflow note is executable content: it starts containers through your container engine and can, if it declares the permissions, reach the network and change files in your vault. A permission a note sets to allow applies without asking. Only run workflows you have read and trust, including notes that arrive through sync.

Example

Create a note with this content:

---
ore: true
name: Hello World
---

```ore:ts id=hello
const message = "Hello from VaultOre!";
message;
```

```ore:ts id=shout depends=[hello]
cell("hello").toUpperCase();
```

Open the command palette and run VaultOre: Run all cells. Each cell runs in a container, and a callout with its result appears under it; the full output is stored under _vaultore/. This example needs a container engine and no API key.

Requirements

Obsidian 1.13.0 or later, desktop only VaultOre starts programs and reads the vault from disk; it does not load on mobile. Its settings use the settings API that 1.13.0 introduced, so Obsidian's settings search finds them. VaultOre 0.1.3 is the last release for Obsidian 1.11.4 to 1.12
A container engine, installed and running Docker, Podman, Colima (macOS), or Apple container (macOS 26+, Apple silicon). Every run needs it, even a workflow with only AI cells
An OpenAI or Anthropic API key (optional) Only for ore:ai cells

Colima users: see Known limitations for the file-sharing mode to use. Windows has not been tested; there, VaultOre looks for Docker Desktop or Podman.

Disclosures

Network use.

  • AI cells send their prompt to api.openai.com or api.anthropic.com, with your API key, when a workflow with an ore:ai cell runs and is granted network. The prompt can contain note contents ({{note:…}}) and other cells' outputs.
  • Container images that are not on your machine yet are downloaded by your container engine from its registry (the default image, oven/bun:1-alpine, from Docker Hub). VaultOre does not contact registries itself.
  • Workflow code in TS and shell cells reaches the network only when the workflow is granted network: allow, and can then contact any host.
  • Nothing else: no telemetry, no analytics, no update checks.

Accounts and payment. AI cells need an account with OpenAI or Anthropic that has paid API access, and your own API key; the provider bills you for each request. Everything else (TypeScript and shell cells, scheduling, the CLI) works without an account.

Runs external programs. VaultOre starts your container engine's command-line tool (docker, podman, colima or container) to detect it and to run each code cell, and the cell runs the code written in the note. See the warning above.

Files outside the vault. VaultOre reads and writes files only inside the vault. Outside it, it looks for the engine's command-line tool in the directories on your PATH and in fixed install locations (macOS: /usr/local/bin, /opt/homebrew/bin, /Applications/Docker.app/Contents/Resources/bin/docker; Linux: /usr/bin; Windows: the Docker Desktop and Podman folders under C:\Program Files), and starts it. The engine mounts the vault folder into containers as the workflow's permissions allow; what the engine itself reads, such as its own configuration and image store, is the engine's business.

Installation

  • From the community plugin directory: Settings → Community plugins → Browse, search for "VaultOre", install and enable (listing).

  • From a release: download main.js, manifest.json and styles.css from a release into <your vault>/.obsidian/plugins/vaultore/, then enable VaultOre under Settings → Community plugins.

  • From source:

    git clone https://github.com/cronai-labs/vaultore.git
    cd vaultore
    bun install
    bun run build
    bun run obsidian:package   # writes packages/obsidian/package/vaultore/
    

    Copy packages/obsidian/package/vaultore/ into <your vault>/.obsidian/plugins/ and enable the plugin.

Then open Settings → VaultOre, pick your container engine, and, for AI cells, select the secret that holds your API key.

Using VaultOre

Commands

Offered only on workflow notes (frontmatter ore: true). No hotkeys are set; assign them under Settings → Hotkeys.

Command What it does
Run all cells Runs every cell of the note, in dependency order
Run cell Runs the cell under the cursor and the cells it depends on
Run cell only (skip dependencies) Runs the cell under the cursor, with its dependencies' last outputs

Cells

Cell Runs Notes
```ore:ts TypeScript on Bun, in a container The last expression is the output. cell("id") reads another cell's output; vault.read, vault.write, vault.exists, vault.mkdirp work on notes; vault.write is applied after the cell, only if the notes it read are unchanged
```ore:shell sh in a container stdout is the output
```ore:ai One request to your AI provider {{cellId}} inserts an output, {{note:Path/To/Note.md}} a note. Needs network: allow

Both container cells use the workflow's runtime.image (default oven/bun:1-alpine). The Ore specification defines the format, including cell attributes (depends, timeout, model, temperature, maxTokens) and the output files; VaultOre's implementation adds what VaultOre decides on top of it.

Settings

Setting Default
Default provider OpenAI OpenAI or Anthropic, for every ore:ai cell
Default model gpt-5-mini Used when a cell sets no model=. Clearing the field sets the current provider's default (claude-haiku-5-5 for Anthropic); switching the provider does the same while the field holds the old provider's default
Temperature provider default
Max tokens 800
AI request timeout 120 seconds
Default runtime engine Docker A workflow's runtime.engine overrides it
Output folder _vaultore Where run outputs are written
OpenAI API key, Anthropic API key none The name of a secret in Obsidian's secret storage
Run scheduled workflows off See Scheduling

Scheduling

---
ore: true
name: Daily Summary
schedule: "0 18 * * *"   # every day at 18:00, local time
---

Nothing runs on a schedule until you opt in. Settings → VaultOre → Scheduled workflows lists every note with a schedule, with its next run or why the schedule is invalid. Turn on Run scheduled workflows, then approve each note you want to run. An approval covers that note's path and exact schedule: a changed schedule, a renamed note, or a note that arrives through sync is listed but does not run until you approve it. Scheduled runs happen only while Obsidian is open.

Security Model

Permissions are declared per workflow in frontmatter, each allow, deny or ask. The defaults (permissions spec, the single source):

Permission Default Controls
network deny Network for container cells; required by AI cells
vaultRead allow Whether the vault is mounted into containers; {{note:}}
vaultWrite deny Whether that mount is writable
buildNetwork deny Nothing yet (reserved for planned Python and Go cells)

The mount enforces them. A container cell sees the whole vault read-only, the whole vault read-write, only its own run directory, or nothing, depending on vaultRead and vaultWrite. .obsidian/, which holds the plugin and its settings, and .vaultore/, which holds the CLI's settings and stored permission decisions, are hidden from every cell.

Containers are hardened on every engine: read-only root filesystem, a noexec /tmp, no Linux capabilities, a non-root user, no network unless granted, and memory and CPU limits. Docker, Podman and Colima also get no-new-privileges and a limit of 256 processes, which Apple's container cannot express (it runs each container in its own VM). Exact flags per engine: sandbox spec and permissions spec §4.

ask is asked once per content. The decision is stored for that note and bound to a hash of its frontmatter and cells; when either changes, including through sync, you are asked again. A permission set to allow or deny in the note is applied without a prompt.

Scheduling needs consent, off by default, per note and schedule (above).

API keys live in Obsidian's secret storage. VaultOre's settings hold only the name of the secret you selected, never the key, and the plugin never writes to the secret storage. Keys are used for the provider request only, not passed to containers.

Known Limitations

  • Colima with sshfs file sharing can show a container a stale, cut-off copy of a file written a moment earlier (#83). vault.write cannot save such a copy: the host applies it only if the note is still what the cell read, and otherwise fails the cell and writes nothing, so run it again. A cell that only reads still sees the stale copy, and shell cells and raw writes to /workspace (Bun.write, node:fs) get no such check. Use virtiofs: colima start --vm-type vz --mount-type virtiofs.
  • Symbolic links are not followed out of the vault by anything VaultOre reads or writes on the host (vault.write, {{note:}}, output files, the workflow note), and a link as the last component of a path is refused wherever it points. A workflow in a folder linked from outside the vault therefore cannot run.
  • Only .obsidian/ and .vaultore/ are hidden from cells. Obsidian's "Override config folder" setting is not followed.
  • Switching the provider keeps the default model of the other provider; AI cells then fail with a message saying so, until you change the model.
  • The Apple container engine is covered by unit tests only, not yet by runs against a real installation.

Command-Line Interface

@vaultore/cli runs the same workflows without Obsidian, on any folder of Markdown. It is not on npm yet; build it from source (bun run build) and run node packages/cli/dist/cli.js.

vaultore run <workflow.md> [--vault <dir>] [--config-dir <name>] [--cell <id>] [--skip-deps] [--yes] [--quiet]
vaultore list [--vault <dir>] [--config-dir <name>]
vaultore agent [--vault <dir>] [--config-dir <name>] [--state-dir <dir>] [--yes] [--rescan <seconds>] [--quiet]
vaultore schedules list [--vault <dir>] [--config-dir <name>] [--state-dir <dir>]
vaultore schedules approve <workflow.md>... [--vault <dir>] [--state-dir <dir>]
vaultore schedules revoke <workflow.md>... [--vault <dir>] [--state-dir <dir>]
vaultore schedules export [--vault <dir>] [--config-dir <name>] [--out <file>]
  • Settings come from <vault>/.vaultore/config.json (defaultProvider, defaultModel, runtimeEngine, outputRoot, aiTimeoutSeconds, …), API keys from the environment (VAULTORE_OPENAI_APIKEY or OPENAI_API_KEY, VAULTORE_ANTHROPIC_APIKEY or ANTHROPIC_API_KEY).
  • Permissions at ask are denied unless you pass --yes, and the decision is stored in the config file. A deny stored that way sticks until the note changes (#28).
  • vaultore agent is a scheduler daemon. It runs a scheduled note only after vaultore schedules approve <note.md>, and only while the note's frontmatter and cells are what you approved: an edit to either, including one that arrives through sync, stops it until you approve again. vaultore schedules list shows where each note stands, and the agent names what it does not run. --yes does not approve a schedule.
  • The agent's approvals are kept outside the vault, in approvals.json under $XDG_CONFIG_HOME/vaultore or ~/.config/vaultore (%APPDATA%\vaultore on Windows; --state-dir <dir> for another place), so that sync cannot deliver one. They are separate from the approvals in the plugin's settings.
  • vaultore schedules export writes the manifest that hands scheduled workflows to CronAI (handover spec).

More in docs/interoperability.md.

Documentation

Contributing

See CONTRIBUTING.md for setup, conventions and the release process, and the plugin development quickstart for running a dev build.

License

MIT © CronAI UG