Vigile
SearchContents

Documentation

Install and first run

From nothing to a running service with a board in your browser and an agent connected. There is no database server to install and no account to make; the code is compiled once, with one command.

What you need

  • Node.js 22.13 or later, which has SQLite built in.
  • pnpm, to install the dependencies and build.
  • git, to fetch the code.

Vigile is developed and tested on Linux with Node.js 22. Nothing in it is specific to Linux, but other systems are untested.

Get it and build it

The examples keep the code in ~/code/vigile. If yours is elsewhere, put your folder in the place of that path wherever it comes up.

git clone https://github.com/dluc/vigile.git ~/code/vigile
cd ~/code/vigile
pnpm install
pnpm build

pnpm build compiles the TypeScript of the packages; until it has run, there is no command to start. bin/vigile in that folder runs the built command.

In every terminal

The examples in this documentation call the command vigile, and name the instance once instead of with every command. For that, every terminal you use needs these two lines, typed again in each new one:

export PATH="$HOME/code/vigile/bin:$PATH"
export VIGILE_CONFIG=~/vigile/main/config.toml

The first puts vigile on the PATH. The second says which instance a command acts on: there is no default location, and a command that is told of none stops and says so. --config <file> on a command does the same for that one command. To have both lines in every terminal without typing them, add them to your shell's start-up file.

vigile --version

Create an instance

An instance is one config file and the data folder next to it. In the same terminal:

vigile config init --name main
  Config created

  File       /home/you/vigile/main/config.toml
  Name       main
  Listen     127.0.0.1:8700
  Admin key  vig_...

  ✓ The file is readable by your account only. The admin key is stored in it; the CLI reads it from there.

config init writes the file that VIGILE_CONFIG names, with a new admin API key in it, readable by your account only. It refuses to replace a file that is already there.

Start the service

Still in the first terminal, which the service then keeps:

vigile serve
  vigile 0.1.0  main

  MCP      http://127.0.0.1:8700/mcp
  Web      http://127.0.0.1:8700/
  API      http://127.0.0.1:8700/api
  Config   /home/you/vigile/main/config.toml
  Data     /home/you/vigile/main/data
  Backups  every 24 hours into /home/you/vigile/main/backups; none taken yet, next due now

  ⚠ Auth is off for everyone but admin: a connection without an API key acts as agent1.
    To require a key from everyone: vigile config set auth.keyless_user ""

serve runs in the foreground until it is stopped with Ctrl-C. The warning is the default, and it is fine while the service listens on 127.0.0.1: before other machines can reach it, read Security.

Open the board

Open the Web address in a browser. With no tasks yet, the board is empty. See the web page for what it shows once there is a plan.

Connect an agent

Point an agent at the MCP address. Most clients take a setting of this form:

{
  "mcpServers": {
    "vigile": { "type": "http", "url": "http://127.0.0.1:8700/mcp" }
  }
}

That is all one agent on your own machine needs. It connects as the built-in user agent1, with no key, is told the routine for working on tasks, and gets a tool for each operation. MCP for agents has the details, and what to do for several agents.

A first plan, from the command line

Everything an agent can do, the command line can do. Open a second terminal, since the first one is taken by the service, and start with the two lines every terminal needs:

export PATH="$HOME/code/vigile/bin:$PATH"
export VIGILE_CONFIG=~/vigile/main/config.toml
vigile create-project --title "Website relaunch" --prefix WEB
vigile create-task --project WEB \
  --title "Checkout: a customer can pay for a basket" \
  --description "Done when a test order goes through."
vigile create-task --project WEB --parent WEB-001 \
  --title "Cart page lists the items and the total" \
  --description "Done when the total is right."
vigile create-task --project WEB --parent WEB-001 \
  --title "Payment form takes a card" \
  --description "Done when a test card is charged." --depends-on WEB-002
vigile list-next-tasks
  ID       TYPE  PRIORITY  VALUE  SIZE  ASSIGNED  TITLE
  WEB-001  –            0      –     –  –         Checkout: a customer can pay for a basket  (0/2)
  WEB-002  –            0      –     –  –         Cart page lists the items and the total

  2 tasks can be started now

list-next-tasks shows the group and the cart page: the payment form waits for the cart page. Reload the page in the browser to see the same on the board and in the graph.

To throw all of it away, stop the service with Ctrl-C in the first terminal and delete the folder ~/vigile/main. Nothing else was written.

Check it

In the second terminal:

vigile doctor

It checks the config file, the data and the running service, and changes nothing. See Troubleshooting.

Updating

Take a backup first. Then fetch the new code and build it, and stop the service and start it again:

cd ~/code/vigile
git pull
pnpm install
pnpm build

A running service goes on running the code it was started with. The doctor says so: its check "service runs the code on disk" fails until the service is restarted.

Next