Key Concepts

Intent-Driven Computing

Coding is writing at the level where the computer thinks. mashin is writing at the level where you think.

The word “coding” means encoding: translating your intent into the machine’s language. mashin closes that gap. You describe what the system should do in mashinTalk, a declarative language that reads like a plan, not code. The platform handles the encoding.

mashinTalk isn’t natural language. It’s a small, structured vocabulary: machine, step, ask, compute, decide, call, remember. But it maps to how humans describe what intelligent systems should do. A compliance officer can read the permissions. A product manager can follow the steps. An LLM can write it.

When your machine wants to send an email, call an API, or query a database, it does not execute the action directly. It produces an intent: a structured description of what it wants to do. The runtime evaluates that intent against your governance policies, records the decision, and only then executes.

This is why governance in mashin is structural rather than bolted on. There is no way to bypass it because the language provides no mechanism for direct effect execution. Every external action passes through the same governance boundary.

The consequences are practical: every execution is replayable (the intent stream is complete), every action is auditable (every decision is recorded), and governance policies can be simulated before deployment (replay historical intents against new rules). One current limit, stated plainly: replay of runs that combine suspension (a wait for) with randomness is not yet supported: the random values are not reproduced across the resume.

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
  behaves
    compute greet
      {greeting: "Hello, " + input.name + "!"}
  verifies
    test "greets by name"
      given {name: "Ada"}
      expect {greeting: "Hello, Ada!"}

Steps

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

Step	Purpose	I/O
compute	Pure computation (math, data transformation)	None
ask ... using	Send a task to an LLM	Governed
ask ... from	Call an action machine (HTTP, file, database)	Governed
decide	Branch based on conditions	None
remember	Store information in semantic memory	Governed
recall	Retrieve information from memory	Governed
wait for	Suspend execution until an event occurs	Governed

Steps execute in order within a behaves 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
  permissions
    allowed to
      model
      network.http
    not allowed to
      filesystem
    requires approval for
      network.http.post

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 added as middleware or prompt instructions that the model can ignore. In mashin, governance is structural: every action begins as an intent, and the runtime decides whether to allow it. The capability to bypass governance does not exist in the language because the language does not provide direct effect execution.

Computer

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

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

You can have multiple computers (personal, work) on one machine. The cloud runs one computer per organization. See Computers for the full guide.

Running and turning on

Running exercises the machine. Turning it on changes how it exists.

A run is one execution with one receipt, and then it is over. Turning a machine on runs nothing by itself. It pins the version you promoted to a computer, brings up the surfaces the machine declared, and leaves it reachable and governed until you turn it off. Both verbs take a place, and for both the default is here, so running on another computer is still just running.

See Running and Turning On for the full distinction, including the case where turning a machine on is not what you meant.

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

• Machine Anatomy - Deep dive into how machines are structured
• Governance - How permissions, trust levels, and approval gates work
• Platform Overview - How all the platform components fit together