Learning Tactus

Installation and Setup

Part I was about why Tactus exists. Now we’ll do the minimum setup so you can run the examples and start building a useful workflow in Part II.

Tactus is a Python package with a CLI. You install it with pip, and you write workflows as .tac files (Lua syntax).

A Note About “Hosts” (Runtime Environments)

When you run a Tactus procedure, it may ask a human for input using primitives like Human.approve, Human.input, and Human.review.

That implies a basic architectural rule:

The simplest host is the CLI, which prompts in your terminal. There’s also a web-based IDE (a reference UI implementation), and in the long run the intended use is embedding Tactus into your own application, where your app’s UI renders the same structured interactions.

This book primarily uses the CLI host so you can run everything locally and deterministically. The IDE is optional, but it’s helpful for seeing what “human-in-the-loop as UI components” can look like.

What You'll Do

Prerequisites

Install Tactus

If you’re using a virtual environment, activate it first.

python -m pip install -U pip
python -m pip install tactus

Verify the CLI is on your PATH:

tactus --help

You can also confirm the installed version:

tactus version

About dependencies

Tactus does not require you to install system packages up front. pip will install everything it needs (including a few packages with prebuilt wheels on most platforms).

If pip install tactus fails because it’s trying to compile native dependencies, use Python 3.11/3.12, upgrade pip, and try again.

Get the Book Examples

To run the exact examples from this book, clone the repo:

git clone https://github.com/AnthusAI/Learning-Tactus.git
cd Learning-Tactus

All runnable examples live under code/.

Your First .tac Run (Fast, No API Key)

Tactus procedures live in .tac files (Lua syntax). This repo already includes runnable examples under code/.

Run a spec in mock mode. This skips real LLM calls and uses Mocks { ... } blocks for deterministic, free tests:

tactus test code/chapter-01/04-basics-simple-agent.tac --mock

If that passes, you’re ready for most of the book.

Optional: Try the Tactus IDE (Web UI Host)

The Tactus IDE runs procedures and renders human-in-the-loop interactions as UI components (buttons, forms, review panels). Think of it as a reference host you can learn from before embedding Tactus into your own product.

At the moment, the IDE requires the Tactus repo checkout (because it includes a React frontend):

git clone https://github.com/AnthusAI/Tactus.git
cd Tactus

# Python (recommended: venv)
python -m pip install -U pip
python -m pip install -e .

# Node 20+ for the IDE frontend
cd tactus-ide/frontend
npm install
npm run build

# Back in repo root
cd ../..
tactus ide

If you’re developing the IDE itself (hot reload), run make dev-ide from the Tactus repo instead of npm run build.

Optional (Strongly Encouraged): Docker Sandbox

Tactus can run procedures inside a fresh container so agent tool code can’t touch your host system. This becomes important as soon as you start giving agents filesystem and network tools.

This is separate from the Lua VM sandbox (language-level restrictions on .tac code) and from secretless execution (keeping credentials out of the runtime via broker boundaries). In practice, you often want all of these layers at once.

You’ll learn the details in Part III (including a control-surface view of why isolation matters). For now:

If you don’t have Docker, you can still run Tactus locally with language-level sandboxing—but you won’t have dev/prod parity for container isolation (and the strongest “fresh per run” filesystem boundary).

Real Runs (Requires a Provider Key)

To actually run an agent against a model provider:

export OPENAI_API_KEY="your-key"
tactus run code/chapter-01/01-basics-hello-world.tac

How This Book Organizes Examples

Provider Credentials (Optional)

Tactus reads credentials from a config file. This is the easiest way to “install once, use anywhere”.

Create ~/.tactus/config.yml:

openai_api_key: "your-key"

Project config (override for one repo)

Create .tactus/config.yml in a project directory to override your user-wide settings.

A Note on Safety (Stub Tools)

Later chapters introduce tools that look like they do real work (for example, “send an email”). In this book repo, those are implemented as safe stubs by default (they log/return an id, but they don’t actually send anything). We’ll use that to teach tool use and approval gates without side effects.