Tavallio Agent

Local connector for Tavallio's Bring Your Own Environment feature.

Install

Choose the path that matches the machine you want Tavallio to use.

Option 1: macOS or Linux quick install

1. Make sure Node.js 18+ and npm are installed.
2. Run:

curl -fsSL https://raw.githubusercontent.com/DeeHendriix/tavallio-agent/main/install.sh | bash

Option 2: Windows PowerShell quick install

1. Make sure Node.js 18+ and npm are installed.
2. Open PowerShell.
3. Run:

irm https://raw.githubusercontent.com/DeeHendriix/tavallio-agent/main/install.ps1 | iex

Option 3: direct npm install on any OS

1. Make sure Node.js 18+ and npm are installed.
2. Run:

npm install -g tavallio-agent

Option 4: run without a global install

npx tavallio-agent status

Option 5: from this repo during development

npm install -g ./agent

Pair

After install:

1. Open Tavallio.
2. Go to Settings -> Environment.
3. Choose Use My Own Computer or VPS.
4. Click Generate Pairing Code.
5. Copy the connect command Tavallio shows you.
6. Run it on the machine you want Tavallio to use.

Example:

tavallio-agent connect --code ABCD-EFGH --server "https://YOUR_PROJECT.supabase.co/functions/v1/localenv-agent"

connect stores the agent token locally and then starts the agent loop by default, so leave it running.

Optional CLI bootstrap

Tavallio can install a curated starter toolset for local work:

tavallio-agent bootstrap --profile core,coding,media,data --yes

Included by default:

• core: Git, jq, ripgrep, fd, FFmpeg
• coding: GitHub CLI, Python 3
• media: FFmpeg, ImageMagick, yt-dlp
• docs: Pandoc, ImageMagick
• data: jq, yq, sqlite3, Python 3

Useful flags:

tavallio-agent bootstrap --profile core,coding,media,data --dry-run
tavallio-agent bootstrap --profile core --include gh --yes

The bootstrap command uses the machine's package manager where possible:

• macOS: Homebrew
• Ubuntu/Debian: apt-get
• Fedora/RHEL-style: dnf
• Arch: pacman
• Windows: winget or Chocolatey

This is safer than bundling third-party binaries inside the agent package itself, and it keeps Tavallio's local worker thin.

Requirements

• Node.js 18 or newer
• A Tavallio pairing code from Settings -> Environment
• Chrome, Chromium, or Microsoft Edge installed locally if you want Tavallio to automate websites through your own computer

What it can do

• Run local terminal commands
• Read and write local text files inside the paths you allow
• List local directories
• Open URLs in your default browser
• Reuse a Tavallio-managed local browser profile for browser automation tasks
• Execute signed multi-step tasks that combine shell, file, and browser work under one Tavallio timeline
• Enforce device-level browser policy for allowed origins, blocked origins, download location, and optional file-upload access

The agent is a thin worker. Tavallio keeps orchestration, approvals, and policy logic server-side, then sends signed short-lived tasks down to the agent for execution.

Commands

tavallio-agent connect --code ABCD-EFGH --server "https://YOUR_PROJECT.supabase.co/functions/v1/localenv-agent"
tavallio-agent start
tavallio-agent status
tavallio-agent version
tavallio-agent bootstrap --profile core,coding,media,data --yes
tavallio-agent disconnect

Publishing

From the agent/ directory:

npm whoami
npm run pack:dry-run
npm publish --access public