Repository navigation
Releases
Aldwin 0.0.6
Aldwin opens in your browser, and long chats keep going: aldwin web serves the same assistant as the terminal from your own computer, and when a chat gets long, Aldwin writes itself notes on the older part instead of forgetting it.
Added
aldwin web: a loopback server that opens Aldwin in your browser. Listens on127.0.0.1port 7841 (or a free port), prints a one-time link, and takes--host,--port,--no-openand--workspace. The UI ships inside the wheel, so no Node is needed to run it.- Browser first run: connect a model with an API key, a local model, or another server, then an optional profile step (first name, occupation, answer styles).
- Chat in the browser: streamed answers with highlighted code, tables, Mermaid diagrams and maths; Stop, Retry and Continue; model and search pickers; a context ring; Clean and Detail views; light and dark themes.
- Conversations: a sidebar with search, Pinned and Recents, a See all page grouped by date, and rename, pin and delete from each conversation's menu. Search finds chats by the words in their messages as well as their titles, and shows the matching words.
- Approval cards: Allow, Always allow in this chat (where grantable) and Deny with an optional reason, shown on the step they belong to.
- Tool displays: typed displays for terminal output, diffs, file lists, search results, pages, tables, memory and denials.
- Skills and apps per message:
@picks up to three skills and/up to three connected apps in the browser's message box. - Settings in the browser: Models, Search, Skills, Tools, Advanced, Appearance and About. Advanced groups the limits with their units and defaults, checks each value against its allowed range, and keeps Save and Discard in a bar while there are edits; Reset to defaults puts every field back. About shows the running version and the update check.
- Tools page: connected apps first, then a library by category with one search across both, and a single dialog for connecting, signing in and retrying.
- Larger connector catalogue: 34 apps, built from the MCP Registry by
scripts/connectors/import_catalog.py, with categories. - Custom connector sign-in: a server added by URL that answers 401 gets browser sign-in when it publishes OAuth metadata, and a token prompt otherwise. Its own icon is fetched from its site and kept in
~/.aldwin/state/connector-icons/. - Long conversations: when a chat fills 60% of what the model can read, Aldwin makes room instead of forgetting. It shortens old tool results first, then writes itself notes on older messages with the model in use, and keeps the recent part word for word. After making room, the chat takes about 10% of what the model can read: the notes up to 4% (at most 4,000 tokens), the recent part the rest (at most 40,000 tokens). If the notes can't be written, it leaves the oldest messages out of the model's view and says so. Every message stays on screen, in
/historyand in search. - Make room now:
/compactin the terminal, and Make room now in the browser's context ring, do it on request. If the notes can't be written, it says so and changes nothing. recallin this chat:recalltakesscope="this_conversation"to find the exact words of earlier messages and tool results in the current chat.- When to make room:
limits.context_compact_percent(60 to 90, default 60), also under Settings, Advanced, as "Summarise older messages at". - Skill summaries: skills can carry a plain one-line
summary, which the@menu, Settings and/skillsshow instead of the description written for the model. The built-in skills all have one. - Protocol:
sessions.list,sessions.open,sessions.new,sessions.rename,sessions.pinandsessions.delete; apinnedfield on conversations;turn.appsandapps.used; typeddisplayon tool results; approvalcall_id;done.contextandhistory.context;compact; atopicon notices (roomwhen Aldwin made room); asummaryon skills; and REST routes under/v1, including conversation search andlimit_rulesin the settings. All additive to protocol v2.
Changed
- Shared home, two doors: the terminal and the browser run as separate processes on one home folder. A conversation is locked while a turn runs, so it answers in one place at a time.
- Settings reload before each turn, and writes to
config.yamlandsecrets.yamlare locked, so a change in one door applies in the other without a restart. - Approvals survive a dropped connection: a waiting approval can be answered after the browser reconnects; one asked while no page is attached is denied.
- Base instructions: finish the job, retry or change approach after a failure, respect a declined approval, and look up connector tools first.
- No 20-message memory: Aldwin no longer forgets everything older than the last 20 exchanges (8 on local models).
limits.context_exchangesis still accepted and ignored. - Steps per answer:
limits.max_stepsnow defaults to 50 instead of 15, with no upper limit. Aconfig.yamlthat already sets a value keeps it, and local models still stop at 15. - Hosted models: OpenAI-compatible providers (OpenAI, DeepSeek, OpenRouter) count as 128,000 tokens and Anthropic as 200,000 from the start of a run, so Aldwin can make room before the model list has been fetched.
- Local models: room is measured against the window Aldwin actually asks Ollama for, because Ollama cuts over-long requests silently.
- Docs: README, contributing, safety, privacy, commands, releasing, manual test and tests docs cover the browser.
SECURITY.mdnow says how to report a vulnerability.
Removed
- The terminal's "Context nearly full" notice: Aldwin now makes room on its own.
Fixed
- Long chats lost messages: when a provider refused a request as too long, Aldwin deleted the oldest exchange from the saved chat, so it vanished from the screen and from search, and the typed text of later messages shifted. Nothing is deleted now.
Security
aldwin webrefuses any non-loopback host. Every/v1route checks the session cookie,Host,OriginandSec-Fetch-Site.- The session cookie is HttpOnly and SameSite=Strict, and the token is removed from the address bar after sign-in.
- The WebSocket needs a single-use ticket that lasts 30 seconds, and only one browser tab is connected at a time.
- API keys saved from the browser are checked with the provider first and only ever returned masked.
- Connector icons are fetched without credentials, from the app's own host or parent domain only, and served with a sandboxing CSP.
- Aldwin's notes on a long chat are written with no tools, framed as background rather than instructions, and have secrets redacted. A file read only in the older part of a chat must be read again before Aldwin edits it.
Upgrade notes
- Upgrading from
0.0.5keeps sessions, notes, memory index, approvals, connectors, persona, keys, and settings. No home migration runs. - Run
uv tool upgrade aldwin, thenaldwin web. - Homes made by
0.0.5havemax_steps: 15inconfig.yaml, and it is kept. To use the new default of 50, change Steps per answer under Settings, Advanced.
Known limitations
- The browser interface only opens on the computer running
aldwin web. - No attachments, dictation, or editing of sent messages in the browser.
- The workspace cannot be changed from the browser; restart with
--workspace. - Tool displays are live only: after a reload, past tool rows are plain.
- Windows is not supported. Local MCP servers remain unsupported on Windows.
- Aldwin makes room before each message, not in the middle of one long task.
- A hosted OpenAI-compatible model that holds fewer than 128,000 tokens can refuse a long chat before Aldwin makes room for it.
Aldwin 0.0.5
What's Changed
- feat(search): add SearXNG provider and shared factory (ENG-559) by @folathecoder in #70
- chore(search): drop DuckDuckGo from search catalogue (ENG-560) by @folathecoder in #71
- feat(cli): add /copy to put the last answer on the clipboard by @olayinkags in #72
- feat(search): add hosted search providers and /search connect (ENG-561) by @folathecoder in #73
- chore(release): prepare Aldwin 0.0.5 (ENG-562) by @folathecoder in #74
New Contributors
- @olayinkags made their first contribution in #72
Full Changelog: v0.0.4...v0.0.5
Aldwin 0.0.4
[0.0.4] - 2026-11-05
Aldwin can use any first-ship model provider, including local servers — no OpenAI lock-in.
Added
- Any model, including local: switch between cloud and local providers with
/model. Built-in catalogue (bundledproviders.yaml, no online lookup): Ollama, LM Studio, OpenAI, Anthropic, Google Gemini, OpenRouter, and DeepSeek. - Local-first first run: on launch Aldwin probes Ollama and LM Studio. Path A uses a found local model with no account; Path B offers cloud or install steps; Path C keeps an existing OpenAI setup with no reconfigure.
- Three HTTP translators (no vendor SDKs): OpenAI-compatible chat, Anthropic Messages, and Ollama native — plain
httpxonly. - Key store: environment variables win and are never written to disk; pasted cloud keys are checked against the provider before save; secrets stay in
~/.aldwin/secrets.yaml(0600). - Friendly provider errors: Agentling error kinds map to copy that names the provider and what to do next, with branded retry status lines.
- Protocol doors:
models.list,provider.key, andprovider.serverfor listing models, saving keys, and registering Other server entries underproviders:inconfig.yaml. - Other server: add any OpenAI-compatible (or Anthropic/Ollama-shaped) endpoint via
/modelorproviders:(shape,local,base_url,secret,title).
Changed
- Agentling 0.2: depends on
agentling>=0.2,<0.3from PyPI; the OpenAI Python SDK is not a dependency. - What's-new and tip: upgrade panel explains any model including local; tip says "Switch between cloud and local models any time with /model."
- README and docs: "Run it fully local" quickstart, first-ship provider table, Fully local privacy, provider-neutral protocol error wording.
Removed
- OpenAI-only product wording from the README and release messaging (OpenAI remains a first-ship cloud option).
Security
- Provider keys follow env-wins and check-then-save; pasted keys are validated before persist.
- Local model traffic on loopback does not leave the machine (except optional web tools, remote connectors, and the PyPI update check).
- No
openai/anthropicvendor SDK packages in the install (size and supply-chain).
Upgrade notes
- Upgrading from
0.0.3keeps sessions, notes, memory index, approvals, connectors, persona, and settings. No home migration runs; bare model ids still resolve asopenai/<id>. - Run
uv tool upgrade aldwin. OpenAI users keep working (Path C).
Known limitations
- First-ship providers only in the built-in catalogue; other backends use Other server /
providers:. - Windows is not supported. Local MCP servers remain unsupported on Windows.
Sizes
- Wheel and installed size: record after TestPyPI / CI (budget ≤120 MB installed, no extras).
Aldwin 0.0.3
Aldwin can now connect to your other apps through MCP servers, and warns you when it detects a secret in your message.
Added
- Connectors: connect Aldwin to Notion, Linear, GitHub, Context7, and other apps with
/connectors. Each connector is an MCP server that adds tools to the current session.- Catalogue: pick a service from the built-in list and sign in through your browser; Aldwin handles the OAuth flow and stores the token at
~/.aldwin/credentials/<name>.json(mode 0600). - Custom URL: paste any remote MCP server URL that is not in the catalogue.
- Local servers: run any MCP server from a shell command; the command is shown for approval before it starts, and re-approved after any hand edit. Local servers are not supported on Windows.
- Import:
aldwin connectors importreads connector configs from other agent apps on your machine and adds compatible entries. - Ask Aldwin to connect: type "connect me to Notion" and Aldwin proposes the right connector for you to approve.
- On-demand tool loading: tools are loaded from the server only when the model needs them. Up to 40 connector tools can be active at once;
/newclears the loaded set. - Trust toggle: control whether a server's read-only tools run on Auto or always ask first.
- Catalogue: pick a service from the built-in list and sign in through your browser; Aldwin handles the OAuth flow and stores the token at
- Pasted-secret warning: Aldwin detects patterns that look like API keys, tokens, or passwords in your message before it is sent to the model. Confirmed messages have the detected text redacted in the session file and in
logs/approvals.jsonl. mcpversion in--version:aldwin --versionnow reports the installedmcpSDK version, for examplealdwin 0.0.3 (protocol v2, agentling 0.1.1, mcp 2.3.0).
Fixed
- The
set_personatool always stated the persona limit as 2,000 characters even whenlimits.persona_charswas set lower. The tool now states the configured limit. /memoryalways said "Notes in the last 7 days" regardless of thelimits.notes_dayssetting. The count and label now follownotes_days./toolslabelled every tool that needs approval "(always asks y/n)". Each tool now shows a note that matches its actual approval tier.- Setting
theme: lightortheme: colour_blindin~/.aldwin/config.yamlhad no effect. The configured theme is now applied. - The "Stopped after N steps" notice always said 15 regardless of
limits.max_steps. It now shows the configured limit. - Some invalid
config.yamlvalues produced garbled errors. Key fields now produce clear, human-readable messages. - Running
aldwinfrom a folder that had been deleted after youcd-ed into it crashed with a traceback. Aldwin now falls back to~/aldwin_workspace.
Security
- Aldwin warns and asks for confirmation when it detects a secret-looking pattern in your message. Confirmed messages are redacted in the session file and
logs/approvals.jsonl. - Connector sign-in tokens are stored at
~/.aldwin/credentials/<name>.json(mode 0600) and never passed through the model. - Local MCP server commands are shown for approval before they start and re-approved after any hand edit.
- Connector tool output is wrapped as untrusted data, the same as file and command output.
Upgrade notes
Upgrading from 0.0.2 or 0.0.2.1 keeps all your sessions, notes, memory index, persona, and settings. No migration runs on first launch:
uv tool upgrade aldwinThere is no connectors.yaml or credentials/ folder until you add a connector with /connectors.
Known limitations
- Local MCP servers run with your user's rights; there is no sandbox. A server can mark a write tool as
readOnlyHint: true, and Aldwin trusts that hint. - Only macOS 13+ and Linux are supported. Local MCP servers are not supported on Windows.
Full changelog: https://github.com/lunarstack-co/aldwin/blob/main/CHANGELOG.md
Aldwin 0.0.2.1
[0.0.2.1] - 2026-10-25
Fixed
- Running
aldwinfrom the home directory, or from any folder that cannot be a workspace (/, or inside~/.aldwin), crashed with a traceback. Aldwin now creates and uses~/aldwin_workspacefor that session, shown in the welcome panel asworkspace: ~/aldwin_workspace. Pass--workspace PATHor start Aldwin inside a project folder to choose a different root.
Changed
- The one-time What's new panel is keyed to the feature release (
major.minor.micro), so a patch release such as this one does not show the0.0.2panel a second time.
Security
- Upgraded the pinned
certifito2026.10.23. Earlier releases bundled emSign root CAs whose intermediate CA keys were compromised (GHSA-6q48-6c7w-9gw2);web_fetchanddownload_fileverify TLS against this bundle.
Aldwin 0.0.2
[0.0.2] - 2026-10-30
Aldwin now works with your files and documents, knows good habits out of the box, and lets you pick a skill with @.
Added
- File tools with diff approval:
list_dir,glob,grep,read_file(read-only);edit_fileandwrite_file, each shown as a folded diff before anything is written to disk. - Document reading:
read_documentconverts PDF (page-range selection withpages=), Word, PowerPoint, Excel (sheet=by name or index), CSV/TSV, and HTML to markdown.download_filesaves a public URL into the workspace after approval. - Planning tools:
todokeeps a checklist for jobs of three or more steps, shown as a live view in the CLI;calculatedoes exact arithmetic and ISO date maths without a shell. - Upgraded memory:
recallnow does ranked search across notes and past conversations; notes can be corrected in place (replace=) or removed (forget, after diff approval) instead of only growing. - Nine packaged default skills (
using-aldwin,files,markdown-notes,documents,making-documents,web-research,memory,terminal,skill-creator) loaded from the install viaimportlib.resources; user skills under~/.aldwin/skills/<name>/override by name. @skill picker: type@to insert a skill into the turn;/skillsandaldwin skillslistname · source · descriptionwithdefault/user/user overridelabels, and/skills show <name>prints a skill's effective body.create_skilltool (diff approval, never session-grantable) to write or update a user skill; the host rebuilds the agent after the turn and showsskills reloaded.aldwin[docs]optional extra (python-docx,openpyxl,reportlab) for themaking-documentsskill to write Office files viarun_command.aldwin[office]optional extra (mammoth,python-pptx,openpyxl) for reading.docx,.pptx, and.xlsx. It is left out of the default install to keep the installed size within budget; without it,read_documentsays how to enable those formats. PDF, CSV/TSV, and HTML always work.- Protocol v2 (
hello(v_min, v_max)negotiation): a v2 door gets Diff-tier approvals with digests; a v1 door still completes a turn with plain y/n approvals, and any Diff-tier call from a v1 door is refused as unapprovable rather than silently downgraded. - New slash commands:
/todo(checklist view),/skills(catalogue andshow),/verbose(toggle file-tool previews),/workspace(inspect or change the workspace root). - One-time What's new panel on the first everyday launch after an upgrade, and three new idle tips pointing at the file, document, and skill-picker workflows.
- PyPI update-available nudge: a muted one-line notice under the welcome card when a newer
aldwinis published, opt out withcheck_for_updates: false.
Changed
- Policy engine: every tool call now goes through a deterministic three-tier approval pipeline (session-grantable, per-call y/n, and Diff approval that can never be session-granted) with a hard floor that denies outright before any tier is even offered.
run_commandruns with a clean, minimal environment. Secrets and API keys are no longer visible to spawned commands by default; extra variable names to pass through are opt-in viarun_command.env_allowinconfig.yaml(secret-looking names are always ignored).run_commandalways asks, with No as the default answer, and refuses outright (no prompt) a short list of privilege-escalation, interactive-program, and bare-REPL commands, and anything naming a blocked path (see Security).- Default skills are no longer copied into
~/.aldwinon first run; upgrades improve packaged skills automatically. - Skills never load code: a
tools:frontmatter key is stripped (flagged astools removedfor user skills).
Security
- Hard floor, fail closed: a fixed set of paths that commonly hold secrets (
.ssh/,.aws/,.gnupg/,.kube/,.docker/config.json,*.pem/*.key/*.p12/*.pfx, SSH private keys,.netrc,.pgpass,.npmrc,.pypirc,.git-credentials,.env*, and~/.aldwin/itself) is never readable, writable, or passed torun_command, with no config override (except read-only~/.aldwin/tmp/**forread_file). This check runs before any approval tier and cannot be session-granted away. - Approvals bound to what was shown: a Diff-tier approval carries a
sha256digest over the tool name, resolved arguments, and the diff text; if the file or digest changed since the diff was shown, Aldwin re-confirms once rather than applying a stale approval. - Every tool result is wrapped as
<untrusted>before it reaches the model, so text read from a file, page, or command output is never treated as an instruction. - Approvals log: every policy decision (approved, denied, blocked, refused) is appended as one redacted JSON line to
~/.aldwin/logs/approvals.jsonl, rotated at 10 MB. - Clean command environment: see
run_commandabove.
Upgrade notes
- Upgrading from
0.0.1runs an automatic, idempotent migration on first launch:config.yamlis backed up toconfig.yaml.bak-0.0.1(once), gainsrun_command.env_allow: []with every existing value and comment preserved,tmp/,state/, andlogs/are created or repaired to0700, andmemory/index.sqliteis built from existing notes and sessions. Nothing in~/.aldwinis deleted. A second launch is a no-op. - A command that used to see
$OPENAI_API_KEY(or any other secret-looking variable) under0.0.1no longer does; add its name torun_command.env_allowif a command genuinely needs a non-secret variable passed through. - An unmodified
0.0.1starter copy of~/.aldwin/skills/using-aldwin/is renamed tousing-aldwin.old-0.0.1/so the new packaged identity block takes effect; an edited copy is kept as a user override. - The one-time What's new panel shows once on the first launch after upgrading, then never again for that version.
Known issues
- A workspace file's contents could, in principle, be read by Aldwin and included in a URL it is asked to fetch. Review
run_commandandweb_fetchapprovals for anything that forwards file contents externally. - A hard link inside the workspace pointing to a file outside it can resolve as if it were inside, letting a file read skip the outside-workspace approval step; its own filename is still checked against the blocked-path list.
run_command's refusal checks parse the command as text, not a real shell grammar; unusual quoting or encoding could in principle evade a check meant to catch it.
Sizes
- Wheel: ~0.23 MB. Installed (no extras): ~116 MB on macOS arm64; confirmed within the 120 MB budget on Linux x86_64 (Python 3.11, 3.12, and 3.13) in CI. With
aldwin[office]: ~131 MB on macOS arm64.
Aldwin 0.0.1
Changelog
All notable changes to Aldwin are documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
0.0.1 - 2026-11-01
First public release of Aldwin: an open-source personal assistant that runs on your own computer, in your terminal, built on Agentling.
Added
- One-command install:
uv tool install aldwininstalls thealdwinCLI (aldwin,aldwin setup,aldwin uninstall [--purge],--version,--plain,--debug). - Private local home folder (
~/.aldwin): created on first run with mode0700(overridable viaALDWIN_HOME), atomic file writes (fsync+os.replace), rotating file logs (logs/aldwin.log,1 MB × 3) with secret redaction and no message content logged, and separatesecrets.yaml(0600) with environment-variable priority (OPENAI_API_KEY,TAVILY_API_KEY). - First-run onboarding & setup: guided terminal setup that prompts for an OpenAI API key with hidden input, verifies it against OpenAI, optionally configures a Tavily web search key, and saves a default chat model.
- One brain, many doors architecture: typed Pydantic v2 protocol (
aldwin.protocol), in-processasyncio.Queuehost (aldwin.host), client SDK (aldwin.client), and CLI door (aldwin.cli) with strict architectural isolation (clinever importscoreoragentling). - Agentling + OpenAI core: streaming responses, automatic exponential-backoff retries on transient OpenAI errors, dynamic context manager keeping the last 20 exchanges on clean turn boundaries, and user-extensible Markdown skills in
~/.aldwin/skills/<name>/SKILL.md(shipping with theusing-aldwinstarter skill). - Five built-in tools:
web_search: web search via Tavily behind a swappableSearchProviderinterface.web_fetch: HTTP/HTTPS page extraction viahttpx+trafilatura(capped at 20,000 chars, wrapped as<untrusted>data, with DNS/IP SSRF blocking against localhost and private networks).run_command: shell command execution in the launch directory with mandatoryy/nuser approval, pre-execution refusal ofsudoand interactive programs, secret environment stripping (*_KEY,*_TOKEN,*_SECRET), 60-second timeout, and 10,000-char output cap.remember: appends a single-line dated note with metadata to~/.aldwin/memory/notes/YYYY-MM-DD.md(last 7 days injected into context, up to 4,000 chars).recall: keyword search across daily notes.
- User-controlled memory and persona:
~/.aldwin/memory/profile.md(user-editable only, up to 4,000 chars) and~/.aldwin/persona.md(up to 2,000 chars, updated viaset_personaonly after explicity/nuser approval). - Session persistence & recovery: conversations saved atomically to
~/.aldwin/sessions/<YYYY-MM-DD>_<id>.jsonafter every step; reopeningaldwindisplays the last 20 messages and resumes where you left off, with an interrupted-turn notice if the previous terminal closed mid-task. - Inline terminal UI: built with Typer, Rich, and
prompt_toolkitin native terminal scrollback, featuring fence-aware streaming Markdown, live spinner and status bar, tool cards, bordered approval prompts with terminal bell,Escmid-turn stop within 1 second,?keyboard shortcut guide, plain mode (--plain/NO_COLOR), and slash commands (/help,/new,/model,/persona,/memory,/skills,/tools,/exit).
Known limitations
- Terminal only, not always-on yet: Aldwin
0.0.1runs inside your terminal process. Closing the terminal stops the active task (your conversation is saved after every step and resumes next time you runaldwin). Background daemon mode over~/.aldwin/aldwin.sockarrives in0.1. - OpenAI API key only: requires your own OpenAI API key (
OPENAI_API_KEYor configured on first run). Other model providers and account OAuth are not included in0.0.1. - Fixed built-in toolset: includes the five built-in tools (
web_search,web_fetch,run_command,remember,recall); custom code tools cannot be added in0.0.1(drop-in Markdown skills in~/.aldwin/skills/are supported). - macOS and Linux only: requires Python
3.11+on macOS or Linux. Windows is not supported yet.