Skip to content
mashin

Cells

A cell is your mashin environment. It is a persistent, networked computing unit that contains your machines, their execution history, credentials, and settings. Think of it as “your mashin.” Whether it runs on your laptop, a Docker container, a Mac Mini in your closet, or in the cloud, it has the same shape and the same capabilities.

What is in a cell

Every cell has three properties: it is owned (belongs to a user or organization), persistent (state survives restarts), and networked (can communicate with other cells).

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

The database holds everything: machine definitions, execution runs, behavioral ledger entries, vector embeddings for memory. The git history tracks every change to every machine. Credentials are encrypted at rest.

Multiple cells

You can have multiple cells on one machine:

CellUse case
defaultPersonal development
workOrganization projects
stagingPre-production testing

Each cell is isolated. Different credentials, different machines, different execution history. Switch between them in koda or via the CLI.

Cell settings

Each cell has settings that affect how machines run:

Default model

Configure the default reasoning provider so machines that omit using: get a sensible default:

cell.default_model = "anthropic:claude-sonnet-4-6"

API credentials

Store API keys for reasoning providers, external services, and machine dependencies:

mashin credentials set anthropic_api_key sk-ant-...
mashin credentials set openai_api_key sk-...

Credentials are encrypted and scoped to the cell. Machines declare their requirements in ensures > needs, and the cell satisfies them at runtime.

Token budgets

Set spending limits per machine, per run, or per day:

cell.budget.daily_limit = 10.00
cell.budget.per_run_limit = 1.00

If a run would exceed the budget, the governance interpreter denies the step.

Cell identity

Every cell has a cryptographic identity. This identity is used for:

  • Signing behavioral ledger entries (provenance)
  • Authenticating with kura (the registry) when publishing or pulling machines
  • Establishing trust when cells communicate over kortex (the network fabric)

You do not need to manage this identity manually. It is created when the cell is initialized and used automatically.

Cell lifecycle

Initialize a cell

Terminal window
mashin cell init

Creates the database, git history, and credential store.

Check cell status

Terminal window
mashin cell status

Shows the current cell, its machines, recent runs, and health.

Run a machine in the current cell

Terminal window
mashin run email_triage --input '{"subject": "Invoice", "body": "Payment due"}'

The machine runs in the cell’s context: using the cell’s credentials, respecting the cell’s budgets, recording to the cell’s ledger.

Where cells run

The same cell concept works everywhere:

EnvironmentWhat it looks like
LaptopA directory under ~/.mashin/cells/
DockerA container with the cell mounted as a volume
Cloud (mashin.live)A managed cell in the cloud, one per organization
Mac Mini / serverA headless BEAM process with the cell on disk

Code does not change between environments. A machine that runs in your laptop cell runs identically in a cloud cell. The behavioral ledger, credentials, and governance all work the same way.

Cells and kortex

Cells can communicate with each other through kortex, the governed network fabric. A machine in your cell can call a machine in another cell. The call goes through governance on both sides: your cell checks that you are allowed to make the call, and the remote cell checks that you are authorized to invoke that machine.

Three tiers of networking:

  • Local: cells on the same machine, zero configuration
  • Organizational: cells within the same organization, deployment-backed
  • Cross-organization: cells across organizations, portable governance

Try it

Initialize a new cell, set up an API credential, and run a simple machine. Then check the cell status to see the run recorded in the behavioral ledger.

Terminal window
mashin cell init --name dev
mashin credentials set anthropic_api_key your-key-here
mashin run greeter --input '{"name": "World"}'
mashin cell status

Next steps