# aidaemon

[![CI](https://github.com/davo20019/aidaemon/actions/workflows/ci.yml/badge.svg)](https://github.com/davo20019/aidaemon/actions/workflows/ci.yml)
[![Crates.io](https://img.shields.io/crates/v/aidaemon)](https://crates.io/crates/aidaemon)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

[Website](https://aidaemon.ai/) · [Documentation](https://docs.aidaemon.ai/) · [Discord](https://discord.gg/JCCPtEEy) · [𝕏](https://x.com/aidaemon_ai)

A self-hosted AI agent that runs on your machine and talks to you on Telegram, Slack, or Discord. It can run commands, browse the web, manage files, remember things across conversations, and learn your workflows over time.

I built this because I wanted to control my computer from my phone, from anywhere. Send a message on Telegram, and it runs a command, checks a log, deploys something, or researches a topic — then replies with the result. I also wanted it to run on cheap hardware: a Raspberry Pi, an old laptop, a $5/month VPS.

<!-- TODO: Add a GIF/screenshot showing a Telegram conversation with aidaemon doing something cool -->
<!-- ![Demo](docs/assets/demo.gif) -->

## What makes it different

- **It's yours** — runs on your machine, your API keys, your data. Nothing goes to a third party beyond the LLM API calls you choose to make.
- **It remembers you** — persistent memory with fact extraction, vector embeddings, and semantic recall. It learns your preferences, your projects, the people you mention. Not a shallow "memory" feature — a full knowledge graph that grows over time.
- **It's always on** — runs as a background daemon. Message it on Telegram at 3am from your phone. Schedule tasks with cron syntax or natural language. It's not an app you open — it's an assistant that's always available.
- **It can act** — 40+ tools: terminal commands, file operations, git, web browsing, web research, HTTP requests with OAuth, MCP servers. It doesn't just answer questions — it does things.
- **It's a single binary** — no Docker, no Node.js, no Python environment. One binary, copy it anywhere and run it. Starts in milliseconds, uses minimal RAM.
- **It works with any LLM** — OpenAI, xAI (Grok), Anthropic, Google Gemini, DeepSeek, Moonshot, MiniMax, Ollama, OpenRouter, Cloudflare AI Gateway, or any OpenAI-compatible API. Switch providers without changing anything else.

## Quick Start

### One-line install

```bash
curl -sSfL https://get.aidaemon.ai | bash
```

### Homebrew

```bash
brew install davo20019/tap/aidaemon
```

### Cargo

```bash
cargo install aidaemon
```

Then run `aidaemon` — the setup wizard walks you through picking a provider, entering your API key, and connecting a channel.

## Features

### Channels
Talk to it on **Telegram**, **Slack** (Socket Mode), or **Discord**. Run multiple bots, add new ones at runtime with `/connect`, no restart needed.
Send images with a caption and the agent analyzes them via vision-capable LLMs (toggle with `[files] vision_enabled` in config).
Send voice notes or audio files on Telegram, Slack, or Discord. Audio-capable models receive native `input_audio` blocks; otherwise enable local Whisper STT fallback under `[files.stt]` (requires `whisper-cli`, a GGUF model, and `ffmpeg` for OGG/Opus). See `config.toml.example` for settings. Restart after config changes.
Telegram owners can also run `/terminal [agent] [working_dir]` to launch the hosted terminal Mini App (`https://terminal.aidaemon.ai`) for direct CLI-agent sessions with automatic secure daemon pairing.

### Tools & Agents
40+ built-in tools including terminal execution, file operations, git, web browser (headless Chrome), web search, HTTP requests with auth profiles, and MCP server integration. Tools declare their risk level — read-only operations run freely, side effects require approval.

Delegate complex tasks to **sub-agents** or external **CLI agents** (Claude, Gemini, Codex, Aider — auto-discovered).

### Memory
SQLite-backed persistent memory with vector embeddings (AllMiniLML6V2). Background consolidation extracts durable facts from conversations. Semantic recall surfaces relevant context automatically. Database encrypted at rest by default.

### Skills
Trigger-based instructions that teach it new workflows. Load from files, URLs, or remote registries. Successful procedures auto-promote to skills after enough consistent use.

### Automation
Cron-style scheduled tasks with natural language time parsing. Email triggers via IMAP IDLE. Long-running goal tracking with task breakdown and multi-schedule support.

### Security
Terminal command allowlists, inline approval flow (Allow Once / Allow Always / Deny), SSRF protection, input sanitization, encrypted state, secrets in OS keychain, and role-based access control. See the [security docs](https://docs.aidaemon.ai/) for the full model.

## Running as a Service

```bash
# macOS
aidaemon install-service
launchctl load ~/Library/LaunchAgents/ai.aidaemon.plist

# Linux
sudo aidaemon install-service
sudo systemctl enable --now aidaemon
```

## Configuration

All settings live in `config.toml`, generated by the setup wizard. See [`config.toml.example`](config.toml.example) for the full reference and the [documentation](https://docs.aidaemon.ai/) for detailed guides on each feature. The provider config supports both model-level fallbacks on the primary backend and ordered cross-provider fallbacks via `[[provider.fallbacks]]`.

The built-in policy profiles `cheap`, `balanced`, and `strong` are execution presets, not separate model tiers. They all use your configured default model; the differences are context budget, tool budget, verification depth, and approval behavior. The open-source default auto-routing now floors at `balanced` for better reliability, while `cheap` remains available as a lower-budget preset for custom forks and policy tweaks.

Secrets (API keys, bot tokens) are stored in your OS keychain by default — not in config files.

If you prefer env-only secrets, set `AIDAEMON_NO_KEYCHAIN=1`. In that mode:
- aidaemon reads secrets from environment variables / `.env`
- secret writes (including OAuth token refresh rotation) are persisted back to the env file
- set `AIDAEMON_ENV_FILE=/absolute/path/.env` to control which env file is used (default: `.env` in working directory)

For env-only mode, keep the env file private (`chmod 600`) and out of version control.

For external APIs, the built-in auth flow is:
- `manage_api` for a single deterministic connect + learn + verify flow
- `manage_oauth` for OAuth services, including custom OAuth 2.0 PKCE, authorization-code, and client-credentials providers you register at runtime
- `manage_http_auth` for API keys, bearer tokens, custom headers, basic auth, or OAuth 1.0a credentials
- `manage_skills` with `learn_api` to ingest the official docs or OpenAPI/Swagger URL into a reusable API guide after auth is set up

`learn_api` now prefers OpenAPI/Swagger when available, crawls multiple docs pages on the same host when needed, discovers linked specs from docs, bundles remote OpenAPI `$ref` documents, and can switch to GraphQL schema introspection when a GraphQL endpoint is available.

`manage_api` can now auto-derive a safe verification probe from a learned OpenAPI spec, and for GraphQL onboarding it can reuse introspection as the verification probe when you didn’t provide a separate `verify_url`.

Both paths keep secrets in the keychain by default, or in the configured `.env` file when `AIDAEMON_NO_KEYCHAIN=1`.

## Building from Source

```bash
cargo build --release                              # standard build
cargo build --release --features "slack,discord"    # with Slack and Discord
cargo build --release --features "browser"          # with headless Chrome
cargo test                                          # run tests
```

See [CLAUDE.md](CLAUDE.md) for architecture details, module map, and contributor guidance.

## License

[MIT](LICENSE)
