SheetBot
SheetBot is an open-source automation and CI tool built with Node.js, Express.js, SQLite, Web Components, and JSON Schema. It provides flexible task orchestration and a widget-based UI for visualization, enabling cross-platform builds, remote installations, and bespoke automation without heavy dependencies.
Agent scripts still run on Deno, Python, Bash, or Node.js, so tasks can be written in the language that fits the job.
Core concepts
- Tasks — arbitrary scripts that run in any programming language.
- Agents — worker processes that poll for tasks matching their type and capabilities.
- Sheets — SQLite-backed tables for storing and visualizing task data.
- Artefacts — files uploaded or generated by tasks.
- Transitions — automated rules for changing task states.
Tasks are matched to agents with JSON Schema. See Why JSON Schema for the reasoning.
Quick start
Requires Node.js 22.6 or newer. Deno is still required for Deno-based agent scripts.
git clone https://github.com/jorisvddonk/sheetbot
cd sheetbot
npm install
npm run adduser
npm start
Then open http://localhost:3000/.
To run an agent:
export SHEETBOT_AUTH_USER=your_username
export SHEETBOT_AUTH_PASS=your_password
export SHEETBOT_BASEURL=http://localhost:3000
# Deno agent
deno run --allow-net --allow-env --allow-read ${SHEETBOT_BASEURL}/scripts/agent.ts
# Node.js agent
curl -fsSL ${SHEETBOT_BASEURL}/scripts/agent.js | node
Browse the docs
| Section | Use it when you want to… |
|---|---|
| Tutorials | learn by following a guided lesson — start here |
| How-to guides | accomplish a specific task |
| Reference | look up an exact contract: protocol, APIs, data formats, and widgets |
| Explanation | understand how SheetBot works and why |
Start with Getting started, then Your first task and Setting up other agents. From there, learn how to run agents with API keys, build sheet dashboards, handle artefacts, and extend SheetBot with library scripts and custom widgets. For the bigger picture, read Architecture. See the project README for the full story.
Project structure
lib/— core libraries and data providersscripts/— agent template fileslibrary/— example automation scripts (examples)sheets/— generated sheet database filesstatic/— web assets, HTML, and widgetsinit/— initialization scripts run on server startupartefacts/— task artefactsdocs/— documentation source