Metadata-Version: 2.4
Name: rtlinux
Version: 0.5.0
Summary: AI Worker Runtime — run AI assistants anywhere, no Docker required
Author-email: MeshPOP <mpop@mpop.dev>
License: Apache-2.0
Project-URL: Homepage, https://mpop.dev
Project-URL: Repository, https://github.com/meshpop/rtlinux
Project-URL: Documentation, https://mpop.dev/docs/
Project-URL: Issues, https://github.com/meshpop/rtlinux/issues
Keywords: ai,agent,assistant,worker,runtime,daemon,claude,gpt,llm,chatbot,automation,bash,tool-use,scheduler,webchat,meshpop,distributed,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.20; extra == "anthropic"
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == "openai"
Provides-Extra: all
Requires-Dist: anthropic>=0.20; extra == "all"
Requires-Dist: openai>=1.0; extra == "all"
Requires-Dist: feedparser; extra == "all"
Requires-Dist: psutil; extra == "all"
Requires-Dist: pyngrok; extra == "all"
Provides-Extra: meshpop
Requires-Dist: meshpop; extra == "meshpop"
Requires-Dist: vssh; extra == "meshpop"
Requires-Dist: meshpop-wire; extra == "meshpop"
Requires-Dist: meshpop-db; extra == "meshpop"
Requires-Dist: sv-vault; extra == "meshpop"
Dynamic: license-file

# rtlinux — AI Worker Runtime

**Run AI assistants anywhere. No cloud. No Docker. Just Python.**

`pip install rtlinux` → set your API key → your assistant is running.

---

## Quick Start

```bash
pip install rtlinux
export ANTHROPIC_API_KEY=sk-ant-...

# Start a general-purpose assistant
rtlinux start assistant

# Chat with it
rtlinux chat assistant

# Or open mobile/browser UI
rtlinux webchat --worker assistant
```

That's it. Your assistant is now running in the background, listening on a Unix socket, ready to answer questions and execute commands on your machine.

---

## What is this?

rtlinux is a lightweight runtime for AI assistants. Each assistant is a Python process that:

- Listens on a Unix socket for messages
- Calls an LLM (Claude, GPT-4, Codex, or local Ollama)
- Executes bash commands via tool-calling (with a dangerous-command blocklist)
- Runs scheduled background tasks (cron-style)
- Serves a mobile-friendly web chat UI

It runs on your laptop, your VPS, your Raspberry Pi — anywhere with Python 3.8+.

---

## Install

```bash
pip install rtlinux
```

**Requirements:** Python 3.8+, an API key for your LLM of choice.

**Supported backends:**
- `claude-*` models — needs `ANTHROPIC_API_KEY`
- `gpt-*` / `o1-*` models — needs `OPENAI_API_KEY`
- `claude-code` — uses Claude Code CLI (`claude -p`)
- `codex` — uses OpenAI Codex CLI
- `cursor/...` — uses Cursor API (`CURSOR_API_KEY`)
- `ollama/...` — local models via Ollama (no key needed)

---

## Built-in Templates

| Template | Description | Model |
|----------|-------------|-------|
| `assistant` | General-purpose with bash access | claude-haiku-4-5 |
| `system-monitor` | Server health monitor + alerts | claude-sonnet-4-6 |
| `news` | Hourly news digest via TTS | claude-haiku-4-5 |
| `research` | Web research + summarization | claude-sonnet-4-6 |
| `email` | Email monitor and responder | claude-sonnet-4-6 |
| `code-reviewer` | Git diff reviewer | claude-sonnet-4-6 |
| `mac-assistant` | macOS: Calendar, Mail, AppleScript | claude-haiku-4-5 |

```bash
rtlinux templates list
```

---

## Usage

### Start a worker

```bash
# From a built-in template
rtlinux start assistant

# From a directory with template.yaml
rtlinux start ./my-bot/

# With extra env vars
rtlinux start assistant --env ANTHROPIC_API_KEY=sk-ant-... --env CUSTOM_VAR=value
```

### Talk to it

```bash
# Interactive chat (REPL)
rtlinux chat assistant

# One-shot question
rtlinux ask assistant "what's using the most memory right now?"

# Web/mobile UI (http://localhost:8080)
rtlinux webchat --worker assistant

# Expose publicly via ngrok
rtlinux webchat --worker assistant --ngrok
```

### Manage workers

```bash
# List running workers
rtlinux ps

# Stop a worker
rtlinux stop assistant

# Restart
rtlinux restart assistant
```

---

## Create Your Own Assistant

```bash
# Scaffold from template
rtlinux init my-bot --template assistant

# Edit the config
$EDITOR my-bot/template.yaml

# Run it
rtlinux start my-bot
```

**template.yaml** format:

```yaml
name: my-bot
description: "My custom assistant"
model: claude-haiku-4-5        # or gpt-4o, ollama/llama3, codex, cursor/...
system_prompt: |
  You are a specialized assistant. You have bash access.
  Your job: [describe what it does]

packages:                       # extra pip packages to install
  - anthropic
  - feedparser

schedule: "every 1h"           # run schedule_task periodically
schedule_task: |
  [what to do on the schedule]

on_message: "Help with the user's task."   # instruction for chat messages

env:                            # required environment variables
  - ANTHROPIC_API_KEY
```

---

## Python API

```python
import rtlinux

# Start a worker
result = rtlinux.worker_up("assistant")
print(result)
# {'status': 'running', 'name': 'assistant', 'pid': 12345, ...}

# Ask a question
reply = rtlinux.ask_worker("assistant", "how much disk space is free?")
print(reply)

# Interactive chat
rtlinux.chat_worker("assistant")

# Stop a worker
rtlinux.worker_down("assistant")

# List running workers
result = rtlinux.worker_ps()
for w in result["workers"]:
    print(w["name"], w["status"])
```

---

## macOS: Persistent Daemon (survives reboots)

```bash
# Install as launchd service (auto-starts on login)
rtlinux mac-up ./my-bot/template.yaml

# List launchd workers
rtlinux mac-ps

# Stop
rtlinux mac-down my-bot
```

---

## Multi-Machine (MeshPOP Fleet)

rtlinux can also run as part of a MeshPOP fleet — each worker gets a VPN IP via WireGuard and appears in `mpop servers`. This is optional and not required for standalone use.

See [mpop.dev](https://mpop.dev) for fleet documentation.

---

## Links

- **GitHub:** https://github.com/meshpop/rtlinux
- **PyPI:** https://pypi.org/project/rtlinux/
- **Docs:** https://mpop.dev/docs/
