tiny-harness
tiny-harness runs an AI agent that can hold a conversation, call tools and survive a
crash. You can use it in two ways:
- In your terminal. Install one command and chat with the agent in a terminal user
interface (the TUI).
- In your Python application. Start the agent from your own code and serve it to
your users over the A2A protocol.
Full documentation: madarauchiha-314.github.io/tiny-harness
Quickstart: chat in your terminal
You need Python 3.14 and an OpenAI API key.
pip install tiny_harness
export OPENAI_API_KEY=sk-...
tiny-harness
The TUI opens. Type a message and press Enter.
On the first run, tiny-harness creates its configuration file at
~/.tiny-harness/config.toml. It also downloads the Temporal server one time. Temporal
keeps your tasks safe when the program stops.
No OpenAI key? Use a local model with Ollama. See
Models.
Read more: CLI guide.
Quickstart: run it in your Python application
pip install tiny_harness
export OPENAI_API_KEY=sk-...
Write a configuration file, config.toml:
[temporal]
mode = "embedded" # tiny-harness starts Temporal for you
[openai]
model = "gpt-6.1-sol"
[server]
base_url = "http://127.0.0.1:8080"
Start the agent from your code:
import asyncio
from pathlib import Path
from tiny_harness.config import Settings
from tiny_harness.service import running_harness
async def main() -> None:
settings = Settings.load(Path("config.toml")) # secrets come from the environment
async with running_harness(settings) as harness:
print(f"Agent ready at {harness.base_url}")
await harness.wait() # serve until the process stops
asyncio.run(main())
Any A2A client can now talk to the agent at harness.base_url.
Read more: SDK guide.
Documentation
License
Apache-2.0. See LICENSE.
