Framework release 0.6.2 · gateway 0.7.2

Install AbstractFramework

One download or one line. No admin password, no system Python to prepare. At the end, AbstractFramework opens in your web browser, already signed in, and a first-run guide helps you pick an engine and a model that fits your machine.

Choose how to install Headless or remote server Python profiles

Choose

Pick the line for your computer

Every way below runs the same installer script, so the result is the same. Running it again repairs or upgrades the install in place.

Without Terminal: the Mac package.

Download AbstractFramework-Installer.pkg (attached to every GitHub release) and double-click it.
The package is not signed with an Apple Developer ID, so macOS blocks it the first time. Close the warning, open System Settings > Privacy & Security, click Open Anyway next to the installer's name and confirm. You do this once per download.
Click Continue, then Install; it installs for you only, so it does not ask for your password. A Terminal window then shows each step and asks one question: Start AbstractFramework automatically when you log in? Press Return for yes.
It also leaves Install AbstractFramework.command (run it again to repair or upgrade) and Uninstall AbstractFramework.command in ~/Library/Application Support/AbstractFramework/Installer.

With Terminal: one line. Paste it and press Return; it runs the same installer.

curl -LsSf https://raw.githubusercontent.com/lpalbou/AbstractFramework/main/scripts/install.sh | sh

macOS 13 or later (the Apple Silicon engines need macOS 14), about 5 GB of free disk before models, and an internet connection.
With no answer to the start-at-login question within 25 seconds, it leaves start at login off. Pass options after sh -s --, for example … | sh -s -- --with-ollama. See Options.

curl -LsSf https://raw.githubusercontent.com/lpalbou/AbstractFramework/main/scripts/install.sh | sh

Paste it in a terminal and press Return. It asks whether to start at login (a systemd --user service); Enter = yes, no answer within 25 seconds leaves it off. Your data lives in ~/.local/share/abstractgateway.
x86_64 or aarch64 (on musl Linux such as Alpine, local voice and llama.cpp are skipped); about 5 GB of free disk before models. The gpu profile is picked when nvidia-smi or rocminfo works.
Headless or over SSH: the same line works. It does not open a browser on the server; it offers the terminal console at the end instead, and one SSH tunnel reaches the web console and every app. See Headless or remote server.

powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/lpalbou/AbstractFramework/main/scripts/install.ps1 | iex"

Windows 10 22H2 or later, or Windows 11. Open PowerShell, paste the line and press Enter.
It installs under your user account (no administrator rights), asks whether to start AbstractFramework at sign-in (Enter = yes) and opens it in your browser.
-NoService leaves start at sign-in off and asks nothing. The terminal console and abstractcode are built into %USERPROFILE%\.local\bin when Rust is already installed.

# the same install, step by step
curl -LsSf https://astral.sh/uv/install.sh | sh
uv python install 3.12
uv tool install --python 3.12 "abstractgateway[tray]==0.7.2"   # [apple,tray] or [gpu,tray] for local engines
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

The last command prints a one-time sign-in link for the console (valid 10 minutes, this machine only).
To avoid compiling anything, add the --with and --overrides arguments that install.sh --print shows.

Checks this machine

OS, CPU, disk, a free port, internet access, NVIDIA or ROCm. It picks a profile: apple on Apple Silicon (macOS 14+), gpu with a working NVIDIA or ROCm GPU, light otherwise.

Installs in your account

uv and a private Python 3.12, then the gateway as an isolated tool, with local voice (Supertonic text-to-speech and Whisper speech-to-text, on CPU). Prebuilt wheels only: no compiler needed.

Puts the commands on PATH

Builds the terminal console and AbstractCode’s terminal client with cargo (on macOS and Linux, Rust from rustup when missing; on Windows, only when Rust is already installed), and exposes the library commands, all next to abstractgateway in ~/.local/bin (Windows: %USERPROFILE%\.local\bin). A failed build never fails the install. Commands you get

Opens the console

Starts the gateway on 127.0.0.1:8080, writes ~/.abstractframework/gateway.json (Windows: %USERPROFILE%\.abstractframework\gateway.json) so every client finds it, and opens the web console through a one-time sign-in link.

Afterwards, AbstractFramework is at http://127.0.0.1:8080/console (bookmark it). The gateway’s tray icon (the menu bar on macOS, the system tray on Windows, a panel on Linux) opens it and shows its status. The browser apps open from the console's Apps page at http://127.0.0.1:8080/apps/<app>/. Next: what the console does, or pick a starting point.

Commands you get

Every command in one folder

Everything lands in ~/.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.

Command	What it does	Opt out
`abstractgateway`	The gateway: `serve`, `service` (start at login), `network`, `models`, `engines`, `apps`	—
`abstractgateway-config`	The gateway’s admin command: `status`, `claim-url` (a new sign-in link), defaults and settings	—
`abstractgateway-console`	The terminal console	`--no-console`
`abstractcode`	AbstractCode’s terminal client (sign it in once, below)	`--no-code-cli`
`abstractcore`, `abstractcore-chat`, `abstractcore-endpoint`	AbstractCore’s configuration and operations (`--config`, `models`, `engines`, `serve`), a terminal chat, a single-model `/v1` server	`--no-core-cli`
`summarizer`, `extractor`, `judge`, `intent`, `deepsearch`	AbstractCore’s apps (also as `abstractcore-<app>`): summarize a document, extract a knowledge graph, LLM-as-a-judge, intent analysis, a sourced web research report
`abstractvoice`, `abstractvoice-prefetch`, `abstractmusic`, `abstractvision`	Voice, music, and images and video in the terminal, from the gateway’s own environment so they match the versions it runs

A package’s commands come all together or not at all: when another program already has one of its names, the installer leaves that package out with a warning naming the file, and installs the rest.

Sign the terminal app in

abstractcode login --token <admin token>   # once; the summary prints it with your token
abstractcode

# or, on the gateway's computer, without handling a token:
abstractgateway apps tui-command code

The installer never saves the token for you. tui-command prints a one-time line, valid 2 minutes, that opens abstractcode signed in. Started without a sign-in, abstractcode says so and prints both lines.

One folder for the terminal apps

The console’s Apps page installs and updates abstractcode in the same folder as the installer, so it runs by name whichever of the two installed it. A re-run of the installer keeps an abstractcode newer than its pin, and the uninstaller removes it with the console.

Requirements

What your computer needs

System	Supported	Notes
macOS	macOS 13 or later	Apple Silicon gets the fast local engines (MLX), which need macOS 14. The gateway takes about 2.4 GB on Apple Silicon, and uv's download cache about 2.4 GB more.
Linux	x86_64 and aarch64	Start at login is a `systemd --user` service. Local voice is skipped on musl Linux (Alpine), where no wheels exist.
Windows	Windows 10 22H2+, Windows 11	User-scoped install, no administrator rights. Windows on ARM64 gets Supertonic voice but not Whisper.
Everything	About 5 GB free disk before models	Models you download later come on top. The installer stops with a plain message and the next step when something is missing.

Install profiles

The installer picks the profile for you; --profile overrides it. The framework's features are the same in every profile; the profile decides which local inference engines are installed. AbstractFramework runs on macOS, Linux and Windows and has been tested most on Apple Silicon; local video generation runs through MLX-Gen, validated on Apple Silicon, until AbstractVision’s Diffusers video path reaches parity (AbstractVision README).

Light

Remote and endpoint engines: OpenAI, Anthropic, OpenRouter, Portkey, LM Studio, Ollama, vLLM and any OpenAI-compatible endpoint, plus local voice on the processor. Works on macOS, Linux and Windows.

OpenAIAnthropicOpenRouterPortkeyLM StudioOllamavLLMOpenAI-compatible

Apple Light +

Everything in Light, plus the local Apple Silicon engines (MLX and Metal) for text, voice, music, images and video. macOS 14+ on Apple Silicon.

Light +MLXHugging FaceGGUF (llama.cpp)Local embeddingsAbstractVoice localMLX-Gen (AbstractVision)AbstractMusic localHeadless browser

GPU Light +

Everything in Light, plus the local GPU engines for NVIDIA CUDA or AMD ROCm on Linux.

Light +vLLM engineHugging FaceGGUF (llama.cpp)Local embeddingsAbstractVoice localDiffusers (AbstractVision)AbstractMusic localHeadless browser

Remote & headless

A Linux server over SSH works like a Mac

Install with the same one-liner over SSH. You configure the gateway from the terminal console on the server, and one SSH tunnel carries the web console, the API and every browser app to your own computer.

Install over SSH

ssh -t <server>
curl -LsSf https://raw.githubusercontent.com/lpalbou/AbstractFramework/main/scripts/install.sh | sh

It asks the start-at-login question in your SSH terminal, installs local voice like every 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 install never hangs. Over SSH it does not open a browser on the server.

Configure from the terminal console

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

The installer's summary prints this command with your port and token filled in; the admin token is also in ~/.local/share/abstractgateway/auth/bootstrap-admin-token. The console runs the same setup guide as the web console. Press N for Network, A for Apps, F3 for the gateway host (restart, update, start at login).

Reach the web console and apps through one tunnel

ssh -L 8080:127.0.0.1:8080 <server>
# on the server, print a one-time sign-in link for your browser:
abstractgateway-config claim-url --base-url http://127.0.0.1:8080

Open the link in your browser, then open the apps from the console's Apps page: each one is served at http://127.0.0.1:8080/apps/<app>/ (observer, code, flow, continuum, entity).

Where it runs

This computer only, until you choose otherwise

Who can reach it

This computer

The default: the gateway listens on 127.0.0.1 only, with user accounts on. Nobody else can connect.

localhostDefault

Local network (LAN)

Every device on your network (or your VPN) reaches the sign-in page and the API. User accounts are required. It is plain HTTP, so use it on networks you trust, or behind a TLS proxy or VPN.

lanAccounts required

Internet

The same, with an explicit acknowledgement. The gateway does not terminate TLS: put your own TLS reverse proxy (Caddy, nginx, Traefik) or a tunnel in front of it.

internetYour TLS

How it runs

Desktop

An icon in the macOS menu bar, the Windows system tray or a Linux panel opens the console already signed in. Start AbstractGateway at login registers a per-user login item.

Tray iconStart at login

Headless server

Install over SSH with the same one-line installer, manage it from the terminal console (abstractgateway-console), keep it running with a systemd --user service, and reach the console, the API and every app through one SSH tunnel.

SSHsystemd --user

Container

Release images on GHCR (ghcr.io/lpalbou/abstractgateway, and a -gpu variant), run with a mounted data directory and ABSTRACTGATEWAY_USER_AUTH=1.

GHCR imageMounted data

In practice. A new gateway answers on this computer only. The Network setting, in the web console, the terminal console or the tray, or abstractgateway network set lan (or internet) opens it up at the next start, and both keep user accounts on. A gateway started on another address without user accounts or a token refuses to start.

The commands

Network

abstractgateway network status
abstractgateway network set lan          # devices on your local network
abstractgateway network set localhost --port 8080
abstractgateway network set internet --acknowledge-internet
abstractgateway network restart --token <admin token>
abstractgateway network addresses

A new mode applies at the next start. Internet mode leaves TLS and port forwarding to you: read Gateway security first.

Start at login

abstractgateway service enable     # start at the next login
abstractgateway service disable
abstractgateway service install --port 8080
abstractgateway service status
abstractgateway service uninstall  # data is kept

Or flip the Start at login switch in either console. It is a LaunchAgent on macOS, a systemd --user unit on Linux and a per-user Run entry on Windows.

Options

Installer options

The most useful ones. --print shows the plan and every command without changing anything. The full list is in docs/install.md.

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-ollama`	`-WithOllama`	Run Ollama's official installer
`--with-lmstudio`	`-WithLmStudio`	Install LM Studio (headless daemon on macOS/Linux)
`--with-apps`	`-WithApps`	Make sure Node.js 18+ exists for running the browser apps on their own with `npx`
`--no-code-cli`	`-NoCodeCli`	Do not build AbstractCode’s terminal client (built by default)
`--no-core-cli`	`-NoCoreCli`	Do not put the AbstractCore, AbstractVoice, AbstractMusic and AbstractVision commands on PATH
`--no-console`	`-NoConsole`	Skip the terminal console
`--no-service`	`-NoService`	Do not start at login; ask nothing
`--no-open`	`-NoOpen`	Do not open the browser (remote: do not offer the terminal console)
`--data-dir DIR`	`-DataDir`	Gateway data directory
`--print`	`-Print`	Show the plan and every command; change nothing
`--uninstall [--purge]`	`-Uninstall [-Purge]`	Remove the gateway and login item (`--purge` also deletes your data)

If something goes wrong

Run it again

The installer stops at the first problem, says what happened in plain words and what to do. After you fix the cause, run it again: 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 and run it again. Nothing was changed.
`this Terminal runs in Intel (Rosetta) mode on an Apple Silicon Mac`	Untick Open using Rosetta in Terminal's Get Info window, then run it again.
`the Apple Silicon engines (MLX) need macOS 14 or later`	You get the light version. Update macOS and run the installer again to add the local engines.
The browser page asks for a token	The one-time link lasts 10 minutes. Run the installer again for a fresh link, or run `abstractgateway claim --open`.
Anything else	Run it again. If it stops at the same step, report it with the log file named at the end of the message.

Check an install

uvx abstractframework doctor

Checks Python, uv, Node, disk, the gateway and whether Ollama and LM Studio answer. It only reads.

Upgrade

# re-run the same line you installed with
curl -LsSf https://raw.githubusercontent.com/lpalbou/AbstractFramework/main/scripts/install.sh | sh

Re-running the script upgrades or repairs the install in place and keeps your profile, port and start-at-login choice. On Windows, run the PowerShell line again; on a Mac without Terminal, double-click Install AbstractFramework.command again. The console’s Gateway card (Check now), the terminal console (F3, then u) and the gateway’s tray icon (Check for Updates) also offer the update: on an installer install it compares your AbstractFramework release with the newest one and runs the installer.

Remove

curl -LsSf https://raw.githubusercontent.com/lpalbou/AbstractFramework/main/scripts/uninstall.sh | sh

It asks before deleting anything, keeps your data unless you say yes, and keeps model weights and shared caches. Windows: install.ps1 -Uninstall [-Purge].

Developers & servers

Python profiles and containers

Want every framework library in your own Python environment, or a container on a server? Use the meta-package or the gateway image. Python 3.10 to 3.13.

python3 -m venv .venv && source .venv/bin/activate
python -m pip install abstractframework
abstractframework doctor
abstractgateway serve     # prints a one-time console link

Remote-first: cloud APIs and endpoint servers (LM Studio, Ollama, vLLM, llama.cpp, OpenAI-compatible). Multimodal input and output, tools, durable runs and workflows all work.

pip install "abstractframework[apple]"

macOS 14 or later on Apple Silicon. Local MLX and Metal engines next to the endpoint providers. A plain pip install of this profile builds a few compiled extras from source and needs a C/C++ compiler; the one-line installer does not.

pip install "abstractframework[gpu]"

Linux (and Windows where the engines publish wheels) with NVIDIA CUDA or AMD ROCm drivers. Voice cloning with F5-TTS needs Python 3.11+.

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

The light container: every framework capability through remote or endpoint inference. On first start it creates default/admin and writes the login token to runtime/auth/bootstrap-admin-token.
ghcr.io/lpalbou/abstractgateway:gpu-latest is an experimental local GPU image for NVIDIA hosts. The AbstractCore OpenAI-compatible server is ghcr.io/lpalbou/abstractcore-server:2.19.0.

abstractframework pins every framework Python package with ==; the framework CHANGELOG lists the pins of each release and what changed; each package’s changes are in its own CHANGELOG: AbstractGateway, AbstractCore, AbstractRuntime, AbstractAgent, AbstractVoice, AbstractMusic, AbstractVision, Abstract3D. Developer journey →