Metadata-Version: 2.5
Name: aldwin
Version: 0.0.6
Summary: An open-source personal assistant that runs on your own computer, built on Agentling.
Project-URL: Homepage, https://askaldwin.com
Project-URL: Repository, https://github.com/lunarstack-co/aldwin
Project-URL: Issues, https://github.com/lunarstack-co/aldwin/issues
Project-URL: Changelog, https://github.com/lunarstack-co/aldwin/blob/main/CHANGELOG.md
Project-URL: Documentation, https://github.com/lunarstack-co/aldwin#readme
Author-email: Folarin Akinloye <me@folarin.dev>
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: agentling,agents,ai,aldwin,assistant,cli,llm
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Requires-Dist: agentling<0.3,>=0.2
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: fastapi<1,>=0.115
Requires-Dist: httpx>=0.28.0
Requires-Dist: markdownify>=0.14.0
Requires-Dist: mcp<3,>=2.3
Requires-Dist: packaging>=23.0
Requires-Dist: pathspec>=0.12.0
Requires-Dist: prompt-toolkit>=3.0.48
Requires-Dist: pydantic>=2.10.0
Requires-Dist: pypdfium2>=4.30.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.9.0
Requires-Dist: trafilatura>=2.0.0
Requires-Dist: typer>=0.15.0
Requires-Dist: tzlocal>=5.2
Requires-Dist: uvicorn<1,>=0.34
Requires-Dist: websockets<18,>=13
Provides-Extra: docs
Requires-Dist: openpyxl<4,>=3.1; extra == 'docs'
Requires-Dist: python-docx<2,>=1.1; extra == 'docs'
Requires-Dist: reportlab<5,>=4; extra == 'docs'
Provides-Extra: office
Requires-Dist: mammoth<2,>=1.8; extra == 'office'
Requires-Dist: openpyxl<4,>=3.1; extra == 'office'
Requires-Dist: python-pptx<2,>=1.0; extra == 'office'
Description-Content-Type: text/markdown

# Aldwin

An open-source personal assistant that works with your files and documents, knows good habits out of the box, and runs on your own computer, in your terminal or your browser, built on [Agentling](https://agentling.dev).

![Aldwin 0.0.3 session: connecting a Linear workspace and asking about open issues](https://raw.githubusercontent.com/lunarstack-co/aldwin/main/docs/assets/demo.gif)

---

## Install

Install with [uv](https://docs.astral.sh/uv/) (Python 3.11+ on macOS or Linux):

```bash
uv tool install aldwin
```

If you don't have `uv` installed yet:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

Or install with `pip`:

```bash
pip install aldwin
```

Then start Aldwin in your terminal:

```bash
aldwin
```

Or open it in your browser:

```bash
aldwin web
```

Already have Aldwin? Upgrade in place and keep your conversations, memory, persona, and settings:

```bash
uv tool upgrade aldwin
```

### First run

The first time you run `aldwin`, it creates a private home folder at `~/.aldwin` and looks for a local model (Ollama or LM Studio). If one is running, you can chat with no account. Otherwise it offers a cloud provider (OpenAI, Anthropic, Gemini, OpenRouter, or DeepSeek) or shows how to install a local server. A Tavily key for web search is optional: Aldwin checks it with Tavily before saving it, and `Enter` skips it. You can connect any search provider later with `/search`.

If you already have an OpenAI key from an earlier install, Aldwin keeps it and does not force you to reconfigure.

After that, `aldwin` picks up your latest conversation where you left off. Type `/help` at the prompt to see what you can do. Switch models any time with `/model`.

The first `aldwin web` asks the same thing in the browser: connect a model with an API key, a local model, or another server, then optionally tell Aldwin your name, your work, and how you like answers.

---

## Use it in your browser

`aldwin web` serves Aldwin from your own computer and opens it in your browser. It comes with the normal install; there is nothing else to set up.

```text
Aldwin web is running at http://127.0.0.1:7841
Open this link to start: http://127.0.0.1:7841/?t=…
Press Ctrl-C to stop.
```

- **Chat** with streamed answers, and choose how much of Aldwin's work to see (Clean or Detail).
- **Approve** file edits, commands, and app actions from a card that shows exactly what will happen.
- **Find, rename, pin, and delete** past conversations in the sidebar.
- **Settings** for models, search, skills, connected apps, limits, appearance, and updates, with no files to edit.

The terminal and the browser share one home folder, so conversations, memory, skills, keys, and settings are the same in both. A conversation answers in one place at a time.

The server listens on this computer only, and each run prints a new one-time link. Leave the terminal open while you use it, and press `Ctrl-C` to stop. Options: `--port`, `--no-open`, `--workspace`, and `--host` (loopback addresses only).

The full guide is at [askaldwin.com/docs/web](https://askaldwin.com/docs/web/install).

---

## Run it fully local

No cloud account required when Ollama or LM Studio is already serving a model on your machine.

1. Install [Ollama](https://ollama.com) (or [LM Studio](https://lmstudio.ai)) and pull a tool-capable model, for example:

   ```bash
   ollama pull qwen3:8b
   ```

2. Install Aldwin (`uv tool install aldwin`) and run `aldwin`.

3. When Aldwin finds the local model, pick it and start chatting. Your prompts stay on loopback (`127.0.0.1` / `localhost`).

Built-in providers (bundled catalogue — no online lookup):

| Provider | Kind | Notes |
|---|---|---|
| Ollama | Local | Default `http://localhost:11434` |
| LM Studio | Local | Default `http://localhost:1234/v1` |
| OpenAI | Cloud | Needs an API key |
| Anthropic | Cloud | Needs an API key |
| Google Gemini | Cloud | Needs an API key |
| OpenRouter | Cloud | Needs an API key |
| DeepSeek | Cloud | Needs an API key |

**Other server:** use `/model` → Other server, or add an OpenAI-compatible endpoint under `providers:` in `~/.aldwin/config.yaml`:

```yaml
providers:
  my-local:
    title: My local server
    shape: openai_chat
    base_url: http://127.0.0.1:8080/v1
    local: true
```

Supported shapes are `openai_chat`, `anthropic`, and `ollama`. Non-loopback `http://` URLs require `local: true` (or use `https://`).

---

## What Aldwin can do

- **Files:** list, find, search, and read files in your workspace; edit or create them after showing you a diff.
- **Documents:** read PDF, CSV, and HTML files as markdown, plus Word, PowerPoint, and Excel with the `aldwin[office]` extra, and download files from the web.
- **Notes and memory:** remember facts you tell it, search past notes and conversations, and keep a profile you write yourself.
- **Persona:** change how Aldwin talks by editing `persona.md` or asking it to.
- **Web:** search the web with SearXNG or a hosted key (`/search`), and read pages.
- **Terminal:** run shell commands, always with your approval.
- **Planning:** keep a live checklist for longer jobs and do exact arithmetic and date maths.
- **Skills:** ten built-in skills, your own skills in `~/.aldwin/skills/`, and an `@` picker to choose one for a message.
- **Models:** switch between local and cloud providers with `/model`; see [Run it fully local](#run-it-fully-local).
- **Long chats:** when a chat gets long, Aldwin writes itself notes on the older part and keeps going, and every message stays on screen. `/compact`, or **Make room now** in the browser, does it on request.
- **Connectors:** connect Notion, Linear, GitHub, and more with `/connectors`, or from Settings in the browser; see the [Connectors](#connectors) section below.

See the [full tool list](https://github.com/lunarstack-co/aldwin/blob/main/docs/tools.md) and the [skills guide](https://github.com/lunarstack-co/aldwin/blob/main/docs/skills.md).

---

## Connectors

Aldwin can connect to your other apps as MCP servers. Add one with `/connectors` in the terminal, or under Settings, Tools in the browser.

**Catalogue:** pick from 34 apps in the built-in catalogue, including Notion, Linear, GitHub, and Context7. Sign in through your browser and Aldwin stores the token in `~/.aldwin/credentials` (mode 0600).

**Any MCP server:** paste a URL to add any remote server that isn't in the catalogue. If the server needs a sign-in, Aldwin offers a browser sign-in when the server supports one, and asks for a token when it doesn't.

**Local servers:** run a server from a command, for example:

```bash
npx -y @modelcontextprotocol/server-filesystem /path/to/folder
```

Local servers start only after you approve the command. They run with a minimal environment in your workspace folder. Local servers are not supported on Windows.

**Import:** `aldwin connectors import` brings in servers already configured in other agent apps.

**Ask Aldwin to connect:** type "connect me to Notion" and Aldwin proposes the connector for you to approve.

---

## Safety

Aldwin runs on your machine without a sandbox, so every tool call goes through a policy engine first:

- **Reading is free, changing asks.** Read-only tools run straight away. Edits show a diff and default to **No**. Shell commands and downloads ask every time. In the browser, each request is a card with Allow and Deny, and nothing runs until you click one.
- **Secrets are off limits.** SSH keys, cloud credentials, `.env` files and similar are blocked outright, whatever you or the model ask for.
- **Dangerous commands are refused.** `sudo`, `rm -rf /`, disk formatting and similar are refused before you're even asked.
- **Commands get a clean environment.** API keys, tokens, and passwords in your shell are never passed to commands Aldwin runs.
- **Everything read is untrusted.** Text from files, pages, and command output is treated as data, never as instructions.
- **Every decision is logged** to `~/.aldwin/logs/approvals.jsonl`, with secrets redacted.
- **Connector tools that only read run on Auto** based on the server's own hint. Turn the trust toggle off in `/connectors` and every tool from that server will ask first.
- **Anything that changes something asks you first.** Connector tools the server does not mark read-only always show an approval.
- **All connector output is treated as untrusted.** The same rule as for files and command output.
- **Tokens stay local.** Sign-in tokens are kept in `~/.aldwin/credentials` (mode 0600) and never pass through the model.
- **Local servers need approval and run in a clean environment.** If you edit the command by hand, Aldwin asks again before re-running it.
- **Known limits:** a server can mark a write tool read-only, and Aldwin will trust that hint. A local server runs with your user's rights; there is no sandbox.

Read the [safety model](https://github.com/lunarstack-co/aldwin/blob/main/docs/safety.md) for the full rules and known limits.

---

## Data and privacy

- **No telemetry.** Aldwin collects no analytics.
- **Sent to a cloud model provider:** when you use a cloud model, your prompts, the conversation (or Aldwin's notes on its older part), your profile and recent notes, and anything Aldwin reads for the turn, including connector tool results, go to that provider. When a chat gets long, its older messages go to the provider once more so it can write those notes.
- **Fully local:** when you use Ollama, LM Studio, or another loopback model, conversation data stays on your machine (except optional web tools, remote connectors, and the PyPI update check).
- **Web search:** with SearXNG, the query goes to your instance (often localhost). With a hosted key, the query goes to that provider. Connect or switch with `/search`.
- **Stays local:** everything else in `~/.aldwin`, including your API keys, saved conversations, sign-in tokens, and logs. Connector tokens never go to the model.
- **In the browser:** `aldwin web` listens on this computer only, needs the one-time link it prints, and loads nothing from other sites.
- **Platforms:** macOS 13+ and Linux. Local MCP servers are not supported on Windows.

Read [data and privacy](https://github.com/lunarstack-co/aldwin/blob/main/docs/privacy.md) for the home folder layout and every network call Aldwin makes.

---

## Commands

| Command | What it does |
|---|---|
| `aldwin` | Open the chat and resume the latest conversation |
| `aldwin web` | Open Aldwin in your browser, served from this computer only |
| `aldwin setup` | Set or update API keys and the default model |
| `/help` | Show slash commands and keyboard shortcuts inside the chat |
| `Esc` | Stop the current answer |

See all [commands, slash commands, and shortcuts](https://github.com/lunarstack-co/aldwin/blob/main/docs/commands.md), including how to uninstall.

---

## Web search

Web search works with self-hosted SearXNG or one hosted search key, all behind the same `web_search` tool. Type `/search` (or open Settings, Search in the browser), pick a provider, and paste its key: Aldwin checks the key with the provider before saving it, and tells you why if it doesn't work. The same screen switches provider, updates a key, or disconnects one. Step-by-step guides for every provider are at [askaldwin.com/docs/search](https://askaldwin.com/docs/search/overview); for SearXNG see also [Set up SearXNG](docs/searxng.md).

| Provider | Cost | Key check |
|---|---|---|
| SearXNG | free, runs on your computer | found automatically on `:8080`, or enter its address |
| Tavily | free monthly credits, then paid | free; can take up to 20 seconds |
| Brave | paid plan | uses one Brave query |
| Exa | paid | free |
| Perplexity | paid | free |
| Parallel | paid | free |
| Firecrawl | paid plan with credits | free |

Keys are saved in `~/.aldwin/secrets.yaml` (mode `0600`). You can also set them in the environment (`TAVILY_API_KEY`, `BRAVE_API_KEY` or `BRAVE_SEARCH_API_KEY`, `EXA_API_KEY`, `PERPLEXITY_API_KEY`, `PARALLEL_API_KEY`, `FIRECRAWL_API_KEY`, `SEARXNG_URL`); an environment variable wins over a saved key. With `search.provider: auto` (the default), Aldwin uses the first connected provider in the order above, so a Tavily key wins over SearXNG.

SearXNG must expose JSON results (`format=json` / `search.formats`). Prefer SearXNG when you want queries to stay on a machine you control; a hosted provider receives the query under its own privacy terms. Brave's key check uses one of your plan's queries.

---

## What's next

Aldwin runs while its terminal window is open, whether you started `aldwin` or `aldwin web`; it isn't always-on yet. Closing the terminal stops any active task, and your conversation resumes next time you start Aldwin. The browser interface only opens on the computer running it. Windows is not yet supported.

---

## Contributing

Contributions are welcome. Read the [contributing guide](https://github.com/lunarstack-co/aldwin/blob/main/CONTRIBUTING.md) to get set up, and see the [docs index](https://github.com/lunarstack-co/aldwin/blob/main/docs/README.md) for the protocol, test, and release docs. Working on the browser interface? Start with the [web UI guide](https://github.com/lunarstack-co/aldwin/blob/main/web/README.md).

Have a question or an idea? Start a [discussion](https://github.com/lunarstack-co/aldwin/discussions). Found a bug? Open an [issue](https://github.com/lunarstack-co/aldwin/issues).

---

## Licence

Apache-2.0. See [`LICENSE`](https://github.com/lunarstack-co/aldwin/blob/main/LICENSE) and [`NOTICE`](https://github.com/lunarstack-co/aldwin/blob/main/NOTICE).
