Surfaces: Pages

The page surface turns a machine into a web application. Instead of returning JSON to an API client, the machine serves a web page that end users interact with in a browser. This is Kanvas, the interface layer where machines become visible to the people who use them.

Declaring a page surface

machine order_dashboard
  accepts
    customer_id as text
  responds with
    orders as list
    total_value as number
  behaves
    ask fetch_orders, from: "@mashin/actions/http/get"
      url: "https://api.internal.com/orders?customer=${input.customer_id}"
      returns
        body as map
    compute format
      {orders: steps.fetch_orders.body.orders, total_value: steps.fetch_orders.body.total}
  expresses
    page
      path: "/"
      title: "Order Dashboard"
  ensures
    permissions
      allowed to
        network.http to "api.internal.com"
  verifies
    test "loads a customer's orders"
      assuming fetch_orders {body: {orders: [{id: "ord_1", amount: 50}], total: 50}}
      given {customer_id: "cus_1"}
      expect {orders: [{id: "ord_1", amount: 50}], total_value: 50}

This machine is now accessible as a web page at the root path.

Configuration options

Config	Required	Default	Description
path	Yes	-	URL path for the page
title	No	Machine name	Page title shown in the browser tab

What Kanvas renders

When a browser visits the page URL, Kanvas renders the machine’s output as an interactive web page. The rendering is based on the output structure:

• Lists render as tables or card grids
• Text renders as formatted content
• Numbers render as metrics or charts
• Maps render as structured data views
• Nested structures render as expandable sections

You do not write HTML, CSS, or React. Kanvas generates the interface from the machine’s typed output. The output types from responds with determine the rendering.

How pages differ from other surfaces

Concern	API surface	Page surface
Client	HTTP client (code)	Browser (human)
Response	JSON	HTML page
Interaction	Single request/response	Navigable interface
Authentication	Token/API key	Session-based

Combining page with WebSocket

For live dashboards, combine page and websocket surfaces:

machine live_dashboard

  responds with
    metrics as map

  behaves
    compute snapshot
      {metrics: {cpu: 0.42, requests_per_minute: 120}}

  expresses
    page
      path: "/dashboard"
      title: "System Metrics"
    websocket
      path: "/ws/metrics"

  verifies
    test "serves a metrics snapshot"
      given {}
      expect {metrics: {cpu: 0.42, requests_per_minute: 120}}

The page surface serves the initial view. The WebSocket surface pushes live updates. Kanvas wires these together automatically: when a page and a WebSocket share the same machine, the page subscribes to the WebSocket for real-time updates.

Combining page with API

machine data_explorer

  accepts
    query as text, is required

  responds with
    rows as list

  behaves
    compute run_query
      {rows: [{query: input.query, matched: 0}]}

  expresses
    page
      path: "/explore"
      title: "Data Explorer"
    api
      path: "/api/query"
      method: "POST"
      auth: oauth, api_key

  verifies
    test "answers a query"
      given {query: "status:open"}
      expect {rows: [{query: "status:open", matched: 0}]}

The page surface provides a visual interface. The API surface provides a programmatic one. Same machine, same governance, same ledger.

Multiple pages

A machine can serve multiple pages:

expresses
  page
    path: "/"
    title: "Dashboard"
  page
    path: "/settings"
    title: "Settings"

Accessing pages

Local computer

http://localhost:9000/
http://localhost:9000/dashboard

Cloud computer

https://myorg.mashin.live/
https://myorg.mashin.live/dashboard

Via tunnel

mashin tunnel order_dashboard.mashin
# Shows: https://mashin.live/tunnel/order_dashboard/

Authentication for pages

Page surfaces use session-based authentication. When a user visits the page, they are prompted to sign in (or the session is validated if they are already signed in). This is different from API surfaces, which use token-based authentication.

For public pages that do not require sign-in, the machine’s governance still applies. The user’s identity is “anonymous” in the ledger.

Governance

Every page view is governed:

1. The user is authenticated (session-based)
2. The machine’s ensures permissions are checked
3. The machine executes
4. A SurfaceAccess event is recorded with :page surface
5. Kanvas renders the result

Navigation within the page (clicking a link, expanding a section) may trigger additional machine executions, each individually governed and recorded.

When to use pages

Scenario	Surface
Internal dashboard for your team	Page
Customer-facing portal	Page
Admin tool	Page + API
Public demo	Page (no auth)
Data API for other systems	API only

Pages are the right choice when a human needs to see and interact with the machine’s output directly in a browser.

Next steps

• MCP - AI tool calling
• REST API - HTTP endpoints
• Surfaces overview - All surface types