Ai.os

Persistent agent runtime. Deploy agents that remember, survive crashes, and run forever.

from aios import Agent, tool

class ResearchAgent(Agent):
    name = "researcher"
    model = "claude-sonnet-4-6"

    @tool
    async def search_web(self, query: str) -> str:
        """Search the web. query: What to search for."""
        ...

    async def run(self):
        results = await self.search_web("latest AI papers")
        await self.memory.save("results", results)  # persists across restarts

if __name__ == "__main__":
    ResearchAgent.launch()

aios run researcher.py --detach   # run in background
aios logs researcher -f           # stream live logs
aios memory researcher            # inspect what it remembers
aios restart researcher           # restart — picks up where it left off
aios ui                           # open web dashboard

Why Ai.os

Every agent framework makes you solve the same problems from scratch:

Problem	Without Ai.os	With Ai.os
Agent crashes	Loses all context	Resumes from last tool call
Cross-run memory	DIY SQLite / Redis	`await self.memory.save("key", value)`
Swap models	Rewrite your code	Change one line: `model = "gpt-4o"`
Inspect running agents	Print statements	Web UI + `aios logs -f`
Recurring tasks	Cron job + state file	`@schedule("every 6h")`
Agent calls agent	Manual subprocess	`await self.call_agent(ResearchAgent, ...)`

Install

pip install aios-runtime

With Postgres support:

pip install "aios-runtime[postgres]"

Requires Python 3.10+. No Docker, no Redis, no external services.

Quickstart

aios init myagent          # scaffold a new agent project
cd myagent
echo "ANTHROPIC_API_KEY=your-key" >> .env
aios run myagent.py        # run it

Core API

Agent base class

from aios import Agent, tool, schedule

class MyAgent(Agent):
    name = "myagent"             # persistent identity key
    model = "claude-sonnet-4-6"  # or "gpt-4o", "ollama/llama3"
    version = "1.0.0"
    description = "What this agent does"
    system_prompt = "You are..."
    temperature = 0.7
    config = {"key": "value"}    # arbitrary config, persisted

    @tool
    async def my_tool(self, input: str) -> str:
        """Tool description shown to the LLM. input: What it means."""
        return f"result: {input}"

    async def run(self) -> None:
        ...

if __name__ == "__main__":
    MyAgent.launch()

Memory

# Short-term (cleared each run)
self.memory.set("draft", "...")
value = self.memory.get("draft", default=None)
self.memory.clear()

# Long-term (persisted forever across runs)
await self.memory.save("report", {"rows": 42})
result = await self.memory.load("report", default=None)
await self.memory.delete("report")
keys = await self.memory.keys()
all_data = await self.memory.all()

# Search (case-insensitive substring match on keys and values)
results = await self.memory.search("climate", limit=5)
# → [{"key": "finding:climate", "value": {...}, "updated_at": "..."}]

# Timeline (append-only event log)
await self.memory.log_event("analysis_complete", {"rows": 1200})
events = await self.memory.timeline(limit=100)

Crash recovery

Before each @tool call, the result is cached in SQLite. If the agent crashes and restarts, run() re-executes from the top — but every completed tool call returns its cached result instantly. The agent fast-forwards to the first uncompleted call and continues.

No manual checkpoints. No configuration. It just works.

Webhook triggers

Make an agent respond to external HTTP events instead of running once:

from aios import Agent, trigger

class GitHubReviewAgent(Agent):
    name = "gh_reviewer"
    model = "claude-sonnet-4-6"

    @trigger("webhook", path="/github", port=8080, secret="env:GITHUB_WEBHOOK_SECRET")
    async def run(self, payload: dict) -> None:
        pr = payload.get("pull_request", {})
        if not pr:
            return
        review = await self.think(f"Review this PR: {pr['title']}")
        await self.memory.save(f"review_{pr['number']}", review)

if __name__ == "__main__":
    GitHubReviewAgent.launch()

Point any webhook source at http://your-host:8080/github. Works with GitHub, Stripe, Slack slash commands, or any HTTP sender. HMAC-SHA256 signature verification built in.

Tool retries

@tool(retries=3, backoff=2.0)
async def fetch_data(self, url: str) -> str:
    """Fetch from an external API. url: endpoint to call."""
    # Automatically retried up to 3 times on exception.
    # Wait: 2s → 4s → 8s (exponential backoff).
    return await self.http_get(url)

Tool result caching

@tool(cache_ttl=60)
async def get_price(self, symbol: str) -> str:
    """Get current price. symbol: ticker to look up."""
    # Same args → same result returned instantly for 60 seconds.
    # Saves API calls and speeds up repeated LLM loops.
    return await self.http_get(f"https://api.example.com/price/{symbol}")

Combine with retries: @tool(retries=3, backoff=2.0, cache_ttl=300)

Scheduling

class DailyAgent(Agent):
    @schedule("every 24h")       # or "every 30m", "every 1d"
    async def run(self):
        await self.do_daily_work()

Next-run time persists in memory — correct schedule survives restarts.

LLM calls

# Single-shot, no tools
text = await self.think("Summarize this: ...")

# Agentic loop — LLM selects and calls tools until done
answer = await self.think_with_tools(
    "Research X, save findings, return a summary",
    max_iterations=10,
)

Agent-to-agent

# Blocking — call another agent, get text back
summary = await self.call_agent(ResearchAgent, "summarize the findings on X")

# Fire-and-forget — spawn in background
await self.spawn_agent(MonitorAgent)

Lifecycle hooks

async def on_start(self) -> None:
    """Called once before run(). Setup work goes here."""

async def on_stop(self) -> None:
    """Called after run() completes or crashes. Cleanup goes here."""

Logging

Every agent has a self.logger (a standard logging.Logger) pre-configured with the agent's name:

async def run(self) -> None:
    self.logger.info("Starting run")
    self.logger.debug("Fetching %s", url)
    self.logger.warning("Rate limit hit, backing off")

Logs appear in aios logs <name> and the web UI log viewer.

Multi-model

Change one line — no other code changes:

model = "claude-sonnet-4-6"      # Anthropic
model = "claude-opus-4-8"        # Anthropic (most capable)
model = "gpt-4o"                 # OpenAI
model = "gpt-4o-mini"            # OpenAI (fast + cheap)
model = "gemini/gemini-pro"      # Google
model = "mistral/mistral-large"  # Mistral
model = "ollama/llama3"          # Local — no API key needed
model = "ollama/mistral"         # Local Mistral

Powered by litellm — any OpenAI-compatible endpoint works.

CLI reference

Command	Description
`aios init [name]`	Scaffold a new agent project (basic template)
`aios init [name] -t scheduled`	Scaffold with a scheduled-run template
`aios init [name] -t research`	Scaffold with a web research template
`aios init [name] -t notifier`	Scaffold with a Slack notifier template
`aios init [name] -t webhook`	Scaffold a webhook-triggered agent
`aios init --list-templates`	List all available templates
`aios run agent.py`	Run in foreground
`aios run agent.py -d`	Run in background
`aios run agent.py -w`	Run, restart on file change
`aios list`	List all agents
`aios status <name>`	Show status + run history
`aios runs <name>`	Full run history (duration, tokens, errors)
`aios runs <name> --failed`	Show only failed runs
`aios cp <src> <dst>`	Clone agent (copy memory + timeline)
`aios timeline <name>`	Show event timeline
`aios timeline <name> -t run_complete`	Filter by event type
`aios logs <name>`	Show recent logs
`aios logs <name> -f`	Stream logs live
`aios stop <name>`	Stop agent
`aios restart <name>`	Restart (resumes from checkpoint)
`aios memory <name>`	Inspect long-term memory
`aios memory <name> -k key`	Show one memory key in full
`aios memory <name> -k key --set '{"x":1}'`	Write a memory key
`aios memory <name> -k key --delete`	Delete a memory key
`aios export <name>`	Export memory to JSON
`aios export <name> -o f.json`	Export to specific file
`aios import <name> f.json`	Import (merge) memory from JSON
`aios import <name> f.json --replace`	Import, wiping existing memory
`aios ui`	Open web dashboard
`aios stats`	Aggregate stats — runs, success rate, tokens, avg duration
`aios publish <agent.py>`	Scaffold a pip-installable package from an agent
`aios publish <agent.py> --push`	Build + upload to PyPI
`aios deploy [file]`	Generate Docker/Fly.io/systemd deploy bundle
`aios deploy -p fly`	Fly.io config + Dockerfile
`aios deploy -p systemd`	Linux systemd service unit
`aios test agent.py`	Dry-run agent (mock LLM calls)
`aios test agent.py -w`	Auto-rerun on file change
`aios secrets set NAME VAL`	Encrypt and store a secret
`aios secrets get NAME`	Decrypt and print a secret
`aios secrets list`	List stored secret names
`aios secrets delete NAME`	Remove a secret
`aios secrets import .env`	Bulk-import a .env file into the encrypted store
`aios version`	Show version

Environment variables

Copy .env.example to .env:

cp .env.example .env

ANTHROPIC_API_KEY=...        # claude-* models
OPENAI_API_KEY=...           # gpt-* models
GOOGLE_API_KEY=...           # gemini-* models
AIOS_LOG_LEVEL=INFO          # DEBUG | INFO | WARNING | ERROR
AIOS_ALERT_WEBHOOK=https://… # POST here when an agent crashes (Slack/Discord/custom)

Ai.os auto-loads .env on Agent.launch(). Local Ollama needs no key.

Encrypted secrets (production)

For production deployments where you don't want plain-text .env files, use the built-in encrypted secrets store:

pip install cryptography          # one-time install

aios secrets set OPENAI_API_KEY sk-...
aios secrets set SLACK_BOT_TOKEN xoxb-...
aios secrets import .env          # or bulk-import an existing .env file
aios secrets list                 # see stored names (never values)

Secrets are encrypted with Fernet symmetric encryption. The master key lives at ~/.aios/master.key (chmod 600 on Unix) and encrypted values at ~/.aios/secrets.db.

Every agent automatically calls SecretsStore.inject_to_env() at startup — secrets are merged into os.environ (existing variables are never overwritten). Agents require zero code changes; just stop shipping the .env file and store secrets once with aios secrets set.

Scrape Prometheus metrics from the web dashboard:

http://localhost:8000/metrics

Built-in tool mixins

Mix in capabilities by inheriting alongside Agent:

from aios import Agent, WebSearchMixin, FilesystemMixin, SlackMixin, PostgresMixin

class AnalystAgent(Agent, WebSearchMixin, FilesystemMixin, SlackMixin, PostgresMixin):
    name = "analyst"
    model = "claude-sonnet-4-6"

    async def run(self):
        rows = await self.pg_query("SELECT * FROM orders WHERE status = $1", ["pending"])
        summary = await self.think(f"Summarize these {len(rows)} orders: {rows[:5]}")
        await self.slack_send_message("#data-team", summary)
        await self.write_file("report.md", summary)

Mixin	Tools	Requires
`WebSearchMixin`	`web_search`, `fetch_url`	nothing (uses DuckDuckGo)
`FilesystemMixin`	`read_file`, `write_file`, `list_directory`, `delete_file`, `file_exists`	nothing
`ShellMixin`	`run_command`, `run_python`	nothing
`HttpMixin`	`http_get`, `http_post`, `http_put`, `http_delete`	nothing
`GitHubMixin`	`github_get_repo`, `github_list_issues`, `github_create_issue`, `github_list_prs`, `github_search_code`, `github_get_file`	`GITHUB_TOKEN`
`SlackMixin`	`slack_send_message`, `slack_send_blocks`, `slack_get_messages`, `slack_list_channels`, `slack_reply_to_thread`, `slack_add_reaction`	`SLACK_BOT_TOKEN`
`PostgresMixin`	`pg_query`, `pg_execute`, `pg_list_tables`, `pg_table_schema`, `pg_count`	`POSTGRES_URL` + `pip install asyncpg`
`EmailMixin`	`send_email`, `send_html_email`	`EMAIL_SMTP_HOST`, `EMAIL_ADDRESS`, `EMAIL_PASSWORD`
`DiscordMixin`	`discord_send`, `discord_send_embed`, `discord_send_message`, `discord_get_messages`, `discord_create_thread`	`DISCORD_WEBHOOK_URL` (webhook) or `DISCORD_BOT_TOKEN` (full API)
`NotionMixin`	`notion_search`, `notion_get_page`, `notion_get_page_content`, `notion_append_block`, `notion_create_page`, `notion_query_database`	`NOTION_TOKEN`
`LinearMixin`	`linear_get_issues`, `linear_get_issue`, `linear_create_issue`, `linear_update_issue`, `linear_add_comment`, `linear_list_teams`	`LINEAR_API_KEY`

Examples

File	What it shows
`examples/researcher.py`	Web research, persistent knowledge base, crash recovery
`examples/monitor.py`	URL monitoring, uptime history, scheduling
`examples/coder.py`	Write code, run tests, iterate until passing
`examples/notifier.py`	Multi-channel alerts (Slack + Discord + Email), dedup across runs
`examples/triage.py`	Linear issue triage on a schedule — classify, dedup, post Slack summary
`examples/github_reviewer.py`	GitHub PR reviewer via `@trigger("webhook")` — HMAC-verified

TypeScript / Node.js SDK

Same API, same persistence layer:

import { Agent, tool, schedule } from '@aios/sdk';

class ResearchAgent extends Agent {
  static name = 'researcher';
  static model = 'claude-sonnet-4-6';

  @tool({ description: 'Save a finding' })
  async saveFinding(topic: string, summary: string): Promise<string> {
    this.memory.save(`finding:${topic}`, { summary });
    return `Saved: ${topic}`;
  }

  async run(): Promise<void> {
    const result = await this.thinkWithTools('Research AI agents and save findings.');
    this.memory.save('last_run', result);
  }
}

ResearchAgent.launch();

cd sdk/typescript
npm install
npx ts-node examples/researcher.ts

A Python agent and a TypeScript agent with the same name share one SQLite database — memory persists across both runtimes.

Team Workspaces

Share agent memory across machines without a server:

# On machine A (set up once)
aios workspace init myteam --dir /mnt/shared/aios   # or ~/Dropbox/aios

# Push agent state to the shared dir
aios workspace push researcher

# On machine B
aios workspace init myteam --dir /mnt/shared/aios
aios workspace pull researcher                       # merge
aios workspace pull researcher --replace             # overwrite
aios workspace list                                  # see what's available

Works with any shared filesystem — NFS, Dropbox, Google Drive, S3 mounted via s3fs, etc.

Encrypted Secrets (Production)

Stop putting API keys in plain-text .env files:

aios secrets set ANTHROPIC_API_KEY sk-ant-...
aios secrets set SLACK_BOT_TOKEN xoxb-...
aios secrets list                              # shows names only, never values
aios secrets import .env                       # bulk import from existing .env
aios secrets get ANTHROPIC_API_KEY             # decrypt + print

Secrets are Fernet-encrypted in ~/.aios/secrets.db. Agents automatically receive them at startup — no code changes needed.

pip install "aios-runtime[secrets]"   # or: pip install cryptography

Remote Log Streaming

Watch a cloud-hosted agent's logs from your laptop:

# Stream logs from a remote Ai.os web UI
aios logs myagent --remote ws://my-server:8000

# Or connect directly with any WebSocket client
wscat -c ws://my-server:8000/ws/agents/myagent/logs

vs. alternatives

	Ai.os	LangGraph	CrewAI	Temporal
Crash recovery	✅ automatic	❌ manual	❌	✅ but complex
Persistent memory	✅ built-in	❌ DIY	❌ DIY	❌ DIY
Zero-config start	✅	❌	✅	❌
Web UI	✅	❌	❌	✅
Multi-model	✅	✅	✅	❌
Scheduling	✅ `@schedule`	❌	❌	✅
Agent-to-agent	✅	✅	✅	❌
Local LLMs	✅ Ollama	✅	✅	❌
Learning curve	Low	High	Low	High

Roadmap

v0.1 — Foundation ✅

v0.2 — SDKs & Ecosystem ✅

Slack, Discord, Email tool mixins
Postgres, Notion, Linear tool mixins
aios export / aios import — memory backup and migration
Web UI — dark/light theme, relative timestamps, ANSI stripping, noise filter, Trace tab
TypeScript / Node.js SDK — same API, same SQLite persistence layer (sdk/typescript/)
aios publish — share agents as pip-installable packages

v0.3 — Observability ✅

Timeline tab in web UI
Tool call Trace tab (see exactly which tools were cached for crash recovery)
Prometheus metrics export — /metrics endpoint, scrape with Grafana / Datadog
Alert webhooks on agent failure — AIOS_ALERT_WEBHOOK=<url>

v0.4 — Cloud ✅

aios deploy — generate production deploy bundle (Docker Compose, Fly.io, systemd)
@tool(retries=N, backoff=s) — automatic exponential-backoff retry on tool failure
aios publish — scaffold and upload agents as pip-installable packages
@trigger("webhook") — event-driven agents; respond to GitHub, Stripe, Slack, etc.
Team workspaces — aios workspace push/pull over any shared directory
Secrets management — Fernet-encrypted secrets store (aios secrets)
Remote log streaming — WebSocket endpoint + aios logs --remote

v0.5 — Visual Builder ✅

Drag-and-drop workflow editor in web UI (Workflow tab — nodes, edges, canvas)
Export workflow to Python agent class (Export .py button)
CSV / JSON / PDF exports from web UI (Runs, Memory, Timeline, full report)

Contributing

See CONTRIBUTING.md. PRs welcome.

License

MIT — see LICENSE.

Name		Name	Last commit message	Last commit date
Latest commit History 13 Commits
.github/workflows		.github/workflows
.vscode		.vscode
aios		aios
examples		examples
sdk/typescript		sdk/typescript
tests		tests
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
eval_agent.py		eval_agent.py
pyproject.toml		pyproject.toml

Folders and files

Latest commit

History

Repository files navigation

Ai.os

Why Ai.os

Install

Quickstart

Core API

Agent base class

Memory

Crash recovery

Webhook triggers

Tool retries

Tool result caching

Scheduling

LLM calls

Agent-to-agent

Lifecycle hooks

Logging

Multi-model

CLI reference

Environment variables

Encrypted secrets (production)

Built-in tool mixins

Examples

TypeScript / Node.js SDK

Team Workspaces

Encrypted Secrets (Production)

Remote Log Streaming

vs. alternatives

Roadmap

Contributing

License

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages