How it works

Everything in Turgai is an object, run by a small core.

Agents, the tools they use, the rules a business sets and the parts of a product all run in Turgai as objects, each owning its state and working with the others by exchanging messages. You run the core where you choose, and you decide which models it uses and what every part may do.

Objects

Why everything is an object

Turgai builds everything from objects that keep their own state and ask each other to do things, because that is the shape a model can work with: it can find what an object offers, connect objects by messages, and add new ones.

The idea is older than language models, and it has worked before. NeXT built a whole computer on it: developers assembled programs from ready objects and connected them in Interface Builder instead of writing everything, and at CERN in 1990 Tim Berners-Lee wrote the first web browser and web server that way in about two months. Steve Jobs described objects as something like people, which know how to do things and remember what happened.

A black NeXTcube computer with its keyboard and mouse
A NeXTcube, the computer NeXT built around objects. Photo: Simon Claessen, CC BY-SA 2.0, resized.

Most software since then kept objects inside single programs, joined by integrations written by hand. A model can now do what Interface Builder did for a developer, from a plain request, and because each object keeps its own state and rules, what it puts together stays readable and safe to change. Each object also describes what it offers, so a model can use one it has never seen.

Actors

How an object stays alive on its own

A model can only use an object that is there when it is addressed, and many objects have to keep working while nobody is talking to them, so each needs a life of its own.

An object that keeps its state private and handles one message at a time is an actor, and it needs no locks, as Erlang showed. Turgai’s actors are also distributed, so calling one looks the same on this machine or another, and virtual, so an object is reached by a stable name and wakes when a message arrives. Each accepted change is journaled, and after a crash a new instance rebuilds the same object from that journal. Work left half done still needs its own rule for whether to retry it.

The trip desk keeps its state in memory and appends every change to its journal. A crash loses the memory, not the journal: the trip desk restarts and replays it line by line, back to where it was.

Agents

Agents are objects too

Since everything else is an object, the agent needs no special treatment. In Turgai’s agent layer, Hail, each agent is a distributed virtual actor like any other object, with its own name, journal and history.

It handles a message, calls tools and goes idle, and after a crash or restart it comes back with its history; a turn the crash cut short is closed rather than run twice. The model sits behind one interface, so an agent can move from a cloud API to a model on your own machine and keep its name, history and rules. A different model still behaves differently and has to be evaluated before you rely on it.

Other agents and Turgai’s conversations ask an agent for work in the same way, with one call.

let planner: Agent = try await actorSystem.agent(plannerID)
let plan: String = try await planner.respond(request)

Behaviors

How agents build objects that last

Because agents are objects, what an agent builds for you can be objects too, still working after the conversation that made them is over.

An agent writes them as behaviors, an idea borrowed from Erlang. A behavior is a short YAML document with an object’s fields and what it does with each message, built from a fixed set of conditions and steps with no code. That makes it safe for a model to write and lets the runtime check it before it runs, and redefining a behavior upgrades every object running it.

The trip desk from the main page is one such behavior. It confirms trips under €8,000 and sends the rest to the owner.

behavior: trip desk
fields:
  approveBelow: 8000
receive:
  - on: tripPlanned(trip, total)
    when: total < approveBelow
    do:
      - send: bookings.confirm(trip)
  - on: tripPlanned(trip, total)
    do:
      - send: owner.approve(trip)

Effects

How an agent’s permissions are enforced

An agent that can build and run things needs clear permissions, and they cannot depend on the model following instructions. Hail enforces them at the point where a tool is about to act.

Each tool declares the one effect it has, such as reading files under a path, and before it runs an authority derived from who is asking decides on that effect. It denies anything it does not explicitly grant. A granted effect is a token the compiler keeps from being stored, returned or handed to another actor.

This authority allows files inside one workspace and any network access, and it denies terminal commands simply by not naming them.

let authority = CompositeAuthority()
  .granting(for: FileEffect.self, decide: FileEffect.pathPolicy(scopedTo: workspace))
  .grantingAll(for: NetworkEffect.self)
// TerminalEffect isn't mentioned, so it's denied.

Control

Where Turgai runs and who controls it

Permissions settle what an agent may do when a tool acts. A business, especially a public body or a regulated one, also needs to know who runs the system, where its data is kept, who sets its rules and what record it leaves.

Turgai runs where you run it, on a Mac, on your own servers or in a cloud you choose, Linux included, with no Turgai-operated service in between. Conversations, memory and journals stay in your own storage, in one SQLite file or in PostgreSQL, and what leaves your machines is what you send out, such as calls to a cloud model or messages on Telegram. Each agent’s model, keys and instructions are your configuration, and so are client authentication, channels and permissions. The journal is the system’s record, and every permission decision can be reported to an audit observer you install.

An agent is described by a profile like this one, and the server starts with the authentication you require.

try TurgaiAgentProfile(
  id: "support",
  name: "Support",
  providerConfiguration: .server(ModelServer(
    software: .ollama, address: .localOllama, key: nil, context: .chosen(.standard))),
  modelID: "qwen3:8b",
  instructions: "Answer customers. Pass orders to the shop."
)

# the server, with the authentication you require
TURGAI_API_KEY=… turgai serve --directory /srv/turgai --api-auth api-key

Your product

Turgai next to your product

Running Turgai on your own terms leaves the practical question of how it connects to a product that already has users, data and code of its own.

Turgai owns agents and conversations, while your product keeps its users, decides who may reach each conversation and talks to Turgai over a WebSocket API, so Turgai never needs your user database. Your system itself joins as an object, either a short Swift actor that calls your existing API or a behavior in YAML, and agents then use it like any other object.

Your productusers, app, data, who sees what

plugs in models, keys, channels, storage and policy

TurgaiAPI and channels · conversations · memory · objects and behaviors
Hailagents · model routing · tools · scoped effects
Runtimedistributed virtual actors · journal and snapshots
Your product keeps its users and rules; Turgai and Hail run agents and objects; the runtime keeps them alive.

Swift

Why the language matters

Swift is Apple’s open-source, multi-paradigm programming language, with structured concurrency and actors built into the language itself. It is used for apps on Apple devices and for servers on Linux. Swift and the Swift logo are trademarks of Apple Inc.

Everything above, objects that keep their own state, messages between them, actors on one machine or many and permissions that cannot leak, usually rests on conventions every contributor has to remember, and conventions wear away as a codebase grows. Turgai is written in Swift because the language enforces most of these rules itself.

Messages are values, so two objects never change the same data. Actors keep each object’s state out of reach, distributed actors make a call across the network as checked as a local one, and ownership lets a permission exist that cannot leave its scope. Because actors can still interleave work while they wait, Hail orders an agent’s turns itself.

This warehouse is a complete object, and a model can discover it and call it like any other.

@Discoverable
public distributed actor Warehouse {
  private var received: [WarehouseNote] = []

  /// Tell the warehouse a refund was approved, so it expects the item back.
  public distributed func refundApproved(order: ShopOrder) {
    received.append(WarehouseNote(order: order.number, instruction: .expectReturn))
  }
}

Today

What runs today

Turgai is early, and below is exactly where it stands.

Built

  • Distributed virtual actors, journaled to files or PostgreSQL
  • Durable workflows with timers, so long-running work can wait for days and survive restarts
  • Self-hosted, with no Turgai-operated service in between
  • Hail agents with journaled turns, each on its own model: Apple on‑device, Ollama or llama.cpp, or OpenAI, Anthropic, Gemini and any OpenAI‑compatible endpoint
  • Behaviors in YAML, checked when defined and upgraded in place
  • Scoped effects with deny-by-default authorities, an audit hook and sealed secrets
  • A WebSocket conversation API with local, API-key or trusted-proxy auth, a Telegram channel and a Mac app

Next

  • A hosted option, for teams that don’t want to run their own servers
  • Objects compiled to WebAssembly, written in any language
  • Permissions on messages between agents, for many teams on one server
  • More channels beyond the API and Telegram, such as WhatsApp and Slack
  • A helper agent that prepares context handoffs for long tasks
  • The client app beyond the Mac
Early stage

Start small.
Keep adding.

An agent, a rule and a part of your product are built and changed in the same way, and new ones join while the rest keeps running.

Turgai is in early alpha. If you’d like to know more or see it running, write to us.