AbstractGateway

AbstractGateway is a deployable Run Gateway host for AbstractRuntime runs, and the control plane of an AbstractFramework installation:

start durable runs, accept a durable command inbox, and replay or stream a durable ledger (replay-first);
enforce a security baseline: user accounts, browser sessions, an origin allowlist, request limits and an audit log;
manage users, providers, capability defaults, local engines, model downloads, browser apps and network exposure from a web console (/console), a terminal console, the CLI or a desktop tray icon.

Clients (AbstractFlow, AbstractCode, AbstractObserver, AbstractContinuum, AbstractEntity, AbstractAssistant, scripts) talk to the gateway over HTTP, so none of them depends on the others.

Start here: docs/first-run.md on your own machine, or docs/getting-started.md for an explicit setup.

What's new in 0.17.2 (CHANGELOG): the console's app manager installs the versions the AbstractFramework release pins (a newer one is offered as an update, never installed by itself); network status reports the user auth a loopback gateway turned on itself.

What's new in 0.17.1: the console's ui-kit islands are resynced from the released kit (ui-kit 0.9.1 -> 0.9.4): the console's voice picker lists each Qwen3-TTS voice once instead of once per model. A run whose On Flow End wrote notify: null now reports quiet_reason: "no notify", not "empty title".

What's new in 0.17.0: memory graph routes (/api/gateway/memory/*: query, history, sources, source reconstruction, derived memories) over AbstractRuntime 0.15.0's memory facade, with a strict owner rule (a person reads only their own graph and the graphs of the entities they created; /kg/query follows the same rule). The gateway no longer imports AbstractMemory directly. It requires AbstractRuntime 0.15.0 and AbstractMemory 0.4.0, whose vector re-encoding is one way: upgrade every process sharing a plane together.

What's new in 0.16.0: the replay view (GET /runs/{id}/view and /view/stream, one fold per record shared by every client), a per-conversation tool policy (approve or deny for the whole session), the voice library with personal voices per account, triggers (feeds, webhooks, several mailboxes) and per-user event streams with Apple push. It requires AbstractRuntime 0.14.0; its hash-chained ledgers are read by 0.14.0 verifiers only, so upgrade writers and verifiers together.

AbstractFramework ecosystem

AbstractGateway is part of the AbstractFramework ecosystem:

AbstractRuntime (required): durable run model + workflow registry + stores (pyproject.toml, src/abstractgateway/runner.py)
AbstractCore, AbstractAgent, AbstractMemory (installed with the gateway): Runtime owns the LLM/tool/media integration boundary; Gateway uses its discovery and run facades for prompt-cache controls, generated and edited media, voice, audio and music, and KG-backed bundle execution (src/abstractgateway/hosts/bundle_host.py)
Apps (optional): AbstractFlow (authoring/bundling), AbstractCode, AbstractObserver, AbstractContinuum, AbstractEntity, AbstractAssistant

Related repos:

AbstractFramework: https://github.com/lpalbou/AbstractFramework
AbstractCore: https://github.com/lpalbou/abstractcore
AbstractRuntime: https://github.com/lpalbou/abstractruntime

Quickstart: your own machine

pip install abstractgateway
abstractgateway serve

On a first run with nothing configured, serve binds 127.0.0.1:8080, turns on user auth, creates the admin user, and prints a one-time link (http://127.0.0.1:8080/console#claim=...). Open it in a browser on the same machine: you are signed in as the admin and a short first-run guide helps you pick a local engine, a default model and the browser apps. A new link: abstractgateway claim --open. Start the gateway at login: abstractgateway service install. See docs/first-run.md.

Local models and engines

The console's Providers page (its Local providers cards) and its Models page (and the matching commands) install a local engine, download a model that fits this machine and delete a download you no longer need, without a terminal. They are AbstractCore's model browser and engine installer, shown inside the gateway:

abstractgateway engines status --probe          # Ollama, LM Studio, MLX, llama.cpp, ...
abstractgateway engines install ollama --dry-run # the exact command, nothing runs
abstractgateway models catalog --fits           # models that fit this machine
abstractgateway models download ollama qwen3:8b
abstractgateway models list                     # installed models with sizes

The commands talk to the running gateway (admin rules and audit log apply); add --local to run them in-process instead. Engine installs run on the gateway host and are on by default for a loopback gateway, and for someone at the gateway machine whatever it listens on (allow_engine_install). See docs/engines.md, docs/model-downloads.md and docs/console.md.

Admins can turn on the OpenAI API on the console's OpenAI API page: any OpenAI SDK or app then uses this gateway's models at http://<gateway>/v1, with a named API key per app, made on that page (valid at /v1 only, revocable one at a time).

Browser apps, network access and the tray

abstractgateway apps install observer --launch   # Flow, Code, Observer, Continuum, Entity, Note, Assistant
abstractgateway apps open observer               # a one-time signed-in link
abstractgateway network set lan                  # let your local network reach the gateway
abstractgateway network restart                  # apply it now
abstractgateway console                          # the terminal console, signed in
abstractgateway update --check                   # what the newest AbstractFramework release changes
abstractgateway update                           # ... and install it (installer installs)

The gateway installs Node.js when needed, installs the browser apps from npm, runs them and opens them already signed in (docs/apps.md). The network setting decides who can reach the gateway: localhost, lan or internet (docs/configuration.md). With pip install "abstractgateway[tray]", serve also shows a menu bar / system tray icon (docs/tray.md).

Quickstart (HTTP server, bundle mode, explicit configuration)

pip install abstractgateway

export ABSTRACTGATEWAY_DATA_DIR="$PWD/runtime/gateway"

# Optional: set only for a custom bundle registry. When unset, Gateway uses
# the packaged shipped bundle directory containing basic-agent.
# export ABSTRACTGATEWAY_FLOWS_DIR="/path/to/bundles"

# User accounts: the sign-in path for the console and the browser apps.
export ABSTRACTGATEWAY_USER_AUTH=1

abstractgateway serve --host 127.0.0.1 --port 8080

OpenAPI docs (Swagger UI): http://127.0.0.1:8080/docs

Smoke checks:

curl -sS "http://127.0.0.1:8080/api/health"

curl -sS -H "Authorization: Bearer $(cat "$ABSTRACTGATEWAY_DATA_DIR/auth/bootstrap-admin-token")" \
  "http://127.0.0.1:8080/api/gateway/bundles"

That last call lists the workflows a fresh install already serves — including a verify-gated coding agent (coding-agent), deep-research, and co-scientist, alongside the default basic-agent. See docs/shipped-workflows.md.

User accounts and the console

With user accounts on (the default of a plain serve, or ABSTRACTGATEWAY_USER_AUTH=1), the gateway creates default/admin, writes its first token to <data dir>/auth/bootstrap-admin-token, and routes each user to their own runtime and data plane (1 user = 1 runtime). Admins manage users from the console or /api/gateway/admin/users; user tokens are returned once and stored only as hashes. Browser apps exchange a user token for an opaque session (POST /api/gateway/session/login, HTTP-only cookie plus CSRF token) instead of keeping the token. ABSTRACTGATEWAY_AUTH_TOKEN is a shared server/operator token, not a browser sign-in token. See docs/security.md.

The built-in console at /console groups its pages in the sidebar: Accounts (users and entities in one table, with each account's email settings and activity), Work (workflows, runtimes, apps), Models (providers, models, engines, multimodal capability defaults) and System (host resources, a sandbox, network access); Setup at the bottom reruns the setup guide. An administrator sees every account; anyone else sees their own account and the entities they created. The same configuration surfaces exist in a terminal through the abstractgateway-console Rust app (the installer builds it; by hand, cargo install abstractgateway-console); abstractgateway console opens it signed in. See docs/console.md.

Each user can connect their own mailbox (Accounts → Email on their own row in the web console, @ on their own row in the terminal console, or /api/gateway/me/email): automations can run when mail arrives, results and approvals can be emailed to the user, and agents can use email tools when an administrator makes them available. Further mailboxes are Read only (automations only read them) or Read and write (a flow's mail steps may mark, move, delete and send), your choice per mailbox. See docs/email.md.

The AbstractAssistant apps on the Apple Watch and iPhone register with the gateway at sign-in and get alerts (approvals, questions, a flow's Notify me, automation results) while the app is closed, through a push relay that never sees any content. See docs/push.md.

Docker server

Release images are published to GHCR. The default image is the light, portable server image:

docker pull ghcr.io/lpalbou/abstractgateway:0.13.1

NVIDIA hosts can try the experimental full GPU image when local vLLM/HuggingFace/Diffusers engines are wanted. This image is published best-effort until it has a real CUDA build and smoke gate:

docker pull ghcr.io/lpalbou/abstractgateway:0.13.1-gpu

The abstractgateway-server and abstractgateway-server-nvidia GHCR names are published as aliases for existing deployments; use abstractgateway for new ones.

The image installs the base abstractgateway package: HTTP server, AbstractRuntime, Runtime-owned provider/tool and multimodal facades, OpenAI-compatible text/media providers, provider/session prompt-cache helpers, AbstractMemory/LanceDB KG support, AbstractAgent, and AbstractFlow compatibility. Local sentence-transformer embeddings and hardware-local inference engines are explicit extras so the light server image does not pull PyTorch/CUDA runtime packages. Remote text embeddings remain part of the light profile through the embedding.text capability route: point it at OpenAI, OpenRouter, Portkey, LM Studio, vLLM, any OpenAI-compatible embeddings endpoint, or a remote AbstractCore server.

AbstractFlow note:

You do not need the abstractflow Python package to run .flow bundles. You only need it to author bundles; the gateway runs bundles only (store VisualFlows through /api/gateway/visualflows/* and publish them as bundles).

docker run --rm --name abstractgateway \
  -p 8080:8080 \
  -e ABSTRACTGATEWAY_DATA_DIR=/data \
  -e ABSTRACTGATEWAY_USER_AUTH=1 \
  -e LMSTUDIO_BASE_URL="http://host.docker.internal:1234/v1" \
  -v "$PWD/runtime:/data" \
  ghcr.io/lpalbou/abstractgateway:latest

On first start, the container creates default/admin and writes the admin user token to runtime/auth/bootstrap-admin-token. Use that token in /console, then rotate it or create named users from the console.

Configure framework model defaults through execution-host capability routes:

docker exec abstractgateway abstractgateway-config set-default input.text \
  --provider lmstudio \
  --model your-model \
  --base-url http://host.docker.internal:1234/v1

In user-auth mode this writes the Gateway baseline Core config at /data/config/abstractcore.json. Per-user runtime overrides use the same Core schema under /data/users/<tenant>/<runtime>/runtime/config/abstractcore.json; use abstractgateway-config set-default --scope user --user alice ... for operator-side scripting.

output.text is a compatibility alias for this same text route. Gateway reports it as a read-only view of input.text, so LLM text input and output do not drift to different default models.

On Apple Silicon, keep Metal/MLX inference native on macOS and run the lightweight Gateway container as the transport/control plane. Point OPENAI_BASE_URL at a generic host-native OpenAI-compatible endpoint such as Docker Model Runner (http://model-runner.docker.internal/engines/v1) or mlx_lm.server on a host port. For named providers, use LMSTUDIO_BASE_URL=http://host.docker.internal:1234/v1 or OLLAMA_BASE_URL=http://host.docker.internal:11434. For native non-Docker installs with local engines, use pip install "abstractgateway[apple]" on Apple Silicon, and pip install "abstractgateway[gpu]" on GPU workstations or NVIDIA Docker builds. For a minimal Apple-local Gateway + Flow setup, see docs/apple-local-gateway-flow.md.

Compose and deployment details: docs/deployment.md.

Capability scope

Direct, run-scoped Gateway routes (each creates a durable child run and returns artifacts):

voice and audio: POST /api/gateway/runs/{run_id}/voice/tts (with speed and one_shot), POST /api/gateway/runs/{run_id}/audio/transcribe
images: POST /api/gateway/runs/{run_id}/images/generate, /images/edit, /images/upscale
video: POST /api/gateway/runs/{run_id}/videos/generate, /videos/from_image
music: POST /api/gateway/runs/{run_id}/music/generate
run data: GET /api/gateway/runs/{run_id}/input_data, GET /api/gateway/runs/{run_id}/history_bundle

Discovery and catalogs for thin clients:

GET /api/gateway/discovery/capabilities: a versioned contract of packages, plugins, endpoints and feature gates, with common.readiness
voice, speech, transcription, music and vision catalogs (/api/gateway/voice/voices, /audio/*/models, /audio/music/providers, /vision/*), each with a gateway_catalog_v1 envelope and canonical items; ?language= filters the voice catalog
the voice library: /api/gateway/voice/languages, /voice/clones (list, read, create from a recording, rename, delete), /voice/design (a voice from a description) and /voice/compatibility (which engine supports which voice feature); with user accounts on, each account has its own voices in front of a shared library the administrator fills; see docs/api.md
/api/gateway/artifacts/search: cross-run, session and run artifact search
/api/gateway/kg/query: KG memory queries (LanceDB by default)
/api/gateway/prompt_cache/* and /api/gateway/sessions/{session_id}/prompt_cache/*: provider-dependent prompt-cache controls

Media generation needs a configured backend for the route (the console's Multimodal tab). Image and video routes stream abstract.progress records on the child run's ledger; prompt-cache support depends on the provider and model. Details: docs/api.md and docs/faq.md.

Client contract (replay-first)

Clients start runs: POST /api/gateway/runs/start
- optional thinking sets the run-scoped _runtime.thinking default used by Flow LLM/Agent nodes and AbstractAgent adapters when Core/provider support reasoning controls
- flow_id: "@default" with an agent interface runs the gateway's default agent workflow for that interface; every start answers resolved_workflow
- input_data._runtime.stream: true also sends the model's reply live (llm.delta frames on the ledger stream)
Clients create automations: a workflow run on a trigger (an interval, a daily or weekly time, new mail in one of your mailboxes, a feed item, a signed webhook call, or only when asked), each run readable as a chat turn, quiet unless a run asks for attention or fails: /api/gateway/automations* (docs/automations.md); feeds and webhooks are trigger connections (/api/gateway/triggers/*, the console's Triggers page)
Clients follow what needs the person on one stream per account: run starts and ends, automation results, approvals and questions waiting, wakes an agent scheduled with schedule_run, notifications shown: GET /api/gateway/me/events (catch-up) and /me/events/stream (SSE) (docs/events-examples.md)
Clients read back what happened after a run: what arrived, how it ended, the alerts it raised (a flow's Notify me chooses its channels: tray, watch, phone, email, console) and where each was delivered: GET /api/gateway/runs/{run_id}/after (docs/api.md)
Clients act by submitting durable commands: POST /api/gateway/commands
- supported types: pause|resume|cancel|conclude|emit_event|update_schedule|compact_memory|inject_guidance, plus the automation.* commands for an automation
Clients render by replaying/streaming the durable ledger:
- replay: GET /api/gateway/runs/{run_id}/ledger?after=...
- stream (SSE): GET /api/gateway/runs/{run_id}/ledger/stream?after=...

A run's owner can browse and preview the run's workspace folder (GET /api/gateway/runs/{run_id}/workspace, /files, /content), and GET /api/gateway/about reports the versions the gateway runs without sign-in.

Model residency is available from a shell through abstractgateway models loaded|load|unload (docs/console.md).

See docs/api.md for curl examples and the live OpenAPI spec (/openapi.json).

Install

Base remote-light server

Requires Python >=3.10 (see pyproject.toml).

The base install is the remote-light HTTP/SSE server: Gateway, Runtime, Agent, Flow compatibility, Runtime-owned provider/tool and multimodal facades, and LanceDB-backed Memory. It intentionally excludes local sentence-transformer embeddings and hardware-local inference engines so Linux installs do not pull PyTorch/CUDA packages. Remote embeddings and remote multimodal input/output still work in this profile through hosted providers, OpenAI-compatible endpoints, or a remote AbstractCore server.

pip install abstractgateway

Optional extras

abstractgateway[apple]: full native macOS Python profile with Apple-local engines and all non-NVIDIA framework capabilities
abstractgateway[gpu]: full local GPU profile with vLLM/HuggingFace, local Diffusers image generation, local voice engines, music, and KG memory; this is also the NVIDIA Docker install profile
abstractgateway[embeddings]: local sentence-transformer embeddings for semantic KG queries
abstractgateway[tray]: a menu bar / system tray icon for abstractgateway serve (macOS, Windows, Linux) — open the console, pause/resume workflows, unload models, watch memory and GPU, restart or update; see docs/tray.md
abstractgateway[docs]: MkDocs site tooling
abstractgateway[dev]: local test/dev deps

KG memory nodes use Gateway's memory resolver. The default durable/vector backend is LanceDB; memory is process-local dev/test storage, and sqlite is structured-only when the installed AbstractMemory build exposes SQLiteTripleStore.

Gateway has a first-class config helper:

abstractgateway-config status
abstractgateway config init --env-file .env

For details on capability route defaults, store backends, and workflow sources, see docs/configuration.md.

Creating a `.flow` bundle (authoring)

Author the workflow in the AbstractFlow editor and publish it: the editor stores the VisualFlow on the gateway (/api/gateway/visualflows/*) and POST /api/gateway/visualflows/{flow_id}/publish packs it into a bundle. From Python, AbstractRuntime packs a bundle from VisualFlow JSON files:

from abstractruntime.workflow_bundle import pack_workflow_bundle

pack_workflow_bundle(
    root_flow_json="/path/to/root.json",
    out_path="/path/to/bundles/my-bundle@0.1.0.flow",
    bundle_id="my-bundle",
    bundle_version="0.1.0",
    flows_dir="/path/to/flows",
)

Upload it with POST /api/gateway/bundles/upload, or place it in ABSTRACTGATEWAY_FLOWS_DIR.

See docs/getting-started.md for running, split API/runner, and file→SQLite migration. Split mode, the worker pools (serve --pool-light/--pool-heavy/--pool-watchers), the run index (--run-index) and the garbage-collector tuning (--gc-tuning) are in docs/configuration.md.

Docs

Published docs site: https://www.lpalbou.info/AbstractGateway/

Docs index: docs/README.md
First run: docs/first-run.md
Getting started: docs/getting-started.md
Architecture: docs/architecture.md
API overview: docs/api.md
Automations: docs/automations.md
Events and triggers, examples: docs/events-examples.md
Email: docs/email.md
Watch and iPhone alerts (push): docs/push.md
OpenAI-compatible API: docs/openai-api.md
Configuration: docs/configuration.md
Consoles: docs/console.md
Apps: docs/apps.md
Local engines: docs/engines.md
Model downloads: docs/model-downloads.md
Desktop tray: docs/tray.md
Security: docs/security.md
Deployment: docs/deployment.md
Shipped workflows: docs/shipped-workflows.md
FAQ: docs/faq.md
Troubleshooting: docs/troubleshooting.md
Operator tooling: docs/maintenance.md

Project: CHANGELOG.md · CONTRIBUTING.md · CODE_OF_CONDUCT.md · SECURITY.md · ACKNOWLEDGMENTS.md · LICENSE (MIT)

Name		Name	Last commit message	Last commit date
.github		.github
changelog.d		changelog.d
ci		ci
console-tui		console-tui
docker/abstractgateway-server		docker/abstractgateway-server
docs		docs
flows/bundles		flows/bundles
scripts		scripts
src/abstractgateway		src/abstractgateway
tests		tests
.dockerignore		.dockerignore
.gitignore		.gitignore
ACKNOWLEDGMENTS.md		ACKNOWLEDGMENTS.md
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
llms-full.txt		llms-full.txt
llms.txt		llms.txt
mkdocs.yml		mkdocs.yml
pyproject.toml		pyproject.toml
start-dev.sh		start-dev.sh

Navigation Menu

Repository navigation

About

Repository files navigation

AbstractGateway

AbstractFramework ecosystem

Quickstart: your own machine

Local models and engines

Browser apps, network access and the tray

Quickstart (HTTP server, bundle mode, explicit configuration)

User accounts and the console

Docker server

Capability scope

Client contract (replay-first)

Install

Base remote-light server

Optional extras

Creating a `.flow` bundle (authoring)

Docs

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

AbstractGateway

AbstractFramework ecosystem

Quickstart: your own machine

Local models and engines

Browser apps, network access and the tray

Quickstart (HTTP server, bundle mode, explicit configuration)

User accounts and the console

Docker server

Capability scope

Client contract (replay-first)

Install

Base remote-light server

Optional extras

Creating a .flow bundle (authoring)

Docs

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Creating a `.flow` bundle (authoring)