Computers

A computer 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.” A computer is where intents become actions: every intent produced by your machines is mediated within the computer’s governance context before execution. 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 computer

Every computer has four properties: it is owned (belongs to a user or organization), persistent (state survives restarts), networked (can communicate with other computers), and equivalent (every computer is a full peer on the Kortex, an equally valid position from which to observe and manage the entire network).

~/.mashin/computers/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 computers

You can have multiple computers on one machine:

Computer	Use case
default	Personal development
work	Organization projects
staging	Pre-production testing

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

Computer settings

Each computer has settings that affect how machines run:

Default model

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

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

API credentials

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

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

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

Token budgets

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

computer.budget.daily_limit = 10.00
computer.budget.per_run_limit = 1.00

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

Computer identity

Every computer 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 computers communicate over kortex (the network fabric)

The identity is hybrid and post-quantum by default: it pairs a classical Ed25519 key (the computer’s stable identifier, also used to establish encrypted connections) with an ML-DSA-65 post-quantum signing key (NIST FIPS 204), which signs ledger entries and attestations. See behavioral ledger for how that carries through to your history.

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

Computer lifecycle

Initialize a computer

mashin setup

Walks you through the provider, the API key, and the deployment mode, then creates the database, git history, and credential store.

Check computer status

mashin computer status

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

Run a machine in the current computer

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

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

Where computers run

The same computer concept works everywhere:

Environment	What it looks like
Laptop	A directory under ~/.mashin/computers/
Docker	A container with the computer mounted as a volume
Cloud (mashin.live)	A managed computer in the cloud, one per organization
Mac Mini / server	A headless process running your computer on disk

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

Computers and kortex

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

Three tiers of networking:

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

Inter-computer connections use hybrid post-quantum key agreement by default: the encrypted tunnel combines classical X25519 with ML-KEM-768 (NIST FIPS 203), and inter-computer TLS uses the hybrid x25519mlkem768 group. Combining the classical and post-quantum exchanges means the connection is never weaker than classical, and traffic recorded today cannot be decrypted later by a quantum computer.

Exposing local machines to the internet

Local computers are not directly reachable from the internet. The Kortex tunnel solves this by opening a persistent WebSocket connection to the cloud server and relaying requests to your local computer.

How it works

Any machine with an expresses section is automatically exposed through the tunnel when your computer starts. You do not need to configure anything manually. The flow:

1. Your computer boots and detects machines with expresses sections
2. A tunnel agent connects to the cloud and registers those machines
3. External clients reach your machines on your organization’s own cloud host, at https://{your-org}.mashin.cloud/{machine-slug}
4. Requests flow through the cloud relay to your desktop, execute locally, and return results

A machine’s address always names the organization it belongs to. There is no shared address that any organization’s machine answers on.

All surface types work through the tunnel: api, webhook, page, mcp, a2a, and websocket.

Using the CLI

You can also start a tunnel manually for a specific machine:

mashin tunnel my_machine.mashin

The CLI shows the public URL when the tunnel connects. Press Ctrl+C to stop.

A manual tunnel gets its own host, https://{subdomain}.tunnel.mashin.cloud, and forwards the path through to your computer unchanged. So a webhook declared at /outlook answers at https://{subdomain}.tunnel.mashin.cloud/webhooks/outlook: the same /webhooks shape, on a different host.

Webhook integration

When a machine declares a webhook surface, the tunnel provides a public URL that webhook providers (Microsoft Graph, Stripe, GitHub) can deliver to. Your machine accesses this URL via context.computer.webhook_urls:

machine outlook_bridge

  responds with
    subscription_id as text

  behaves
    // context.computer.webhook_urls["/outlook"] resolves to the one address the
    // platform serves for that declared path, on your organization's own host:
    // https://your-org.mashin.cloud/webhooks/outlook
    ask register, from: "@mashin/actions/http/post"
      url: "https://graph.microsoft.com/v1.0/subscriptions"
      body: {changeType: "created", notificationUrl: context.computer.webhook_urls["/outlook"], resource: "me/mailFolders('Inbox')/messages"}

    compute done
      {subscription_id: register.body.id}

  expresses
    webhook
      path: "/outlook"
      provider: microsoft

  verifies
    test "registers the webhook subscription"
      assuming register {body: {id: "sub_123"}, status: 201, headers: {}}
      given {}
      expect {subscription_id: "sub_123"}

Cloud vs local computers

Behavior	Cloud computer	Local computer with tunnel
Reachability	Direct (subdomain URL)	Via tunnel relay
Execution	On cloud server	On your machine
Governance	Same	Same
Ledger	Cloud database	Local database
Latency	Lower (no relay hop)	Slightly higher (relay roundtrip)
Availability	Always on	Only while tunnel is connected

What the relay can see

A tunnel puts mashin.cloud in the path between a caller and your computer, so it is worth being precise about what that means.

Your computer publishes a sealing key in its agent card, under mashinGovernance.sealing. A caller that seals its request to that key sends bytes the relay cannot read. The relay carries the routing details it needs to deliver them, which computer, which machine, how large, how long it took, and whether it worked, and the result comes back sealed to an ephemeral key only that caller holds.

A caller that does not seal sends plaintext, and the relay holds it: the method, path, headers, body, and query on the way in, and the result on the way out. Sealing is the caller’s choice, not a switch on your computer, and the common tunnel callers, a webhook from another service or a mobile shortcut, do not seal. Publishing a sealing key makes the sealed path available; it does not close the readable one.

Two different things are sometimes both called “the relay”, and only one of them has this property. Traffic between your own computers travels over an encrypted mesh, and the relay that forwards those packets holds no key for them at all. The tunnel above is the other one.

To check what a caller will see:

curl -s https://{subdomain}.mashin.cloud/a2a/{slug} | jq '.mashinGovernance.sealing'

A key means the sealed path is available to callers. null means your computer advertised none, and every request through the tunnel is readable to the relay.

Koda tunnel management

From Koda or any tool context, you can manage tunnels programmatically:

• TunnelSupervisor.tunnel_status() returns state, registered machines, and cloud URL
• TunnelSupervisor.start_tunnel() starts with auto-detected machines
• TunnelSupervisor.stop_tunnel() disconnects the tunnel
• TunnelSupervisor.add_machine("slug") adds a machine to the active tunnel
• TunnelSupervisor.remove_machine("slug") removes a machine

Troubleshooting

“Not authenticated”: Run mashin login --token YOUR_API_KEY to store your API key.

“No org_id configured”: Your credentials file needs an org_id field. Run mashin login with an org-scoped API key.

Tunnel not starting: Check that at least one machine has an expresses section. The tunnel only starts when there are machines to expose.

Slow responses: The tunnel adds a relay roundtrip. For latency-sensitive workloads, deploy to a cloud computer instead.

Try it

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

mashin setup
mashin secrets set ANTHROPIC_API_KEY your-key-here
mashin run greeter --input '{"name": "World"}'
mashin computer status

Next steps

• Platform Overview - How all the platform components fit together
• Deployment - Getting computers to production
• Publishing - Sharing machines via the registry
• koda - The IDE that manages your computers