Skip to main content

Architecture

This page explains how Imaginne is put together, in terms meant for users and administrators — without getting into infrastructure details.

Overview​

Surfaces talk to the Engine; the Engine talks to the Gateway (models) and the Platform (identity and policy); the Gateway talks to the model.
The four surfaces, the Engine (the agent), the Gateway (models), and the Platform (control).

Imaginne has four parts that matter to you:

  • Surfaces — Desktop, terminal (TUI), VS Code, and the browser chat. This is where you talk to the agent. They are "just" the interface: all the reasoning happens in the Engine.
  • Engine — the agent. It interprets your request, decides which tools to use (read/write files, run commands, trigger skills), drives the conversation turn by turn, and produces the response. The Engine is the same whether it runs on your machine or on the server.
  • Gateway — the model broker. It is the only component allowed to talk to the model vendor.
  • Platform — the control plane: identity (who you are), policy (what your organization allows), skill governance, and the relay for remote sessions. The Platform does not run your tools and does not see your files.
Golden rule

The Engine never calls the model directly — always through the Gateway. And the Gateway is the only one that talks to the model vendor. This concentrates credentials, model policy, and metering in a single place.

The path of a message​

You write a request; the surface hands it to the local Engine; the Engine resolves policy with the Platform and calls the Gateway, which calls the model; the response streams back.
From your message to the model and back — streaming.
  1. You write a request in the surface.
  2. The surface hands it to the Engine.
  3. The Engine resolves the active policy with the Platform (which models and skills you may use) and assembles the context (your message, relevant files, project memory).
  4. The Engine calls the Gateway, which calls the model.
  5. The response streams back. If the agent decides to use a tool (edit a file, run a command, trigger a skill), it does so locally — asking for confirmation according to your autonomy.

Where the agent runs​

Local-first on the app surfaces; hosted in the web chat.
Two topologies, the same Engine.
  • Local-first (Desktop, terminal, VS Code). The Engine runs on your machine. It reads and writes your files, runs commands in your shell, and runs skills locally. Only the content the model needs to read leaves the machine, headed for the Gateway.
  • Hosted (browser chat). Since nothing is installed, the same Engine runs on Imaginne's servers. The Platform authenticates and relays the streaming between the browser and the Engine.

The privacy implications of this are covered in Local execution & privacy.

Why this separation matters​

  • You work where the files are — no exporting and pasting.
  • The organization has a single point of control — the Platform decides policy; the Gateway enforces credentials and metering.
  • Switching models doesn't change the product — the surfaces and the Engine speak in logical names (nnumbers, nnumbers-code); the model vendor behind them can change without affecting you. See Models.

Keep reading​

Local execution & privacy

What leaves your machine and what stays.

Open →Identity & login

The single token that works everywhere.

Open →Organizations & policies

How your organization governs the agent.

Open →