rtlinux 0.5.2

AI Worker Runtime — run AI assistants anywhere, no Docker required

rtlinux — AI Worker Runtime

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

Already have a Codex or Claude Code subscription? No API key needed — use it directly.

---

Quick Start

Option A — Codex subscription (no API key needed)

pip install rtlinux

# Uses your existing Codex CLI subscription
rtlinux init my-bot --template assistant
# Edit my-bot/template.yaml → set model: codex
rtlinux start my-bot
rtlinux chat my-bot

Option B — API key

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

rtlinux start assistant
rtlinux chat assistant

That's it. Your assistant is 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

pip install rtlinux

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

Supported backends:

Model	Billing	Notes
codex	Codex subscription	Uses codex CLI — no API key
claude-code	Claude Code subscription	Uses claude -p CLI — no API key
claude-haiku-4-5, claude-sonnet-4-6	Anthropic API key	ANTHROPIC_API_KEY
gpt-4o, o1, etc.	OpenAI API key	OPENAI_API_KEY
ollama/llama3, etc.	Free (local)	Needs Ollama running locally
cursor/...	Cursor subscription	CURSOR_API_KEY

---

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

rtlinux templates list

---

Usage

Start a worker

# 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

# 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

# List running workers
rtlinux ps

# Stop a worker
rtlinux stop assistant

# Restart
rtlinux restart assistant

---

Create Your Own Assistant

# 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:

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

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)

# 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 for fleet documentation.

---

Links

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