Skip to content
mashin

Key Concepts

Machine

A machine is the fundamental unit in mashin. It has a name, accepts inputs, produces outputs, and implements behavior through steps. Every machine is a .mashin file.

machine greeter
  accepts
    name as text, is required
  responds with
    greeting as text
  implements
    compute greet
      {greeting: "Hello, " + input.name + "!"}

Steps

Steps are the actions a machine performs. Each step has a type that determines what it can do.

StepPurposeI/O
computePure computation (math, data transformation)None
ask ... usingSend a task to an LLMGoverned
ask ... fromCall an effect machine (HTTP, file, database)Governed
decideBranch based on conditionsNone
rememberStore information in semantic memoryGoverned
recallRetrieve information from memoryGoverned
wait forSuspend execution until an event occursGoverned

Steps execute in order within an implements section. Each step’s output is available to subsequent steps via steps.<name>.<field>.

Governance

Governance is what makes mashin different from every other AI framework. The ensures section declares what a machine is and is not allowed to do.

ensures
  allowed to reason
  allowed to call "@mashin/actions/http/get"
  not allowed to file_write
  requires approval for send_email

These are not suggestions. The runtime enforces them. If a machine tries to do something it is not allowed to do, the execution stops and the denial is recorded in the behavioral ledger.

Why this matters: In other frameworks, an LLM agent can call any tool, access any API, and perform any action. Governance is bolted on as middleware or prompt instructions that the model can ignore. In mashin, governance is structural. The capability to bypass it does not exist.

Cell

A cell is your mashin environment. It contains your machines, their execution history, credentials, and settings. Every cell has the same shape whether it runs on your laptop, a Docker container, or in the cloud.

~/.mashin/cells/default/
  mashin.db          # machines, runs, ledger, vectors
  history.git/       # version control for machines
  credentials.db     # encrypted API keys and secrets

You can have multiple cells (personal, work) on one machine. The cloud runs one cell per organization. See Cells for the full guide.

Behavioral Ledger

Every machine execution produces a trace in the behavioral ledger. The trace records:

  • What steps ran and in what order
  • What the LLM was asked and what it returned
  • What governance decisions were made (allowed, denied, approval requested)
  • How many tokens were used and the estimated cost
  • A hash chain proving the trace was not tampered with

The ledger is not optional. It is produced automatically by every execution. This is how mashin delivers auditability.

Koda

Koda is the intelligent development environment. It is not an assistant or chatbot. The entire interface is intelligent: you work in projects, books, and sessions, and Koda provides context-aware help throughout. Koda’s cognitive operations are themselves mashin machines, so they are governed and auditable. See Koda for the full guide.

Kura

Kura is the package registry. You publish machines as krates (versioned packages) and discover machines published by others. Every published krate goes through 6-level cryptographic verification: file integrity, artifact identity, publisher authenticity, envelope integrity, registry attestation, and lineage provenance. See Publishing & Kura for details.

Next steps