Skip to main content

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, built on Agentling.

Aldwin 0.0.3 session: connecting a Linear workspace and asking about open issues


Install

Install with uv (Python 3.11+ on macOS or Linux):

uv tool install aldwin

If you don't have uv installed yet:

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

Or install with pip:

pip install aldwin

Then start Aldwin:

aldwin

Already on 0.0.4? Upgrade in place and keep your conversation, memory, persona, and settings:

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.


Run it fully local

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

  1. Install Ollama (or LM Studio) and pull a tool-capable model, for example:

    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:

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, Word, PowerPoint, Excel, CSV, and HTML files as markdown, 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.
  • Connectors: connect Notion, Linear, GitHub, and more with /connectors; see the Connectors section below.

See the full tool list and the skills guide.


Connectors

Aldwin can connect to your other apps as MCP servers. Add one with /connectors.

Catalogue: pick Notion, Linear, GitHub, Context7, and others from the built-in catalogue. 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.

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

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.
  • 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 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, recent conversation, your profile and recent notes, and anything Aldwin reads for the turn — including connector tool results — go to that provider.
  • 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.
  • Platforms: macOS 13+ and Linux. Local MCP servers are not supported on Windows.

Read data and privacy 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 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, including how to uninstall.


Web search works with self-hosted SearXNG or one hosted search key — all behind the same web_search tool. Type /search, pick a provider with the arrow keys, 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; for SearXNG see also Set up SearXNG.

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 inside your terminal process; it isn't always-on yet. Closing the terminal stops any active task, and your conversation resumes next time you run aldwin. Windows is not yet supported.


Contributing

Contributions are welcome. Read the contributing guide to get set up, and see the docs index for the protocol, test, and release docs.

Have a question or an idea? Start a discussion. Found a bug? Open an issue.


Licence

Apache-2.0. See LICENSE and NOTICE.

Metadata

Release files for aldwin 0.0.5

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aldwin 0.0.5
File Size Uploaded Provenance Actions
aldwin-0.0.5.tar.gz 353.0 kB Without provenance Details for aldwin-0.0.5.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aldwin 0.0.5
File Interpreter ABI Platform Actions
aldwin-0.0.5-py3-none-any.whl Python 3 none any Details for aldwin-0.0.5-py3-none-any.whl

Total release size: 776.2 kB

Release files / aldwin-0.0.5.tar.gz

Download URL aldwin-0.0.5.tar.gz
Size 353.0 kB
Tags Source
SHA-256 checksum
How to use checksums
c1b62c3ef6f355985dab83054c4b671961b6e8f908d1bf2c9b838daebddd4efa
BLAKE2b-256 checksum
How to use checksums
ba6cc95b796b55bfad61cfa54eb8c157b28e76b1f97ed2c6e21e326412131f8e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / aldwin-0.0.5-py3-none-any.whl

Download URL aldwin-0.0.5-py3-none-any.whl
Size 423.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
826be9919780927ed028646ee94455f972d6425ab15bbde7238050c8c6377b9a
BLAKE2b-256 checksum
How to use checksums
b3d1413ab1e0ea04ad73d3f7b500e428c7a2d407ea32489535e2818f37fa9cd8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for aldwin 0.0.5

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page