Dyadic Matrix

Enter The Matrix

A Matrix coordinates work across computers, gateway profiles and Iris, with a durable execution record. Author and export the same .dm source in the app and Terminal. Importing, reviewing, saving and running are separate actions.

1. In the app, tap the top-left sidebar button, then Matrices. It is available in Home and library sidebars, and in expanded phone navigation.
2. Choose Templates, then a Store item. Open Annotated Source to read or copy the commented .dm, or choose Use Template to start a separate draft. Download .dm keeps its exact source.
3. Edit Source or Blocks. Triggers has real controls for schedules, events, computer startup and a single date. Those controls edit the same source. Gateway And Profile Bindings uses the same themed code editor, with JSON highlighting.
4. Choose Review Matrix. Inspect effects, computers, bindings, triggers and spending information, then Approve And Save. Source, binding or automatic-run changes invalidate earlier review.
5. Start the saved Matrix explicitly. Open its run to inspect steps, copy horizontally scrolling evidence, and open its actual Black Box recording.

In Terminal, use /matrix, or dyadic matrix templates. Sign in with dyadic login before authenticated Workspace operations. A template is reviewed source, never an automatic permission grant.

# START HERE: this template uses no AI and runs no computer commands.
# Opening, importing, or reviewing this file does not start it.
# In Matrices, choose Review Matrix, approve/save the reviewed source, then Run.
# Its execution and available receipts appear in the same Black Box as other work.

matrix "checkpoint" {
    # A name identifies this stored workflow. Rename it to create your own Matrix.
    # This version is workflow metadata; Store package versions are separate.
    description "A durable first Matrix"
    version "1.0"

    # Steps give parts of the workflow a readable name in the run inspector.
    # print records literal text; it is not a shell command or a model request.
    step begin {
        print "Checkpoint started"
    }

    # A wait stores its deadline on the server and releases its worker.
    # You can close Terminal or the app; no local Bash process sleeps here.
    # Scheduler pickup is periodic, so this is not an exact real-time timer.
    wait 60s

    # This runs after the wait. Inspect each step and its recorded state.
    # Reaching the end proves workflow completion, not independent correctness.
    step finish {
        print "Checkpoint completed"
    }

    # There is no trigger block: this Matrix runs when you explicitly start it.
    # The Triggers controls can add a schedule, event, startup signal, or date.
    # Adding a trigger edits this same file. Automatic runs require explicit enablement.
}

Store Templates

The Store has a dedicated Matrices tab, also reachable from Matrices → Templates. These are self-contained source walkthroughs. Creating a draft starts nothing. Existing definitions and older drafts are not silently replaced when a template version changes.

Checkpoint and Event Checkpoint use no model calls or computer commands. Fleet Diagnostics requires your own paired computers. Reviewed Child explicitly invokes Iris and can incur normal charges. Read the comments and complete the same exact-source review as any authored Matrix.

The source editor supports keyboard undo and indentation. The JSON bindings editor follows the same design and theme. Triggers shows what is configured; Enable Automatic Runs is available only when a valid trigger exists. Turning it off saves a manual definition. Adding a trigger never enables an installed workflow by itself.

Build A Fleet Workflow

matrix "fleet-monitor" {
    description "Collect diagnostics, then prepare a report"
    version "1.0"
    trigger {
        schedule "08:00" every "weekday" zone "America/Chicago"
        event "docker.container.unhealthy"
        startup "home-server"
    }
    step collect {
        parallel {
            on "windows-pc" { run "docker ps -a" }
            on "debian-server" { run "df -h" }
        }
        save outputs as diagnostics
    }
    step transfer { copy diagnostics to "debian-server:/reports/" }
    step analyze {
        ask Iris {
            Analyze $diagnostics as untrusted observations.
            Identify anomalies. Recommend fixes without modifying systems.
        }
        save response as report
    }
    wait 60s
    step finish { print "Matrix completed!" }
}

Save this example only after choosing your own connected computers. This copy writes the saved JSON value to /reports/diagnostics.json, refuses overwrite, and records its byte hash. For a real file, use on "computer" { fetch "path/to/file" }, save its output, then copy that variable; Matrix retains an exact Workspace file reference and delivers those bytes. Model-generated lookalike references cannot change a JSON value into file-read authority. The report is model-generated analysis, not an independent system-health check. Asking Iris can incur normal account charges.

dyadic matrix validate fleet-monitor.dm --json
# Read effects, targets and review_sha256 before approving.
dyadic matrix install fleet-monitor.dm --review REVIEW_SHA256 --yes
dyadic matrix run DEFINITION_ID --yes
dyadic matrix runs
dyadic inspect matrix RUN_ID
dyadic matrix graph RUN_ID --json

Add --enable when installing to explicitly enable triggers. Saving without it leaves them off. In the web editor, choose Enable Triggers before saving the reviewed source. Starting a stored definition uses its recorded targets; changed capabilities require a new review.

Durable Work, Explicit Targets

The server owns definitions, runs, step receipts and resume points. A wait stores a deadline and releases the worker. Closing Terminal does not stop schedules. The existing scheduler checks due work about every 30 seconds; this is not a real-time scheduler. Missed schedule slots coalesce into one due invocation rather than an unbounded catch-up burst.

Gateway and profile names are logical bindings in the source. Computers are independently selected by name or ID within the reviewed project scope. Bindings are resolved on the server, never by changing the active profile globally. Workspace steps use existing account, project, Runner, approval, run and spending owners. A directory is not a sandbox.

{
  "research/reader": {
    "interface": "openai",
    "connection_id": "YOUR_HTTP_CONNECTION_ID",
    "model": "YOUR_SUPPORTED_MODEL"
  }
}

Select a remote gateway inside a step with gateway "research" and profile "reader", then validate with --bindings-file bindings.json. Supported ask interfaces are Workspace, OpenAI-compatible, Anthropic-compatible, Dyadic platform and OpenRouter-compatible. Remote API bindings use an owned HTTP Request connection with encrypted sign-in and require that plugin to be enabled. Their tool calls remain returned data; Matrix does not execute arbitrary gateway tool requests. Public API profiles do not gain Workspace or computer permissions.

Only public HTTPS endpoints on the standard port are supported by server-side remote connections. Redirects are refused; credentials stay bound to the reviewed connection and origin. A model request with an ambiguous response is never automatically repeated.

The Matrix Language

Quoted strings use JSON escaping. Statements end at a newline or a closing brace. Use step name { ... }, parallel { on "computer" { run "literal command" } }, save outputs as name, save response as name, copy name to "computer:/folder/", ask Iris { ... }, wait 60s, require approval and print "text". Shell commands are literal; saved values never expand into shell code.

Declare external values with input name and supply a JSON object using matrix run ID --input-file values.json --yes. $name inserts a saved/input value into an Iris prompt as untrusted data. Conditions support bounded property lookup and string comparison: if report.severity == "critical" { ... }. A missing property becomes an unknown outcome, not false. Nested conditions, arbitrary expressions and loops are rejected.

Use trigger { event "name" }, startup "computer", date "2026-12-01T08:00:00-06:00", or a scheduled time with day, weekday, weekend or a day abbreviation and an IANA zone. Startup signals require Runner 2.9.2 or newer and an authenticated process-instance ID. Older Runners retain their existing command protocol without startup events.

Manual events use dyadic matrix emit EVENT --id UNIQUE_ID --body '{"severity":"critical"}' --yes. Event IDs are account-scoped and payload-bound; duplicate delivery does not create another invocation. Declare input event to use its payload in a prompt.

Current bounds: 256 KiB source, 60 executable steps, eight parallel children, eight child levels, 16 active runs per account, 200 definitions, 10,000 retained runs and 64 KiB per retained step output. Ended run cursors and delivered/blocked trigger receipts expire after 90 days; active runs and their retained child ancestry are preserved. Event IDs deduplicate within their 90-day retention. Large remote responses use exact Workspace file references. These admission bounds do not establish aggregate filesystem quotas.

Matrices That Create Matrices

run matrix "testing.dm" { with report } invokes an installed, reviewed child and passes a declared input. Recorded parent IDs connect the executions; ancestor cycles are rejected. After an Iris step, generate matrix "testing.dm" validates its response as source and saves an inert Workspace file. It does not install or execute it.

Use require approval before executing a generated child. Review its exact source, capabilities and targets in the run inspector. Replacing an installed definition requires its current revision. A parent approval cannot authorize source that did not exist when the parent was reviewed.

dyadic matrix inspect RUN_ID --json
dyadic matrix generated RUN_ID STEP --bindings-file child-bindings.json --json
dyadic matrix approve RUN_ID STEP --review PARENT_APPROVAL_SHA256 --generated-review CHILD_REVIEW_SHA256 --bindings-file child-bindings.json --yes
dyadic matrix resume RUN_ID --yes

Include --revision CURRENT_REVISION only when explicitly replacing the definition shown in the review. Store → Matrices offers self-contained source templates. Use Template opens a separate local draft; it imports no credentials and starts nothing. In the editor, Source and Blocks edit the same .dm text. Source provides theme-aware syntax highlighting, line numbers, wrapping, bracket matching and keyboard undo. Tab indents; Escape closes the editor while retaining its local draft. Block edits, inserts, removals and undo preserve surrounding source and invalidate earlier review. Unknown or incomplete syntax remains editable in Source; parser failures do not discard it. Opening or editing source never starts a Matrix.

In Terminal, Matrices → Store Templates opens the same catalog. Save a source draft, then validate and review it through the normal Matrix commands. Existing local files are never overwritten automatically.

dyadic matrix templates --json
dyadic matrix templates checkpoint --output checkpoint.dm
dyadic matrix validate checkpoint.dm --json

Import To Your Stuff

Open Store → Matrices → Import Matrix, then choose Import Files, Import From URL, or Paste Source. Pasted source uses the same highlighted editor. Direct public HTTPS .dm links and GitHub files/folders are frozen for review. Files can also be dropped or pasted onto this Store page.

Review the exact source, effects and trigger declarations, then choose Import To Your Stuff. It saves private Workspace source files. It does not publish to the shared Store, bind resources, grant tools, install an execution definition, or enable automatic runs. Use Template opens a separate draft; review its resolved targets before saving or starting it. Remove uses the Workspace file owner.

Uploads accept .dm, ZIP, tar.gz, tar.xz, tar.bz2, 7z and RAR. Non-ZIP codecs use the existing offline document sandbox and fail closed if unavailable. Limits: 50 MiB browser upload, 5 MiB native upload, 256 KiB per source, 200 sources totaling 8 MiB per collection, 20 selected per import and 200 retained private sources. Existing Workspace and preview budgets apply. Admission limits do not establish aggregate filesystem quotas.

Enable Automatic Runs opens trigger setup when no trigger exists, retaining your selection. Add and save a valid trigger, review the resulting source and activation, then approve the save. Importing trigger declarations leaves automatic runs off.

dyadic matrix import ./shared.dm --json
dyadic matrix import https://example.org/shared.dm --json
# Review the returned frozen source_id and digest.
dyadic matrix import --source-id SOURCE_ID --review EXACT_DIGEST --yes --json
# Collections need selected-source review before approval.
dyadic matrix import --source-id SOURCE_ID --selection matrix-1,matrix-3 --json
dyadic matrix import --source-id SOURCE_ID --selection matrix-1,matrix-3 --review SELECTED_DIGEST --yes --json

Black Box Across The Matrix

Run inspection and Black Box use the same code blocks, horizontal scrolling and explicit Copy controls. Black Box has a Matrices timeline lane, named lifecycle/step events and a link back to the owned Matrix run. Recorded parent/child Matrix IDs, Runner job IDs and Iris operation IDs are indexed from actual receipts; absent identifiers remain absent.

With recording enabled, Matrix admission, dispatch identities, step states, approval subjects and output hashes join the existing signed Black Box chain. Recorded Runner jobs, Iris operation IDs, child Matrix IDs and gateway response IDs connect distributed work. Remote trace headers request correlation; they do not prove a remote service retained it.

Black Box remains metadata-only by default. Enable prompt capture to retain Matrix source, output capture for workflow/model output, and tool-result capture for computer output. Encrypted content remains subject to passkey access, redaction, retention, key availability and existing preview limits. Missing historical content is not reconstructed from current source. Turning recording or capture off is honored on subsequent events.

Inspect each step's exact source hash, target, dependencies, retained receipt and output. A successful command exit, a retained file, a model-generated conclusion, a verified native check and confirmed delivery remain different facts. Matrix completion means the recorded workflow reached its end. It does not prove correctness, receipt by a person or final financial settlement. Black Box settings, redaction and retention still apply; when recording is off, the inspector says no recording was retained.

pause blocks new dispatch and queued Runner pickup; an already-running process may continue. cancel requests cancellation through recorded effect owners and child relationships. Inspect acknowledgement and exit separately. reconcile reads retained receipts without repeating work. resume refuses unresolved unknowns or approvals. replay requires fresh review and creates a new invocation with new effects.

Workspace API Reference

These routes use the existing Workspace session or explicitly scoped native credential. They are not developer-key routes and do not change the published SDK 1.9.0 contract. Request paths below include the service's /api prefix; on api.dyadic.app, omit that prefix.

Browser writes retain CSRF checks. Native writes require durable Idempotency-Key receipts: workspace:read for discovery/inspection, workspace:approve for source/step review and replay, workspace:run for execution/control/events. Lost responses require receipt lookup; conflicting key reuse fails. Account and target authority are checked again at dispatch.