Install AbstractFramework

Most people want AbstractFramework running on their own computer with nothing to set up by hand. That is what the installer does: one download or one line, no admin password, and at the end AbstractFramework opens in your web browser, already signed in. Developers who want the Python libraries in their own environment go to Install the Python framework.

Install on a Mac

You need a Mac with macOS 13 or later (Apple Silicon gets the fast local engines; they need macOS 14), an internet connection, and free disk space before models: the installer warns below 8 GB on Apple Silicon (the apple profile) and 1.5 GB on an Intel Mac (light), plus 0.3 GB with --with-apps and 0.7 GB when it installs Rust for the terminal console, and stops below 1 GB.

Download AbstractFramework-Installer.pkg (attached to every GitHub release).
Allow it once. The package is not signed with an Apple Developer ID, so the first double-click shows a warning that macOS cannot verify the installer ("… Not Opened", "Apple could not verify …" or "… from an unidentified developer", depending on your macOS version). Close the warning (Done or OK), open System Settings > Privacy & Security, scroll down to Security, click Open Anyway next to the installer's name, and confirm (macOS may ask for your login password or Touch ID). This is the standard macOS step for software from outside the App Store; you do it once per download.
Install. The macOS Installer opens. Click Continue, then Install. It installs for you only, so the Installer does not ask for your password.
A Terminal window opens and shows each step as it happens. It asks one question:
```
? Start AbstractFramework automatically when you log in? (a per-user login item, no admin; the uninstaller removes it) [Y/n] (Enter = yes)
```
Press Return for yes (recommended: it is then always there when you need it), or type n. You can change it later with the Start at login switch in the console.
Wait 2 to 15 minutes, depending on your connection. The last lines say AbstractFramework is ready. and your browser opens AbstractFramework.
In the browser, the first-run guide helps you pick an engine (it detects what this Mac can run and installs it with one click) and a model that fits your Mac. You can close the Terminal window.

Afterwards, AbstractFramework is at http://127.0.0.1:8080/console (bookmark it), and its icon in the menu bar opens it and shows its status.

What it puts on your Mac, all inside your home folder: uv and a private Python 3.12 in ~/.local, the AbstractFramework gateway (about 2.4 GB on Apple Silicon, with the MLX engines), uv's download cache (about 2.4 GB, reused by upgrades), your data in ~/Library/Application Support/AbstractGateway, and, if you said yes, a login item (~/Library/LaunchAgents/ai.abstractframework.gateway.plist). Models you download later come on top.

The package also leaves two double-clickable files in ~/Library/Application Support/AbstractFramework/Installer: Install AbstractFramework.command (double-click it again to upgrade or repair: it runs the latest installer) and Uninstall AbstractFramework.command. See Upgrade.

Or: paste one line in Terminal

On macOS and Linux, open Terminal, paste this line and press Return:

curl -LsSf https://abstractframework.ai/install.sh | sh

It asks the same start-at-login question in your terminal: press Return for yes or type n. With no answer within 25 seconds it leaves start at login off, so an unattended run never waits. Everything else is the same as the Mac package above. On Linux the login item is a systemd --user service and the data lives in ~/.local/share/abstractgateway.

Run from a script, a provisioning tool or CI (no terminal to ask on), the installer asks nothing: start at login stays off on a first install (a re-run keeps what you chose before), and the summary says how to turn it on. --no-service always leaves it off and asks nothing.

Windows

Windows 10 22H2+ / 11: open PowerShell, paste this line and press Enter:

powershell -ExecutionPolicy ByPass -c "irm https://abstractframework.ai/install.ps1 | iex"

It installs under your user account (no administrator rights) and opens AbstractFramework in your browser. It asks whether to start AbstractFramework at sign-in, like the Mac and Linux installer: Enter = yes, no answer within 25 seconds (or no console to ask on) leaves it off on a first install. -NoService leaves it off and asks nothing.

What runs locally on Windows with the gpu profile (x86_64, NVIDIA):

Engine	On Windows
llama.cpp (GGUF models, in the gateway)	Yes: the installer adds llama.cpp's prebuilt CUDA, Vulkan or CPU build.
Hugging Face Transformers	Yes, on PyTorch's CUDA build.
Diffusers (image generation), faster-whisper (speech to text), sentence-transformers	Yes.
Ollama, LM Studio	Yes: install them from the console's Local engines page (or `-WithOllama`, `-WithLmStudio`).
vLLM	No native Windows build: run it in WSL2 or on a Linux machine, and point the gateway at that server.
MLX	Apple silicon Macs only.

Agents' shell commands need a sandbox, and Windows has none that the gateway supports, so the gateway refuses those commands on Windows; every other tool works. AbstractGateway's security guide explains abstractgateway serve --unsandboxed-commands, which runs them with your account's own file access, for a gateway you start yourself.

If something goes wrong

The installer stops at the first problem, says what happened in plain words, and says what to do. It never leaves a half-finished install behind that a second run cannot fix: after fixing the cause, run it again (double-click the installer again, or paste the line again) and it continues where it stopped.

What you see	What to do
`no internet connection: the installer could not reach pypi.org`	Connect to the internet, then run the installer again. Nothing was changed.
`cannot reach pypi.org through the proxy set in your environment (…)`	Your computer is set up to use a proxy that does not answer. Fix the proxy (or remove the `HTTPS_PROXY` setting), then run it again.
`… failed because the internet connection dropped`	Reconnect and run it again; it continues where it stopped.
`this Terminal runs in Intel (Rosetta) mode on an Apple Silicon Mac`	Quit Terminal. In Finder open Applications > Utilities, select Terminal, choose File > Get Info, untick Open using Rosetta, then run the installer again. (Double-clicking the installer restarts itself in the right mode on its own.)
`the folder … belongs to 'root', so the installer … cannot write there`	An earlier command was run with `sudo`. Run the `sudo chown -R …` line the message shows (it asks for your password once), then run the installer again.
`macOS … is older than the versions AbstractFramework is tested on`	A warning, not a stop. If the install then fails, update macOS in System Settings > General > Software Update.
`the Apple Silicon engines (MLX) need macOS 14 or later`	You get the light version (remote and endpoint engines). Update macOS and run the installer again to add the local engines (a light install made by 0.10.0 or older keeps light on a re-run: add `--profile apple`).
`the installed gateway does not start … reinstalling it`	Nothing to do: an earlier install was interrupted and the installer repairs it.
`the gateway did not answer … within 180 s`	Restart the computer (the login item starts it) or run the installer again, then open `http://127.0.0.1:8080/console`.
The browser page asks for a token	The one-time sign-in link lasts 10 minutes. Run the installer again: it opens a fresh link.
`another AbstractFramework installer is already running`	An installer, or an Update from a console or the menu-bar icon, is running for this data directory. Wait until it finishes, then run the line again.
`PyPI hasn't published abstractgateway 0.8.1 to every mirror yet; retrying in 30 s (attempt 3/8)`	Nothing to do: a release published minutes ago has not reached every PyPI mirror yet. The installer waits and runs the same install again (see Right after a release).
`PyPI lists … but still does not serve its file after 8 attempts over about 10 minutes`	The package list shows the version but the file host has not served its file for 10 minutes. Nothing was left out and the previous install is unchanged. Run the installer again in a few minutes (the message ends with the exact command).
`PyPI still does not list … after 8 attempts over about 10 minutes`	The package index this computer reads has not caught up after 10 minutes (often a company package mirror set in `UV_INDEX_URL`, `PIP_INDEX_URL` or `uv.toml`). Nothing was left out and the previous install is unchanged. Run the installer again in a few minutes (the message ends with the exact command); with a mirror, ask its administrator to refresh the package the message names.
`a network error while downloading (uv: HTTP status server error (502 Bad Gateway) …); retrying in 15 s (attempt 2/8)`	Nothing to do: a download failed on the way (a server error, a rate limit, a dropped or reset connection, a timeout). The installer runs the same install again, with every part (see Right after a release).
`… failed: a network error while downloading, still failing after 8 attempts over about 10 minutes`	The network (or the proxy) kept failing for 10 minutes. Nothing was left out and nothing was changed: the gateway you had is still installed and still works. Check the connection, then run the command the message ends with (the same command, same options).
`crates.io hasn't listed it yet (…); retrying in 15 s`	Nothing to do: the terminal console or `abstractcode` was published minutes ago and crates.io's index has not caught up; the installer builds it again.
`NOT installed:` at the end, in red	Something was left out, and the line says what and why. For `terminal console` or `AbstractCode's terminal client` (crates.io or the network still failing after 10 minutes; exit code 1) run the command shown again later; the gateway is installed and running. For `local voice` this system cannot run it (no wheels for it); the rest is installed.
`port N (the gateway's Network setting) is already in use by another process`	The port you chose in a console (or the tray) is taken by another program. Stop that program, or choose another port with `--port` (Windows: `-Port`); it becomes the Network setting's port.
The gateway stopped answering for a while, then came back; its log shows `[FATAL] gateway watchdog` (exit code 75)	Nothing to do: the gateway's event loop was blocked, so it wrote the stack of the code that blocked it to its log and exited, and was started again (by the LaunchAgent or systemd service, by the installer's background mode, or by the `scripts/start-local.sh` supervisor). Report it with the `[FATAL]` lines of the log (macOS: `~/Library/Logs/AbstractGateway/gateway.err.log`; background mode: the gateway log the installer names; Linux service: `journalctl --user -u abstractgateway`). A gateway started by hand in a terminal is not restarted. `abstractgateway serve --watchdog-seconds N` sets the limit (default 30, `0` = off).
Anything else	Run the installer again. If it stops at the same step, report it with the log file named at the end of the message (`~/Library/Application Support/AbstractGateway/logs/install-….log`).

Right after a release

For a few minutes after a release, some of PyPI's mirrors can still serve a package list without the new versions. uv then answers there is no version of abstractgateway==0.19.0 even though the release is published. The installer (install.sh and install.ps1; the Update action of the consoles and the menu-bar icon runs install.sh on macOS and Linux, and gives the install.ps1 line to paste on Windows) treats that as a delay:

it runs the same install again, with every part it was asked for (local voice, llama.cpp, PyTorch's CUDA build): a delay never makes it install less;
it waits 15 s, 30 s, 60 s, then 120 s between attempts, 8 attempts over about 10 minutes, and says so: PyPI hasn't published abstractgateway 0.8.1 to every mirror yet; retrying in 30 s (attempt 3/8);
if the version is still missing after that, it stops with the cause and what to do, ending with the exact command to run again. uv stops before it changes anything, so the previous install keeps working.

Only these cases wait, for a package at the exact version this release pins (the gateway and the release's libraries: AbstractCore, AbstractRuntime, AbstractVoice, ...): uv exits with code 1, its output contains uv's resolution failure (No solution found when resolving dependencies) and it says there is no version of <package>==<version>; or the download of that version's own file answered HTTP status client error (404 (Failed to fetch: .../<package>-<version>-py3-none-any.whl: the package list already shows the new version but the file is not served yet; uv exits with code 1, or 2 when even the file's metadata answered 404). The voice requirement carries its pinned version for this reason. An install with --pin latest or --from pins nothing, so no version is waited for.

A network failure is handled the same way, on any download: the same full install runs again on the same waits, then the installer stops (exit code 1) with uv's cause and the command to run again; it never installs less because of the network. uv changes the gateway's environment only after every download succeeded, so a failed upgrade leaves the previous gateway installed and working. A network failure is any uv failure that names one of: an HTTP server error (HTTP status server error (5…), a rate limit or request timeout (429, 408), Request failed after N retries (uv's own retries ran out), Failed to download distribution due to network timeout, a DNS, connect, reset, refused or closed connection, a body cut off mid-download, or a plain Failed to download / Failed to fetch with no other cause. These are never retried: uv's resolution failure (No solution found when resolving dependencies, e.g. has no wheels with a matching platform tag), a failed source build, a broken file (hash or CRC mismatch, an invalid wheel) and an HTTP 4xx other than 408/429 that is not the index lag above. The installer's comment above AF_UV_DETERMINISTIC lists the exact strings and the uv version they come from.

Only such a deterministic failure takes the soft paths: a system without the voice engine's wheels (onnxruntime … has no wheels with a matching platform tag) installs without local voice, and says so in red: in the warning (with uv's reason), in the summary's first line (… but NOT everything was installed:), on the Voice: line, and in the last lines of the output (NOT installed:); the data directory's bootstrap.env records the reason as VOICE_SKIPPED=. The llama.cpp wheel works the same way.

The terminal console and abstractcode are built with cargo install --version <pin>. Right after their publish, crates.io's index can still answer could not find `abstractcode` in registry `crates-io` with version `=<pin>` ; that, and cargo's network failures (spurious network error, failed to get successful HTTP response … got 502, Couldn't connect to server, ...), get the same waits. When they run out, the rest of the install goes on (the gateway is installed and started), the summary says in red which one was not built and why, and the installer exits with code 1. A compile error is not retried. The browser apps are not installed by the installer: the gateway's Apps page downloads them from the npm registry when you choose Install (the latest published version), and says so when the registry cannot be reached; press Install again then.

Upgrade

Upgrade everything (recommended)

The line you installed with also upgrades and repairs. Run it again:

curl -LsSf https://abstractframework.ai/install.sh | sh

From a gateway 0.15.6 or later, the same upgrade is one command of the gateway, with a preview of what changes first:

abstractgateway update --check   # what would change: each package installed -> new, and the release notes in between
abstractgateway update           # the preview, one confirmation, then the installer runs and restarts the gateway

update --check exits 0 when you have the newest release and 10 when an update exists, so a script can use it. update runs the same install.sh as the line above (sha-checked, with --yes, --no-open, --no-modify-path and this install's data dir), keeps your port, profile and login choices, and restarts the gateway service itself. A gateway that runs from a source checkout, a container or a plain pip install is told how to upgrade instead. abstractgateway --update is the same command.

On Windows:

powershell -ExecutionPolicy ByPass -c "irm https://abstractframework.ai/install.ps1 | iex"

On a Mac without Terminal, double-click Install AbstractFramework.command in ~/Library/Application Support/AbstractFramework/Installer again. It downloads and runs the latest install.sh, the script of the one line, so it upgrades the same way. When GitHub cannot be reached, it runs the copy of the installer it came with and says so. Installing the latest AbstractFramework-Installer.pkg again does the same.

The line always runs the installer of the latest AbstractFramework release. It:

finds the existing install and says what it does. An install made by 0.6.2 or later recorded its release, so the line names it: AbstractFramework <yours> found: upgrading to AbstractFramework <latest>, or AbstractFramework <yours> found: already up to date (every part is still checked, and repaired when needed). An install made by 0.6.1 or earlier recorded no release, so its first upgrade says AbstractFramework found (abstractgateway 0.7.1; its release was not recorded): upgrading to AbstractFramework 0.11.0 (with the gateway version you have);
installs the gateway version that release pins, and every library the gateway uses (AbstractCore, AbstractRuntime, AbstractAgent, AbstractSkill, AbstractMemory, AbstractSemantics and the voice, vision, music and 3D packages) at the exact version released and tested with it (Check your versions shows how to print the list);
rebuilds the terminal console (abstractgateway-console) and AbstractCode's terminal client (abstractcode) when the release pins newer versions, with the Rust toolchain from the first install;
keeps your profile, port, start-at-login choice, data directory (a custom --data-dir too), Network setting, settings, downloaded models and installed apps, and the options that change what is installed: --no-console, --no-code-cli, --no-core-cli, --no-tray and --full. It prints the options it kept. To change one, give the opposite option: --with-console, --with-code-cli, --with-core-cli, --with-tray or --no-full (Windows: -WithConsole, -WithCodeCli, -WithCoreCli, -WithTray, -NoFull);
restarts the gateway when anything in its environment changed, a library alone included, and leaves a running gateway alone when nothing changed. The macOS login item is restarted through launchd, a running Linux systemd --user service with systemctl --user restart, and a background gateway is started again. On Windows the installer stops the running gateway before it changes any file (Windows locks the files of a running program) and starts it again afterwards;
replaces a gateway of this install that you started yourself (it serves the same data directory) on its port, instead of moving to another port and starting a second gateway on the same data; a program that is not this install's gateway keeps the port, and the installer takes the next free one. The installer signals only a process of your user running abstractgateway serve for this data directory; a stale gateway.pid or serve record naming another program is left alone. On Windows with start at login on, the installer cannot tell which process the login item started, so a gateway of this data directory that you started yourself on the install's port is taken for the login item and left running (stop it, then re-run the installer, to have the login item's);
asks PyPI again for the packages it pins (uv tool install --refresh-package ...), so a release published minutes earlier installs without clearing uv's cache, and waits for PyPI's mirrors when they have not caught up yet (Right after a release);
keeps the port of the gateway's Network setting when you changed it in a console, the menu-bar icon or with abstractgateway network set: that port wins over the one the previous install recorded, the installer says so (port 18094: kept from the gateway's Network setting (bootstrap.env said 18095 …)) and records it. Only --port (Windows: -Port) changes it. When another program holds that port, the installer stops and says so instead of moving to another port;
retries a download that fails on the way (a server error, a dropped connection) with the same full install, and never installs less because of the network (Right after a release);
never leaves the gateway stopped: when the login item cannot be registered, the gateway starts in the background and the summary says how to turn start at login on;
ends with what changed, old -> new, under Changes (Changes: none when nothing moved), and Upgraded: AbstractFramework <yours> -> <latest> (Upgraded: AbstractFramework (not recorded) -> <latest> for the first upgrade of a 0.6.1 or earlier install) or Already up to date: AbstractFramework <yours>; nothing changed.

Upgrading from 0.6.1 or earlier

Installs made by AbstractFramework 0.6.1 or earlier recorded neither their release nor your install options. The first re-run says AbstractFramework found (abstractgateway <version>; its release was not recorded): upgrading to AbstractFramework 0.11.0, and reads your options from what is installed: whether the terminal console and abstractcode are there, whether the gateway has the tray extra and the AbstractCore commands, whether the compiled extras were built (--full), and a custom data directory through the gateway pointer. It prints what it found (read from disk: …) and records it for later runs. An option the installer did not have yet when that install was made was never a choice, so it takes today's default instead: the terminal console for installs before AbstractFramework 0.5.0 (gateway 0.6.0), abstractcode and the AbstractCore commands for installs before 0.6.1 (gateway 0.7.1); the installer dates the install by the gateway version it recorded and says (no such option before gateway <version>'s installer: today's default, on). You can also repeat your original options once on that first run. The Update button of gateway 0.7.1 and earlier cannot upgrade an installer install: re-run the line once, and from gateway 0.7.2 on Update runs the installer.

With --no-start (Windows: -NoStart) the installer upgrades without starting or restarting the gateway, and says when a restart is due. It keeps this install's port even when another program holds it.

One installer runs at a time for a data directory. A second one, for example the line re-run while a console's Update is running, stops with another AbstractFramework installer is already running and changes nothing; run it again when the first has finished. A run that was interrupted (a closed terminal, a crash) leaves a lock that the next run takes over by itself.

Open the terminal console

abstractgateway console (also abstractgateway --console) opens the terminal console signed in: it finds abstractgateway-console next to abstractgateway (the installer builds it there) or on PATH, and passes it this install's gateway address and admin token; --url and --token override them. Without the console it says how to get it (cargo install abstractgateway-console).

Upgrade only the gateway

A gateway release can reach PyPI before the next AbstractFramework release. To install the newest gateway with the same profile, voice and llama.cpp setup:

curl -LsSf https://abstractframework.ai/install.sh | sh -s -- --pin latest

On Windows:

& ([scriptblock]::Create((irm https://abstractframework.ai/install.ps1))) -Pin latest

--pin latest moves the gateway and its libraries to their newest releases on PyPI; --pin 0.7.1 installs one exact version. The libraries then follow the gateway's own requirements instead of the release's tested versions, and the install records no AbstractFramework release. The installer restarts the gateway as above. A later run without --pin returns every package to the versions the AbstractFramework release pins.

Do not use uv tool upgrade abstractgateway for an installer install. The installer installs an exact version (abstractgateway[<profile>,tray]==<version>), uv keeps that constraint, and uv tool upgrade answers Nothing to upgrade. uv tool install abstractgateway@latest does move to the newest version, but it replaces the whole install with the bare package: the profile extras, the local voice packages, the AbstractCore, voice, vision and music commands and the prebuilt-wheel overrides the installer added are gone. Use the installer.

From the console or the menu-bar icon

The gateway's Update runs the same installer as the line above. You find it in three places (and in the terminal as abstractgateway update, above):

the web console: Resources > Gateway > Version, then Check now;
the menu-bar icon: Check for Updates…;
the terminal console: F3, then u to check and U to update.

For a gateway installed by the AbstractFramework installer on macOS or Linux:

The check compares the AbstractFramework release you have with the latest one. It reads the release from the install manifest on the framework repository's main branch. The version line reads AbstractFramework <yours> · gateway <version> · AbstractFramework <latest> available.
Update to AbstractFramework asks you to confirm and shows exactly what runs:
- the address of the installer, https://abstractframework.ai/install.sh;
- the commit it comes from and the script's sha256;
- the command: /bin/sh install.sh --yes --no-start --no-open --no-modify-path --data-dir <data dir>.
The gateway runs exactly the script you confirmed, and refuses to run a different one.
The installer runs next to the running gateway: nothing is asked, start at login stays as it is, and every package moves to the release's tested versions. The web console shows its output live under Update log.
The result is one of three:
- installed: what moved (AbstractFramework <yours> -> <latest>, then the gateway and the libraries that changed), then a restart to finish (Restart gateway… in the web console, Restart Now in the menu-bar icon's dialog, R in the terminal console);
- already up to date: the installer changed nothing, and no restart is needed;
- didn't finish: the installer's exit code and the last lines of its log (the full log is the newest <data dir>/logs/install-*.log). The running gateway keeps running; re-run the line above to finish by hand.

On Windows, a running program's files are locked, so the gateway does not update itself. The check says which release is available and shows the PowerShell line to paste; that installer stops the gateway, upgrades and starts it again.

Update is for the gateway's admin only, and it runs on the gateway's own machine, also when you use a console from another computer or over SSH.

For a gateway installed with pip, pipx or in a virtual environment, the check compares with the newest abstractgateway on PyPI, and Update to … installs it in the background, keeping the apple, gpu and embeddings extras. It updates the gateway package only: not the terminal console, not AbstractCode's terminal client, not the apps. Restart the gateway to finish.

Restart the gateway

The installer restarts the gateway itself when anything changed, except with --no-start (the console's and the menu-bar icon's Update). A gateway updated while it runs keeps the previous version until its next start. To restart it now:

web console: Resources > Gateway > Restart gateway…; menu-bar icon: Restart AbstractGateway…; terminal console: R in F3;
terminal: abstractgateway network restart --force --token <admin token>;
Linux, start at login on: systemctl --user restart abstractgateway.

Running workflows pause at their next step and continue after the restart.

Upgrade the apps

The browser apps (Flow, Code, Observer, Continuum, Entity) are installed by the gateway, and the installer keeps them on the release: on every install and upgrade, once the gateway answers, each browser app the gateway has installed is brought to this release's version (--print lists the planned updates) through the gateway's own abstractgateway apps update <app> --version <version>, so the gateway's apps registry stays right and a running app restarts on the new version. It is a command-line call against the running gateway, signed in with <data dir>/auth/bootstrap-admin-token passed as a parameter (an ABSTRACTGATEWAY_AUTH_TOKEN in your shell, set for another gateway, is not used), so it works the same on a headless or terminal-only machine: no browser or web console is involved. The step starts only once the gateway's boot is over (/api/health no longer says "status": "starting"), waiting up to 60 s for a gateway that is still booting or slow to answer right after its start, and then up to 90 s for an app the gateway is still starting, so the update restarts it on the new version. The summary's Apps line lists each app's version; an app that could not be updated is listed in red with the command to retry, and the installer exits 1. A fresh install installs no app: the console's Apps page installs them.

An app's port may be held by a copy this gateway did not start. The gateway's own install is updated all the same, and what happens to the copy depends on what it is:

A leftover of a previous gateway run — the process runs a program under <data dir>/apps/, which only the gateway puts there (an app that outlived a stop or restart of the gateway, for example on a Linux server, and kept serving an older version). The installer stops it (its command line is checked again before each signal; SIGTERM, then SIGKILL after 20 s) and starts the updated install in its place with abstractgateway apps launch <app>; the Apps line says leftover of a previous gateway run (<version>, pid <pid>) stopped; <app> <version> started. If the leftover could not be stopped or the app did not start, the summary says so in red with the command to run. Gateways from 0.15.2 on do this themselves at every start and on every apps launch or apps update, so the installer's stop is only needed with an older gateway.
A copy not started by this gateway — anything else (an app run by hand with npx, a checkout, a process this system cannot inspect). It is left alone: the Apps line says RUNNING: a copy not started by this gateway, <version> on port <port> (pid <pid>) and, when that copy is not at this release's version, the summary shows it in red with what was checked and the pid to stop, then abstractgateway apps launch <app>.

The summary's last line then points at the apps (What to do for the apps: run the command given on their line above, then check them with: abstractgateway apps list …), not at a re-run.

When no gateway answers (--no-start while the gateway is stopped), the installer writes the release's versions to <data dir>/apps-upgrade.pending instead, and the gateway (0.11.1 and later) brings its installed apps to those versions when it next starts, then removes the file. The console's Update runs the installer with --no-start while the gateway is running, so its apps are updated right away.

The desktop Assistant is a Python app the gateway installs; the installer leaves it as it is. When npm has a newer version of an app, its card on the console's Apps page offers Update under Technical details. In a terminal:

abstractgateway apps list                # installed and latest version of every app
abstractgateway apps update code         # update one app; a running app restarts on the new version
abstractgateway apps install-tui code    # update the terminal version the Apps page installed

The terminal console and an abstractcode built by the installer are upgraded by re-running the installer.

Check your versions

abstractgateway --version                    # the installed gateway
uv tool list --show-version-specifiers       # the gateway uv tool and its pin ([required: ==0.17.0])
abstractgateway-console --version            # the terminal console
abstractcode --version                       # AbstractCode's terminal client
abstractgateway apps list                    # the apps: installed and latest
curl -LsSf https://abstractframework.ai/install.sh | sh -s -- --print-versions   # what the latest release installs

The web console shows the running gateway's version under Resources > Gateway > Version.

Remove AbstractFramework

Double-click Uninstall AbstractFramework.command (in ~/Library/Application Support/AbstractFramework/Installer after a package install), or paste:

curl -LsSf https://abstractframework.ai/uninstall.sh | sh

It asks before removing anything, then asks two more questions, both defaulting to no:

Also delete your AbstractFramework data? This cannot be undone. It deletes:

What	macOS	Linux
Gateway data: settings, users, chats, run history, artifacts, memory, the tray's preferences	`~/Library/Application Support/AbstractGateway`	`~/.local/share/abstractgateway`
The login item's logs	`~/Library/Logs/AbstractGateway`	(in the data dir)
The gateway's download cache (engine installers)	`~/Library/Caches/AbstractGateway`	`~/.cache/abstractgateway`
The Assistant's sessions, snapshots and preferences	`~/.abstractassistant`, `~/Library/Logs/Assistant/abstractassistant-*`	`~/.abstractassistant`
AbstractCode's login and preferences	`~/.abstractcode`, `~/.abstractcode-tui`	same

It keeps model weights and shared caches: ~/.cache/huggingface, ~/.abstractcore (its config and its downloaded models), ~/.abstractframework, ~/.cache/abstractvoice, and the models of LM Studio and Ollama. Delete those by hand if you want them gone.

Also remove uv, its Python and its download cache (about 2.5 GB)? Asked only when the installer is what added uv; answer no if you use uv for anything else.

It always removes the login item, including one turned on after the install (abstractgateway service enable or a console's Start at login switch) when it starts this install's gateway; a login item that starts another gateway is kept and the uninstaller prints the commands to remove it. On Linux it leaves lingering as it is (it never runs sudo) and, when lingering is on, prints sudo loginctl disable-linger <user> for you to run if nothing else needs it. It stops AbstractFramework and removes the gateway (and the Assistant, which lives in the gateway's environment), the terminal console and abstractcode, including an abstractcode that a gateway before 0.7.1 installed in <data dir>/apps/bin (that folder is removed when nothing else is in it). It also deletes the local gateway pointer, ~/.abstractframework/gateway.json, when it names this install's data directory. Stopping means the whole gateway process tree: after the login item is removed it waits up to 20 seconds for every gateway process to exit (the server, the tray, an entity's own-time loop, model downloads, the apps it started), then stops the rest, and says which processes it stopped. It keeps Ollama and LM Studio (they have their own uninstallers) and the one PATH line uv added to your shell profile. Without questions: sh uninstall.sh --yes (keeps data), add --purge to delete the data and --remove-uv to remove uv; --print shows every command and changes nothing. Windows: install.ps1 -Uninstall [-Purge].

If a folder cannot be deleted, the uninstaller stops with an error that names the folder, lists what is left in it and the programs that hold files there. Quit those programs (or log out and back in); on macOS, a file shown with the uchg flag is unlocked with chflags -R nouchg <folder>. Then run the uninstaller again: it skips what is already gone. Each deleted location is checked once more a second later; a program that starts writing there again after that is not detected (an uninstaller cannot outwait a writer it does not know). A --data-dir given by hand is purged only when it holds a gateway file (bootstrap.env, gateway.sqlite3, auth/users.json, ...) or the note a previous, interrupted purge left in it (.abstractgateway-purge-incomplete); the root, your home folder and any folder that contains it are always refused (exit 2, nothing changed).

Advanced: what the installer does

The Mac package, the .command files and the one line all run the same script, scripts/install.sh (Windows: scripts/install.ps1):

Checks the machine (OS, CPU, macOS 14+ for Apple Silicon, Rosetta, NVIDIA/ROCm, the folders it writes, internet access to PyPI, free disk, a free port) and picks a profile: apple on Apple Silicon (macOS 14+), gpu when nvidia-smi or rocminfo works, light otherwise. Free disk before models: it warns below 8000 MB for apple, 12000 MB for gpu and 1500 MB for light, plus 300 MB with --with-apps and (install.sh) 700 MB when it installs Rust for the terminal console; below 1000 MB it stops.
Asks whether to start at login, whenever a person is at a terminal (/dev/tty, so it also works through curl | sh). Enter = yes on a first install and the previous choice on a re-run; no answer within --ask-wait seconds (default 25) keeps the previous choice, or leaves it off on a first install. The double-click installers pass --interactive, which waits for the answer without a time limit. With no terminal (automation) or --yes nothing is asked: a re-run keeps the previous choice (the login item's own state, so a change made with a console's Start at login switch counts), a first install leaves it off.
Installs uv when it is missing, then Python 3.12 through uv.
Installs the gateway as an isolated uv tool, pinned to this release: uv tool install --python 3.12 "abstractgateway[<profile>,tray]==0.21.0", from prebuilt wheels only (see No compiler needed), and checks that the command starts (reinstalling it in place when it does not). Every profile also gets local voice, --with "abstractvoice[supertonic,stt]==0.21.1" (the release's AbstractVoice): Supertonic text-to-speech and Whisper speech-to-text, both on CPU (skipped on musl Linux and macOS before 13, where no wheels exist; Windows ARM64 gets Supertonic only). If those packages do not install on a system (for example glibc older than 2.28), the gateway is installed without them and the summary says so. A release that PyPI has not yet published to every mirror never causes that: see Right after a release. The same install puts AbstractCore's commands and those of its voice, vision and music packages on PATH next to the gateway's (--with-executables-from; --no-core-cli leaves them out): see Commands you get.
Builds the terminal console, abstractgateway-console, with cargo install --locked into the same folder as the abstractgateway command (crates.io has no prebuilt binary). When cargo is missing, macOS and Linux get Rust from rustup (minimal profile, in ~/.rustup and ~/.cargo, about 600 MB, shell profile untouched); Windows builds it only when Rust is already installed. It needs a C compiler; without one, or if the build fails, the installer says why and continues. --no-console skips it. AbstractCode's terminal client, abstractcode, is built the same way, with the same cargo, into the same folder (--no-code-cli skips it; under --no-console it is built only with a cargo already there). A failed build never fails the install: the installer warns once and prints the command to run by hand. Then, when asked for, Node.js for the browser apps, Ollama or LM Studio (flags below). See Commands you get.
With start at login on, registers the gateway with abstractgateway service install --port N (a LaunchAgent on macOS, a systemd --user unit on Linux, a per-user login entry on Windows) and starts it. The login item runs plain abstractgateway serve, so the gateway's Network setting decides where it listens. With start at login off (or --no-service, or on a Linux host without a user systemd session), it starts the gateway in the background instead and removes a login item an earlier run registered; the summary then says how to turn start at login on: the Start at login switch in either console (web: the Gateway section; terminal: F3), or abstractgateway service enable. Both restart a gateway that exits with an error after running, which is how a hung gateway ends (its event-loop watchdog exits with code 75): the login item through the service manager (KeepAlive with SuccessfulExit: false on macOS, Restart=on-failure on Linux), the background mode (install.sh) through a small loop that starts it again 10 s later, unless it was stopped (a signal, a clean exit, or gateway.pid removed) or failed in its first 30 s. The Windows login entry and the Windows background start do not restart it.
Waits up to 180 seconds for /api/health, then writes the local gateway pointer, ~/.abstractframework/gateway.json (Windows: %USERPROFILE%\.abstractframework\gateway.json): the gateway's address on this computer, its port and data directory, never a token. Clients on this computer that start without a gateway address (the Assistant, AbstractCode's terminal client, the browser apps' servers) read it to find a gateway on a port other than 8080. The installer always writes it for the install it just made, a custom --data-dir included (it replaces a pointer that names another data directory). abstractgateway serve keeps it current once bound, but only when the file is absent and it uses the default data directory, or when the file already names its data directory, so a test gateway never takes it over.
Opens http://127.0.0.1:8080/console through a one-time sign-in link (abstractgateway-config claim-url, valid 10 minutes, this machine only). If no link can be created, it shows where the admin token is. The summary shows both ways to configure the gateway (the web console link and the terminal console command) and where the browser apps open: http://127.0.0.1:8080/apps/<app>/ (the console's Apps page installs and opens them). On a remote or headless session (SSH, or Linux without a display) it offers the terminal console instead ("Press Enter within 25 s", signed in); no answer skips it, and --no-open or --yes skips the offer.

Every command is printed as it runs, and the summary lists them all. Re-running the script upgrades or repairs the install in place (see Upgrade). The macOS package is payload-free: it copies the two .command files into ~/Library/Application Support/AbstractFramework/Installer and opens install.sh --interactive in Terminal. It is built by scripts/lib/build_macos_installer.sh.

No compiler needed

By default the script never compiles a Python package, so you do not need Xcode Command Line Tools, gcc or the MSVC Build Tools for the gateway. Two parts do need one: the terminal console and AbstractCode's terminal client are built with cargo (crates.io has no prebuilt binary), and vLLM compiles its GPU kernels the first time it starts a model. Without a compiler the installer says up front that it will skip the first two and why, says it again in its summary, and gives the fix (sudo apt-get install -y build-essential on Debian/Ubuntu, xcode-select --install on macOS); the console's Code app also installs a prebuilt abstractcode. It passes uv a small overrides file (uv-overrides.txt in the gateway data directory; --print shows it) that swaps webrtcvad for webrtcvad-wheels, keeps vllm to Linux, and leaves out the two compiled extras below, and it refuses to build those packages from source, so a gap fails with a clear error instead of starting a compiler. If macOS asks you to install the command line developer tools (an xcode-select prompt) during an install, cancel the prompt, fetch the script again with the one-liner above and re-run it.

llama.cpp GGUF models

Every profile, light included, gets in-process llama.cpp GGUF support (llama-cpp-python). PyPI has only its source, so the script takes upstream's prebuilt wheel from abetlen's wheel index (--find-links on the package page, pinned in uv-constraints.txt next to the overrides file):

Machine	Wheel
Apple Silicon Mac	`llama-cpp-python==0.3.28`, Metal (GPU offload)
Linux x86_64 / aarch64 (glibc), light profile	`llama-cpp-python==0.3.35`, CPU
Linux x86_64, gpu profile with an NVIDIA GPU	`llama-cpp-python==0.3.35`: the CUDA build matching PyTorch's CUDA (below), else CPU
Windows x64, light profile	`llama-cpp-python==0.3.35`, CPU
Windows x64, gpu profile	`llama-cpp-python==0.3.35`: the CUDA build for the GPU stack (below), else Vulkan, else CPU
Intel Mac, musl Linux, Windows on ARM	no prebuilt wheel: skipped

Where no wheel exists, or when the wheel install fails, the script installs everything else and says GGUF (llama.cpp) skipped: no prebuilt wheel for this machine; --full then builds it from source. The summary's GGUF: line says which wheel was installed. On Apple Silicon the Metal wheel is pinned to 0.3.28, the newest Metal wheel on that index that passes uv's archive integrity check.

GPU on Linux (NVIDIA)

PyPI's PyTorch for Linux is already a CUDA build, so the gpu profile installs it as it is. After the install, install.sh asks nvidia-smi for the driver version and compute capability and checks, in the gateway's own environment:

that PyTorch sees the GPU (torch.cuda.is_available(), the device name and PyTorch's CUDA version); a driver older than PyTorch's CUDA needs is reported with the version it has;
llama.cpp: the install itself takes the CPU wheel (it never fails on a GPU detail); then the CUDA build matching PyTorch's CUDA is swapped in, cu130 for CUDA 13 (driver 580 or newer) or cu125 for CUDA 12 (driver 525 or newer). It uses the CUDA runtime and cuBLAS that PyTorch's NVIDIA wheels already installed (AbstractCore preloads them before importing llama.cpp), and it is kept only when it loads the way AbstractCore loads it and reports GPU offload; otherwise the CPU wheel goes back and the summary says why;
faster-whisper: which device AbstractVoice picks, and that CUDA 12 cuBLAS really loads for it.

The summary's PyTorch:, GGUF: and Voice: lines say what runs where. uv's output is shown as it comes, with a still working (… elapsed; last: …) line after 15 seconds of silence.

vLLM is part of the Linux gpu profile, and it is the one engine that needs a C compiler: Triton builds its GPU kernels the first time vLLM starts a model (sudo apt-get install -y build-essential on Debian/Ubuntu; the installer warns when none is found). On a GPU older than compute capability 8.0 (Turing: RTX 20xx, Quadro RTX, T4) start it with --attention-backend TRITON_ATTN: its default there, FlashInfer, compiles with the CUDA toolkit's nvcc, which a driver-only machine does not have.

Driver. PyPI's PyTorch for Linux (2.11 at this release) is a CUDA 13 build, which needs NVIDIA driver 580 or newer. With a driver from 525 to 579, PyTorch reports no GPU, so Diffusers, Transformers, vLLM and llama.cpp run on the processor; the installer says so. Update the driver (on Ubuntu: sudo apt-get install -y ubuntu-drivers-common, which cloud images often lack, then sudo ubuntu-drivers install and a reboot) and run the installer again. Whisper uses its own CUDA 12 libraries, which need driver 525 or newer.

Measured on real hardware. Ubuntu 26.04 with a Quadro RTX 5000: 16 GB, compute capability 7.5, driver 595.91.07 (CUDA 13.2), 4 vCPU and 26 GB RAM, with the AbstractFramework 0.6.3 stack: the install and text rows with AbstractGateway 0.7.3, AbstractCore 2.19.1, AbstractRuntime 0.7.2, AbstractVoice 0.13.1 and AbstractVision 0.3.32; speech-to-text with Voice Input set to faster-whisper and PyAV 18; the Load timings with AbstractRuntime 0.7.3; sequential CPU offload with AbstractVision 0.3.33. Any previous install was removed (uninstall.sh --yes --purge) and uv's download cache cleared first. Model weights, LM Studio (qwen/qwen3.5-9b) and a Rust toolchain were already on the machine. The installer ran without a terminal, so start at login stayed off.

Step	Result
Whole install (`install.sh`, profile picked automatically: gpu)	3 min 1 s; 14.2 GB added on disk
Python packages (`uv tool install`, exact pinned versions)	39 s, about 5.8 GB of wheels
llama.cpp `cu130` build swapped in	18 s (726 MB); loads, GPU offload
Terminal console and AbstractCode compiled with cargo	62 s and 48 s, no output meanwhile
Checks	PyTorch 2.11.0 on CUDA 13.0; Whisper on the GPU; vLLM 0.22.1 installed
Running it again	"already up to date", 10 s
`--print` with `nvidia-smi` hidden	exit 0; "no working NVIDIA GPU (nvidia-smi not found)"

With Use recommended defaults and the model weights already downloaded (load and generation timed separately where the path allows it):

Capability	Engine	Result
Text	LM Studio, `qwen/qwen3.5-9b` Q4_K_M, 6.5 GB on the GPU	first gateway request 23 s including the model load; then 12 s for 318 tokens; about 41 tokens/s from AbstractCore in Python
Text-to-speech	Supertonic, on the processor	1.1 to 1.4 s per sentence; 3.2 s for the first gateway request
Speech-to-text	faster-whisper `base` on CUDA, 0.3 GB of GPU memory	1.0 to 2.3 s per gateway request, no OpenAI key
Image	FLUX.2 [klein] 4B, Diffusers, model CPU offload, 7.8 GB peak	41 s to load, then 15 to 16 s per 1024x1024 image; after Load in the console, 17 to 19 s per gateway request on the loaded model (54 to 59 s when each request loads the model)

What to expect on a GPU of this size:

Speech input. The fresh setup and Use recommended defaults set Voice Input (input.voice) to faster-whisper, model base, so transcription runs locally without an OpenAI key. PyAV is held below 19, because PyAV 19 breaks faster-whisper 1.2.1's file reading.
The image model next to a loaded text model. When LM Studio keeps a 9B text model loaded (6.5 GB), Diffusers switches to sequential CPU offload for the image model: much less GPU memory (near 1.4 GB for FLUX.2 [klein] 4B at 768x768) and slower per step (about 2.3 s against 1.5 s), so a 4-step image takes 10.9 to 15.6 s against 13.4 to 18.5 s with model CPU offload, and models that run many steps are slower. Unloading the text model first (lms unload --all) gives model CPU offload back, which is faster for those.
Loaded image models are reused. After Load in the console (or POST /models/load), image requests run on the loaded model, and an unload frees its memory.

Not validated: vLLM (installed, never started a model here).

GPU on Windows (NVIDIA)

PyPI's PyTorch for Windows runs on the CPU only; the CUDA builds come from PyTorch's own index. With the gpu profile, install.ps1 asks nvidia-smi for the driver version and the GPU's compute capability, prints the stack it picks and why, and installs:

NVIDIA driver	PyTorch	llama.cpp builds tried, in order
580 or newer, compute capability 7.5 or newer	CUDA 13 (`cu130`, about 1.9 GB)	`cu130`, `cu132`, Vulkan, CPU
525 or newer	CUDA 12 (`cu126`, about 2.5 GB)	`cu125`, Vulkan, CPU
older, or no working NVIDIA GPU	PyPI's CPU build	Vulkan, CPU

It announces the big downloads before they start and shows uv's output as it happens, with a still working (… elapsed; last: Downloading torch …) line whenever nothing new was printed for 15 seconds. At the end it checks, in the gateway's own environment, that PyTorch sees the GPU (torch.cuda.is_available() and the device name), that the llama.cpp build loads the way AbstractCore loads it and reports GPU offload, and which device faster-whisper picks. A part that does not work is replaced by one that does: a CUDA install that fails is retried without llama.cpp, then with PyTorch's CPU build; a llama.cpp build that does not load (or reports no GPU offload) is replaced by the next one, and removed when none loads. A build is also replaced when it was compiled for CPU instructions your processor lacks: llama.cpp's cu130 build uses AVX-512, which most desktop Intel processors do not have, so those computers get the cu132 build. On a GPU newer than the build's CUDA architectures (RTX 50 series), the first model load takes a minute or two while the driver compiles the GPU code; later loads reuse it. The summary's GPU stack:, PyTorch:, GGUF: and Whisper: lines say what runs where, and why. vLLM (Linux only upstream) and stable-diffusion.cpp (a source build that needs an elevated MSVC install) are not part of the Windows gpu profile; Diffusers on PyTorch covers image generation. Local video generation runs on Apple silicon (MLX) only.

Validated on Windows 10 22H2 with an NVIDIA GeForce RTX 5060 Ti (compute capability 12.0, driver 617) and an Intel Core i7-5820K (no AVX-512): PyTorch 2.14.1 cu130 on the GPU; llama.cpp 0.3.35 cu132 with GPU offload answering a GGUF chat model; a Hugging Face (transformers) chat model on CUDA; Diffusers text-to-image (stabilityai/sd-turbo, fp16 on CUDA); Supertonic text-to-speech; and faster-whisper large-v3 speech-to-text on CUDA. The stack choice and its fallbacks for older drivers are tested with simulated drivers.

GPU voices on NVIDIA

With the gpu profile on Linux or Windows and an NVIDIA driver that answers nvidia-smi, the installer adds ONNX Runtime's CUDA build for the local voices (Supertonic and Piper text-to-speech) after the profile install, in the gateway's own environment. It installs AbstractVoice's onnx-cuda extra at the release's AbstractVoice version (uv pip install --python <the gateway's environment>/bin/python "abstractvoice[onnx-cuda]==<version>"; Windows: Scripts\python.exe), then checks python -c "import onnxruntime as o; print(o.get_available_providers())". The CPU build of ONNX Runtime (which piper-tts and faster-whisper need) and onnxruntime-gpu write the same files, so when CUDAExecutionProvider is missing it writes onnxruntime-gpu again, once (uv pip install --python … --no-deps --reinstall-package onnxruntime-gpu "onnxruntime-gpu==<the version just installed>", uv's form of pip install --force-reinstall --no-deps onnxruntime-gpu) and checks again. onnxruntime-gpu 1.27 and later is a CUDA 13 build, so the step needs driver 580 or newer and compute capability 7.5 or newer; on an older driver or GPU it is skipped. It asks nothing and never fails the install: one line during the install and the summary's GPU voices: line say whether the CUDA build is in place or why Supertonic and Piper stay on the processor. The check proves the CUDA build is in place, not that it loads: Supertonic and Piper report the provider they run on at first use. AbstractVoice 0.21.0 is the first release with the onnx-cuda extra; with an older AbstractVoice the line says so. On macOS nothing changes.

Compiled extras

Optional engines that publish no wheel on PyPI are skipped by default: stable-diffusion.cpp image generation (stable-diffusion-cpp-python) and, on macOS and Linux, voice echo cancellation (aec-audio-processing; Windows gets its prebuilt wheel). --full (Windows: -Full) keeps them and builds them, and llama.cpp, from source, which takes several minutes and needs a C/C++ compiler (macOS: xcode-select --install; Debian/Ubuntu: sudo apt-get install -y build-essential; Windows: Visual Studio Build Tools with "Desktop development with C++"). Without a compiler, --full stops before installing anything. You do not need them for MLX on Apple Silicon, for llama.cpp GGUF models (above), for Ollama, LM Studio or other endpoint engines, or for cloud providers.

Options

macOS/Linux	Windows	What it does
`--profile auto\|light\|apple\|gpu`	`-Profile`	Override the profile choice
`--port N`	`-Port N`	Gateway port (default 8080; the next free port when 8080 is busy)
`--with-apps`	`-WithApps`	Make sure Node.js 18+ exists for running the browser apps on their own with `npx` (the console's Apps page installs Node.js for the apps it runs)
`--with-ollama`	`-WithOllama`	Run Ollama's official installer (Linux uses sudo; the script tells you first)
`--with-lmstudio`	`-WithLmStudio`	Install LM Studio (headless daemon on macOS/Linux, winget on Windows)
`--no-console`	`-NoConsole`	Skip the terminal console (`abstractgateway-console`), which is otherwise built with cargo
`--no-code-cli`	`-NoCodeCli`	Skip AbstractCode's terminal client (`abstractcode`), which is otherwise built with the console's cargo into the same folder
`--no-core-cli`	`-NoCoreCli`	Do not put AbstractCore's commands (`abstractcore` and its apps) and `abstractvoice`, `abstractvision`, `abstractmusic` on PATH
`--full`	`-Full`	Also build the compiled extras and llama.cpp from source (needs a C compiler)
`--no-tray`	`-NoTray`	Leave out the menu-bar icon (`tray` extra)
`--with-console`, `--with-code-cli`, `--with-core-cli`, `--with-tray`, `--no-full`	`-WithConsole`, `-WithCodeCli`, `-WithCoreCli`, `-WithTray`, `-NoFull`	Turn back what an earlier `--no-console`, `--no-code-cli`, `--no-core-cli`, `--no-tray` or `--full` changed (a re-run keeps those choices otherwise)
`--no-service`	`-NoService`	Do not start at login (asks nothing; starts the gateway in the background)
`--server`	(Linux only)	A Linux server in one command, idempotent: asks nothing, installs `libatomic1` and `zstd` (LM Studio's and Ollama's Linux builds need them), starts at login as a systemd user service, turns lingering on (`sudo loginctl enable-linger`), opens no browser, and ends with the address, the setup code and the next steps (deploy-linux.md)
`--gpu` with `--server`, or `--gpu-driver`	(Linux only)	Install the NVIDIA driver first when `nvidia-smi` is missing and `lspci` sees an NVIDIA GPU (`ubuntu-drivers`), then say to reboot and run the command again. `--gpu` alone is the gpu profile
`--tailscale-funnel`	(Linux only, with `--server`)	Install and sign in Tailscale (prints the login URL and waits), publish the gateway with `tailscale funnel --bg <port>`, allow its https address as a browser origin; the summary's public address is that URL
`--no-start`	`-NoStart`	Install or upgrade only; do not start or restart the gateway, and say when a restart is due (the gateway's Update uses it)
`--no-open`	`-NoOpen`	Do not open the browser (remote or headless session: do not offer the terminal console)
`--ask-wait SECONDS`	`-AskWait SECONDS`	How long a timed question waits for an answer: start at login, and the terminal console offer at the end of a remote or headless install (default 25, at most 25; `--console-wait` is an alias)
`--no-modify-path`	`-NoModifyPath`	Do not add `~/.local/bin` to your shell profile (`uv tool update-shell`)
`--pin X` / `--from PATH`	`-Pin` / `-From`	Install another gateway version (`--pin latest`: the newest on PyPI; see Upgrade only the gateway) or a local checkout
`--with-wheel PATH` (repeatable)	(not yet)	Install a local wheel of a framework package (abstractcore, AbstractRuntime, ...) into the gateway's tool in place of its release pin, for this run only (env twin `AF_LOCAL_WHEEL`; a same-version wheel is reinstalled; the next run without it installs the release versions again): the wheel goes through `uv tool install --with` and its package leaves `uv-constraints.txt`, so the tool's receipt and a later `uv tool upgrade` keep it. The gateway itself is `--from`; abstractvoice is refused (it installs with its extras)
`--manifest PATH`	`-Manifest`	Read the gateway pin from this `install-manifest.json`
`--data-dir DIR`	`-DataDir`	Gateway data directory
`--interactive`	—	Wait for every answer without a time limit, and also ask whether to build the terminal console (and, with `--uninstall`, whether to delete data and uv); the double-click installers pass it
`-y`, `--yes`	—	Ask nothing, not even start at login (a first install leaves it off; a re-run keeps the previous choice)
`--print`	`-Print` (or `-WhatIf`)	Show the plan and every command; change nothing
`--print-versions`	`-PrintVersions`	Print the AbstractFramework release, the pinned gateway, its libraries, the npm apps and the crates, then exit
`-v`, `--verbose`	—	Show the full output of every command
`--uninstall [--purge] [--remove-uv]`	`-Uninstall [-Purge]`	Stop the gateway process tree, remove the service and uv tools (purge also deletes your data: see Remove AbstractFramework; `--remove-uv` also removes uv, its Python and cache when the installer added uv)

Commands you get

Everything lands in one folder, ~/.local/bin (Windows: %USERPROFILE%\.local\bin), which the installer adds to your shell profile: open a new terminal for it to be on PATH. The summary lists them under Commands.

The gateway's own commands, and the two terminal clients built with cargo:

Command	What it does
`abstractgateway`	The gateway itself: `serve`, `service` (start at login), `network` (who can reach it), `models`, `engines`, `apps`
`abstractgateway-config`	The gateway's admin and configuration command: `status` (readiness without starting it), `claim-url` (a new one-time console sign-in link), `defaults` / `set-default` / `clear-default` (which provider and model each capability uses), `get` / `set` / `unset` (runtime settings), `bootstrap-admin`, `init`
`abstractgateway-console`	The terminal console (`--gateway-url <url> --token <admin token>`); skipped with `--no-console`
`abstractcode`	AbstractCode's terminal client (sign it in once, see below); skipped with `--no-code-cli`

Sign abstractcode in. It needs the gateway's admin token once. Choose one of:

abstractcode login --token <admin token>, then plain abstractcode. The installer summary prints this line with your token, ready to paste (the installer does not save it for you). login checks the token and keeps it in AbstractCode's own login store, ~/.abstractcode/gateway.json (readable by you only). Without --gateway-url, abstractcode finds this computer's gateway through the gateway pointer, on whichever port it runs.
On the gateway's computer, SSH included: abstractgateway apps tui-command code. It prints a one-time line (valid 2 minutes) that opens abstractcode signed in as you, without you handling a token (add --data-dir <dir> for an install with a custom data directory; the summary shows it).

If abstractcode starts without a valid sign-in, it says so and names both ways. The admin token is in <data dir>/auth/bootstrap-admin-token; abstractgateway-config status prints the data directory. The gateway console's Apps page can update abstractcode in the same folder; a re-run of the installer keeps a newer version.

The commands of AbstractCore and its voice, vision and music packages, from the gateway's own environment (uv tool install --with-executables-from), so they always match the versions the gateway runs:

Package	Command	What it does
AbstractCore	`abstractcore`	AbstractCore's configuration and operations: `--config` (interactive setup wizard), `--status`, `models` (catalog, download), `engines` (detect, install), `serve` (the AbstractCore server and its web console)
	`abstractcore-config`	The same command as `abstractcore`
	`abstractcore-chat`	An interactive chat in the terminal with any provider and model (`--provider`, `--model`, `--stream`)
	`abstractcore-endpoint`	A single-model OpenAI-compatible `/v1` server: one provider and model loaded once per worker
	`summarizer`	Summarizes a document (`--style`, `--length`, `--focus`)
	`extractor`	Extracts entities and relationships from a document as a knowledge graph (JSON-LD or RDF triples)
	`judge`	LLM-as-a-judge: scores texts or files against criteria such as clarity, soundness and completeness
	`intent`	Analyzes the intents behind a text or a conversation, with deception indicators
	`deepsearch`	An autonomous research agent: searches the web and writes a sourced report on a question
	`abstractcore-summarizer`, `abstractcore-extractor`, `abstractcore-judge`, `abstractcore-intent`, `abstractcore-deepsearch`	The same five apps under prefixed names
AbstractVoice	`abstractvoice`	Voice in the terminal: a spoken chat with a model by default, plus `web` (a local web demo), `tts` (text to an audio file) and `check-deps`
	`abstractvoice-prefetch`	Downloads voice models ahead of time (for example `--supertonic`, `--stt`), so the first use does not wait
AbstractVision	`abstractvision`	Images and video in the terminal: `t2i` / `i2i` (generate or edit an image), `upscale`, `t2v` / `i2v` (video), `cli` (an interactive session), `download`, `models`, `provider-models`
AbstractMusic	`abstractmusic`	Music in the terminal: `t2m` (text to music), `repl`, `models`

A package puts all of the commands it declares on PATH: uv exposes all of a package's commands or none and cannot pick a subset, which is why the generic app names (summarizer, judge, …) come with AbstractCore. --no-core-cli (Windows: -NoCoreCli) leaves the four packages out; the gateway still uses them internally.

If one of those names already exists in the folder (another program's file, or another uv tool's command, such as an earlier uv tool install abstractcore), uv would refuse the whole install, so the installer leaves that package out, names the file in the way in a warning and in the summary's Not exposed line, and installs everything else. Remove that file and run the installer again to add the package.

An abstractcode that an earlier installer built with --with-code-cli is in ~/.cargo/bin; the installer does not touch it (delete it with cargo uninstall abstractcode).

Pass options through the one-liner like this:

curl -LsSf https://abstractframework.ai/install.sh | sh -s -- --with-apps --with-ollama

& ([scriptblock]::Create((irm https://abstractframework.ai/install.ps1))) -WithApps -WithOllama

Headless or remote machine

Step by step on a fresh Linux server (driver, service, tunnel, first model, uninstall): Deploy on a Linux server.

Install over SSH with the same one-liner. It asks the start-at-login question in your SSH terminal (Enter = yes; a scripted install with no terminal leaves it off), installs local voice (Supertonic and Whisper, on CPU) like every other install, and at the end offers to open the terminal console, signed in ("Press Enter within 25 s"; no answer skips it, so a scripted ssh -t never hangs).

Later, start the terminal console on the server with the command the installer's summary prints (your port and token filled in):

abstractgateway-console --gateway-url http://127.0.0.1:8080 --token <admin token>

The admin token is in ~/.local/share/abstractgateway/auth/bootstrap-admin-token (the summary prints the command with it filled in). The terminal console configures everything the web console does: press N for the Network screen (who can reach the gateway: this machine, the local network or the internet; the saved and the running setting side by side, with the addresses to copy), A for Apps, F3 for the gateway host (restart, update, start at login).

From your own computer, one SSH tunnel carries the web console, the API and every browser app, because the gateway serves the apps on its own port:

ssh -L 8080:127.0.0.1:8080 <server>

Then open the link from abstractgateway-config claim-url --base-url http://127.0.0.1:8080 in your browser, and open the apps from the console's Apps page: each opens at http://127.0.0.1:8080/apps/<app>/ (observer, code, flow, continuum, entity). On the server itself, the terminal console's Apps screen shows the same link and the tunnel command instead of starting a browser.

On a server, run text models with llama.cpp, which every profile installs (the CUDA build on an NVIDIA GPU: the summary's GGUF: line). The setup guide may recommend LM Studio, a desktop app that is not installed on a server: choose a GGUF model instead, for example this 2.5 GB one (the model of Deploy on a Linux server, measured there on a 16 GB GPU):

abstractgateway models download huggingface "unsloth/Qwen3-4B-Instruct-2507-GGUF:Q4_K_M"
abstractgateway-config set-default output.text --provider huggingface --model unsloth/Qwen3-4B-Instruct-2507-GGUF
abstractgateway-config set-default input.text  --provider huggingface --model unsloth/Qwen3-4B-Instruct-2507-GGUF

Local voice is installed without its default voice: download it once (the installer's summary prints this line), or speech synthesis answers an error until you do:

abstractgateway models download supertonic supertonic-3

The same install by hand

curl -LsSf https://astral.sh/uv/install.sh | sh             # Windows: irm https://astral.sh/uv/install.ps1 | iex
uv python install 3.12
uv tool install --python 3.12 "abstractgateway[tray]==0.21.0"    # [apple,tray] or [gpu,tray] for local engines
                       # (add --with and --overrides as shown by `install.sh --print` to avoid compiling)
uv tool update-shell                                          # puts ~/.local/bin on PATH; open a new terminal
abstractgateway service install --port 8080                   # or: abstractgateway serve
abstractgateway-config claim-url --base-url http://127.0.0.1:8080  # prints a one-time console link

Run at login

The easiest way to turn start at login on or off is the Start at login switch in either console: the web console's Gateway section, or F3 in the terminal console. In a terminal, abstractgateway service does the same (LaunchAgent on macOS, systemd --user on Linux, a per-user Run entry on Windows, experimental):

abstractgateway service enable      # start this gateway at the next login (the consoles' switch)
abstractgateway service disable     # stop starting it at login (the running gateway keeps running)
abstractgateway service install --port 8080   # register the login item and start the gateway now
abstractgateway service status
abstractgateway service uninstall   # stop it and remove the login item (data is kept)

The login item runs plain abstractgateway serve, so the host and port come from the Network setting below. Passing --host to service install stores the matching mode in that setting.

Linux: lingering. A systemd --user service runs only while you have a session: on a server it stops when your last SSH session ends and does not start at boot. Turn lingering on once (loginctl show-user "$USER" -p Linger says Linger=yes afterwards); the installer's summary prints this line when it is off:

sudo loginctl enable-linger "$USER"

The bootstrap scripts use it by default. Gateways older than 0.3.0 (installed with --pin) have no service command: install.sh then starts the gateway in the background and install.ps1 adds a Startup-folder shortcut. To write a login entry yourself on Linux, a user unit is enough:

# ~/.config/systemd/user/abstractgateway.service
[Service]
Environment=ABSTRACTGATEWAY_USER_AUTH=1
Environment=ABSTRACTGATEWAY_DATA_DIR=%h/.local/share/abstractgateway
ExecStart=%h/.local/bin/abstractgateway serve
Restart=on-failure

[Install]
WantedBy=default.target

Then systemctl --user daemon-reload && systemctl --user enable --now abstractgateway. On macOS use a LaunchAgent in ~/Library/LaunchAgents/ with the same absolute command and environment (launchd does not read your shell profile, so use absolute paths).

Network setting: who can reach the gateway

The gateway listens on this computer only (localhost, 127.0.0.1:8080) until you choose otherwise. Change it in the web console's network panel, on the terminal console's Network screen (N), from the menu-bar icon's Network menu, or in a terminal:

abstractgateway network status                      # configured vs running mode, addresses, warnings
abstractgateway network set lan                     # other devices on your local network
abstractgateway network set localhost --port 8080   # back to this computer only
abstractgateway network set internet --acknowledge-internet   # public; TLS and port forwarding are yours
abstractgateway network restart --token <admin token>   # apply it to the running gateway now
abstractgateway network addresses                   # every URL a client can use

A new mode or port applies at the next start: network restart, the console, the menu-bar icon's Restart AbstractGateway…, or the next login. Keep localhost unless you need another device to connect; see Gateway security before choosing internet.

Reached through Tailscale? On the gateway machine run tailscale serve --bg http://127.0.0.1:<port> and open https://<host>.<tailnet>.ts.net/; tailscale serve reset undoes it. The Network setting can stay localhost. Voice and camera in the browser need this https address (browsers offer them only on https pages or on the gateway's own computer). See Phones and tablets: Reached through Tailscale.

Upgrade and uninstall

Upgrade: re-run the one-liner, or use Update in a console or the menu-bar icon, which runs the same installer; see Upgrade (uv tool upgrade abstractgateway does not upgrade an installer install: it keeps the installed version's pin).
Uninstall: Remove AbstractFramework above, curl -LsSf .../install.sh | sh -s -- --uninstall (Windows: the script block with -Uninstall), or by hand: abstractgateway service uninstall (when registered), then uv tool uninstall abstractgateway (it also removes the AbstractCore, voice, vision and music commands it exposed) and cargo uninstall --root ~/.local abstractgateway-console abstractcode (Windows: cargo uninstall --root %USERPROFILE%\.local abstractgateway-console abstractcode). The uninstaller does all of it. Your data stays in the data directory until you delete it (--purge). See Operations and support for locations.

Check the install

uvx abstractframework doctor

It checks Python, uv, Node, disk, the gateway (ABSTRACTGATEWAY_URL, default http://127.0.0.1:8080), and whether Ollama and LM Studio are reachable. It only reads.

Install the Python framework (developers)

Use the profiles below when you want every framework library in one Python environment, for example to build on AbstractCore or AbstractRuntime directly. Choose the profile by deciding where inference should run. The framework APIs stay the same across profiles; the profiles mainly change whether local inference engines are installed.

Quick chooser

Profile	Command	Use when	Local inference stacks
Light	`pip install abstractframework`	You use cloud APIs or endpoint servers such as LM Studio, Ollama, vLLM, llama.cpp, OpenRouter, or OpenAI-compatible services.	No
Apple	`pip install "abstractframework[apple]"`	You are on Apple Silicon and want local MLX/Metal-capable engines as well as endpoint providers.	Yes, Apple-focused
GPU	`pip install "abstractframework[gpu]"`	You have a supported discrete GPU and want local GPU-capable engines as well as endpoint providers.	Yes, GPU-focused

Requirements per profile

Profile	Platforms	Python	Notes
Light	macOS, Linux, Windows	3.10–3.13	No local inference engines.
Apple	macOS 14 or later on Apple Silicon	3.10–3.13	MLX wheels need macOS 14+. F5-TTS voice cloning needs Python 3.11+; the rest of the profile works on 3.10.
GPU	Linux with NVIDIA CUDA or AMD ROCm drivers; Windows x64 with NVIDIA (see GPU on Windows)	3.10–3.13	F5-TTS voice cloning needs Python 3.11+; the rest of the profile works on 3.10.

[apple] needs macOS 14 or newer: MLX publishes no wheels for macOS 13 (its wheels start at macosx_14_0_arm64, and there is no source package), so pip install "abstractframework[apple]" on macOS 13 fails to resolve (mlx … has no wheels with a matching platform tag). Use the light profile there (pip install abstractframework). The one-line installer and the .pkg pick the light profile on macOS 13 on their own, refuse --profile apple below 14, and switch to apple on the re-run after a macOS update.

A plain pip install of the apple profile, or of the gpu profile on Linux, builds the compiled extras (llama-cpp-python, stable-diffusion-cpp-python, aec-audio-processing) from source, so it needs a C/C++ compiler. The one-line install above does not. On Windows, a plain pip install "abstractframework[gpu]" needs no compiler (llama.cpp and stable-diffusion.cpp are left out there, and aec-audio-processing has Windows wheels for Python 3.11 to 3.13), but it gets PyPI's CPU-only PyTorch and no llama.cpp: use the one-line installer, which adds PyTorch's CUDA build and llama.cpp's prebuilt GPU build (GPU on Windows).

abstractframework 0.14.0 pins the published Python matrix listed in the release matrix, including abstractgateway==0.21.0, abstractcore==2.35.1, AbstractRuntime==0.19.5, AbstractMemory==0.5.1, abstractagent==0.6.1, abstractvoice==0.21.1, abstractvision==0.3.36, abstractassistant==0.18.3, abstractskill==0.3.11, abstractnote==0.3.1, abstractcamera==0.2.1 and abstractavatar==0.2.0. The apple and gpu extras select local-engine dependencies at the same component versions. abstractframework doctor reports installed packages that differ from these pins. Avatar wheels cover macOS arm64/x86_64, manylinux glibc 2.28+ arm64/x86_64 and Windows x86_64. Other platforms need Rust 1.87+ to build its source distribution.

Light is not a reduced-functionality framework. It is the remote-first profile: multimodal input, multimodal output, embeddings, tools, durable runs, workflows, and Gateway/Flow still work when they are backed by remote or local endpoint providers.

Recommended technical install

Use a clean virtual environment:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install abstractframework
abstractframework doctor

Use uv if you prefer faster environment management:

uv venv
source .venv/bin/activate
uv pip install abstractframework
abstractframework doctor

pipx is useful for isolated command-line apps, but a normal venv is usually clearer for the full framework because Gateway, Flow, Core, and local plugins share one environment.

Light profile

pip install abstractframework

Choose Light when:

you use OpenAI, Anthropic, OpenRouter, Portkey, or other hosted providers;
you use local model servers through HTTP, such as LM Studio, Ollama, vLLM, llama.cpp, or LocalAI;
you want the smallest and least surprising install;
you do not want pip to install MLX, CUDA, Diffusers, or local model-runtime stacks.

The Light environment takes about 0.9 GB in a fresh Python 3.12 environment. About 600 MB of it is AbstractCore's light setting, which includes the Office-document parsers, the built-in tools and the voice, vision, music and 3D plugins with their remote backends; it installs no local engine.

After install, run abstractframework doctor, start the gateway and configure providers in its console (see Start the gateway).

Apple profile

pip install "abstractframework[apple]"

Choose Apple when:

you are on Apple Silicon;
you want local Apple/MLX-capable inferencers in addition to endpoint providers;
you accept larger downloads and platform-specific native dependencies.

Then run abstractframework doctor.

GPU profile

pip install "abstractframework[gpu]"

Choose GPU when:

you have a supported GPU stack and drivers;
you want local GPU-capable inferencers in addition to endpoint providers;
you accept larger downloads and platform-specific native dependencies.

Then run abstractframework doctor.

Apps and tools outside pip

The browser apps and the Rust terminal tools are not Python packages, so no profile installs them. Run or install them next to the Python stack:

Tool	Command	Version released with 0.14.0
Gateway web console	built into `abstractgateway`: open the link `abstractgateway serve` prints (`http://127.0.0.1:8080/console#claim=…`)	0.21.0
Core web console	built into `abstractcore`: open the link `abstractcore serve` prints (`http://127.0.0.1:8000/console#claim=…`)	2.35.1
Core terminal console	`cargo install abstractcore-console` (Rust 1.87+), then `abstractcore-console` (uses the `abstractcore` command). The installers do not build it: it is the console of a standalone `abstractcore serve`, and the gateway's terminal console already has its Models and Engines screens	0.8.1
Gateway terminal console	built by the installer (`--no-console` skips it), or `cargo install abstractgateway-console` (Rust 1.87+); then `abstractgateway-console --gateway-url http://127.0.0.1:8080 --token <admin token>`	0.18.1
Flow Editor	the console's Apps page (opens at `/apps/flow/`), or on its own: `npx @abstractframework/flow --gateway-url <url>`	0.14.2
Code Web UI	the console's Apps page (`/apps/code/`), or `npx @abstractframework/code --gateway-url <url>`	0.16.0
Observer	the console's Apps page (`/apps/observer/`), or `npx @abstractframework/observer --gateway-url <url>`	0.13.0
Continuum console	the console's Apps page (`/apps/continuum/`), or `npx @abstractframework/continuum --gateway-url <url>`	0.8.1
Entity manager	the console's Apps page (`/apps/entity/`), or `npx @abstractframework/entity --gateway-url <url>`	0.12.0
Notes	the console's Apps page (`/apps/note/`), or `npx @abstractframework/note@0.3.1 --gateway-url <url>`	0.3.1
Assistant web app	the console's Apps page (on the Assistant card, served at `/apps/assistant-web/`), or `npx @abstractframework/assistant --gateway-url <url>`	0.2.0
AbstractCode terminal client	`cargo install abstractcode`, or a prebuilt binary from the AbstractCode GitHub release	0.15.0

The browser apps need a running gateway. The gateway installs, starts and serves them itself, on its own address at /apps/<app>/ (it installs Node.js for them when it is missing); running one on its own with npx needs Node.js 18 or later. abstract3d (pinned above) comes with AbstractCore in every profile; Camera, Notes and the Python Avatar binding are also pinned in the Python profiles. abstractskill comes with the gateway, which carries its curated skill shelf.

Start the gateway and apps

Start the gateway and open its console:

abstractgateway serve            # binds 127.0.0.1:8080 and prints a one-time console link

The console's Apps page installs and opens the browser apps, each at http://127.0.0.1:8080/apps/<app>/, already signed in. To run an app on its own instead (for development, or against another gateway), pass the gateway's address:

npx @abstractframework/flow --gateway-url http://127.0.0.1:8080

Configure providers, API keys, engines and default models in the console. For library-only use of AbstractCore, abstractcore serve opens the same Models and Engines screens in its own console, and abstractcore --config remains available in the terminal. When you work from source, the workspace helper scripts build and start the same services (see Workspace scripts).

Gateway-hosted browser apps use Gateway user tokens and browser sessions. Do not use the bootstrap server token as a browser login token.

Container deployment

For a server/VPS deployment, prefer the Gateway container rather than installing every app package on the host:

docker run \
  -p 8080:8080 \
  -v "$PWD/runtime:/data" \
  -e ABSTRACTGATEWAY_DATA_DIR=/data \
  -e ABSTRACTGATEWAY_USER_AUTH=1 \
  ghcr.io/lpalbou/abstractgateway:0.21.0

This is the Light container: full framework capabilities through remote/endpoint inference, without local MLX/CUDA stacks. On first start it creates default/admin and writes the login token to runtime/auth/bootstrap-admin-token. Use ghcr.io/lpalbou/abstractgateway:gpu-latest only on an NVIDIA host when you explicitly want the local GPU profile (pinned tags are <version>-gpu, published on a best-effort basis; this image is experimental). The AbstractCore OpenAI-compatible server is also published as ghcr.io/lpalbou/abstractcore-server:2.35.1.

How installs are designed

The scripts and the gateway console are the install experience on every OS. On macOS the double-click artefacts (a payload-free .pkg and two .command files) only launch the same script in Terminal; they add no install logic of their own. Design, security model and per-OS behavior are in docs/installers.

Generated install manifest

The installer-facing contract is generated from the root release profile:

abstractframework manifest
abstractframework manifest --check docs/installers/install-manifest.json
abstractframework manifest --write install-manifest.json

The bootstrap scripts read bootstrap.gateway_version from it; other installers should consume this manifest instead of maintaining independent package pins. Field reference: release-and-manifest.md.

OpenAI-compatible serving

The gateway serves an OpenAI-compatible API on its own listener at http://<gateway host>:<port>/v1 (/v1/models, /v1/chat/completions, structured outputs through response_format). An admin turns it on in the web console under Models → OpenAI API (the Endpoint switch) and chooses who can connect: this machine only, devices on your network, your tailnet (offered when a Tailscale address is detected) or anywhere. The API key is the caller's own gateway token, so requests run as that account; an admin turns it off for one account with that account's OpenAI API switch (Accounts → OpenAI API). In Open mode, requests without a key run as an account the admin picks (a restricted guest by default, never an admin). /core/v1 answers with a 308 redirect to /v1 for this release and is deprecated. See AbstractGateway: OpenAI API.

FilesExpand file tree

install.md

Latest commit

History