runtype-sdk-marathon

Runtype SDK and Marathon

Use this skill for code-first Runtype workflows, the CLI, and Marathon. Use runtype-build-product when the user designs hosted product resources through MCP.

SDK guidance

Fetch live docs when available:

• get_platform_documentation(topic="sdk-reference")
• get_platform_documentation(topic="types-flow-steps")
• get_platform_documentation(topic="types-entities")
• get_platform_documentation(topic="flow-step-types")

Code-first modes:

• Stored: create persistent agents or flows in Runtype.
• Upsert: running the code creates the flow if it does not exist and updates it when its steps change. It keeps a version of each change by default (createVersionOnChange: false turns that off). If the flow was last edited in the dashboard or through the API, upsert fails unless you set allowOverwriteExternalChanges: true.
• Ensure (config-as-code): converge a definition from your repo onto Runtype at deploy time without running it. Ensure never deletes a resource, and agents, flows, and skills keep a version of each change. The SDK has ensure for flows, agents, tools, skills, evals, products, surfaces, and client tokens; evals.ensure replaces the suite's cases. The CLI has runtype agents ensure <file> for a JSON agent definition; add --expect-no-changes to fail a CI job on drift.
• Virtual: the definition is supplied per execution without creating a saved agent or flow. Execution logs, traces, and retention policies still apply, so this is not a zero-retention mode.

Use ensure for CI/CD deploys and upsert for save-and-run scripts. Prefer stored, upsert, or ensure for production workflows, because dashboard inspection, logs, evals, and versioning are easier. Use virtual for tests, one-offs, or temporary generated flows. For privacy-sensitive workloads, verify retention separately.

Use local tools when a tool must run in the user's browser or server: pass a map of tool names to async functions to runWithLocalTools. Use hidden parameters when auth context, tenant IDs, or sensitive request data must not appear in the tool schema the model sees: list them in the tool's hiddenParameterNames, and the runtime fills them from execution variables. Names that start with _internal are never filled; use {{secret:NAME}} references for credentials. The sdk-reference topic has the signatures.

CLI setup

Install or run directly:

npm install -g @runtypelabs/cli
npx @runtypelabs/cli@latest <command>

Check auth before you change it:

runtype auth status

runtype auth status checks only the stored login or signup state. Then pick the first case that applies:

1. RUNTYPE_API_KEY is set: run runtype auth whoami --no-tty and reuse that account. This is also how CLI commands authenticate in CI.
2. A stored account is authenticated: reuse it.
3. A signup is pending: run the next command that auth status prints.
4. auth status reports unauthenticated with a requestedOrgId: the project is linked (.runtype/project.json) to an organization with no stored login. Do not register; have the user privately run runtype auth login --api-key <key> for that organization.
5. The user needs a new account: run runtype auth register --email <email>, then runtype auth verify <code>.
6. The user wants the browser login flow of runtype auth login: the user runs it in their own interactive terminal, not in an automated agent's shell.

For existing-account or installation recovery, follow https://runtype.ai/.well-known/agent.md. Never ask for API keys in chat. Have the user configure credentials privately.

Common commands include runtype agents list, runtype agents ensure, runtype dispatch, runtype flows create, runtype records create, runtype schedules, runtype models, runtype batch, runtype eval, runtype persona, runtype products init, and runtype validate-product. For flags not listed here, run runtype --help or runtype <command> --help.

Marathon

Marathon is a CLI command that runs long research, code-editing, and build tasks across multiple sessions. It streams progress, carries context from one session to the next, supports playbooks, and can use sandboxes. runtype marathon is an alias for runtype agents task. The get_platform_documentation topics do not cover Marathon, so use runtype marathon --help as the flag reference. User docs: https://docs.runtype.com/user-guide/agents/marathon-long-running-tasks.

The first argument is an agent ID or name. If no agent matches, the CLI creates an agent with that name in the user's account.

runtype marathon researcher \
  --goal "Research recent AI announcements and summarize them" \
  --tools firecrawl \
  --max-sessions 5 \
  --max-cost 2

runtype marathon "Code Editor" \
  --goal "Refactor the auth module and run tests" \
  --max-cost 10

runtype marathon calculator \
  --goal "Build a calculator in 3D and deploy it publicly" \
  --sandbox daytona

Guardrails:

• Cost and length: --max-sessions defaults to 50 and there is no default budget. For unattended runs, always set --max-cost <usd> and an explicit --max-sessions <n>.
• Local files: local file tools such as read_file, write_file, and list_directory are on and can read and write anywhere under the current working directory. The --no-local-tools flag does not currently turn them off, so start research-only runs from an empty directory, and never from an untrusted one.
• Unattended runs: without a TTY, or with --json, the interactive startup screen is off. --json prints the final result as JSON. Checkpoint pauses auto-continue after --checkpoint-timeout seconds (default 10). The --no-checkpoint flag does not currently remove the pauses.

Built-in tools you can enable with --tools include exa, firecrawl, dalle, openai_web_search, anthropic_web_search, and google_search. The CLI validates tool IDs and model compatibility at startup.

--sandbox accepts daytona, runtype-sandbox, cloudflare-worker, or quickjs. Only daytona and runtype-sandbox can deploy to a public preview URL.

Models: --model sets the model for the run, --planning-model and --execution-model set it per phase, and --fallback-model is used when the primary model fails. Use routed model IDs such as claude-sonnet-5 or claude-haiku-4-5. For --max-tokens and --temperature, a playbook milestone value beats the CLI flag, and the CLI flag beats the playbook-level default.

To watch a run in the dashboard, add --track. Marathon syncs progress to a Runtype record named after the task.

Resume or restart a run

Marathon saves local state per task, by default under ~/.runtype/projects/<hash>/marathons/ (change it with --state-dir).

• --resume "<new instruction>" continues from saved state, for example after the run hits its session or cost cap. The message is optional.
• --session <name> resumes a specific session.
• --fresh starts a new run and ignores saved state.
• --name <name> keeps separate tasks for the same agent apart. It defaults to the agent name.

For long runs that hit context limits, adjust --compact-threshold, --tool-context observation-mask, or --offload-threshold. See runtype marathon --help.

Playbooks

Use a playbook for repeatable multi-phase work such as research, build, verify, and polish. Load one with --playbook:

runtype marathon researcher \
  --goal "Research the topic, then build a demo" \
  --playbook research-build \
  --max-cost 5

--playbook NAME accepts a file path, or a name that resolves to .runtype/marathons/playbooks/NAME.{yaml,yml,json,ts,mts}. The CLI checks the current directory first, then the home directory. The CLI ships no built-in playbooks, so research-build above is a file the user writes.

A playbook has a name and a list of milestones. Each milestone has a name, instructions, and optional model, fallbackModels, completionCriteria, maxTokens, and temperature. Top-level fields include description, rules, verification, policy, fallbackOnEmpty, maxTokens, temperature, and plugins. Keep rules explicit about file scope, verification, and deployment expectations.

A TypeScript playbook default-exports a config, or a factory that receives { registerWorkflowHook }. Wrap it in definePlaybook from @runtypelabs/sdk for types:

import { definePlaybook } from '@runtypelabs/sdk'

export default definePlaybook({
  name: 'build-only',
  milestones: [
    {
      name: 'build',
      instructions: 'Build the feature described in the goal, then run the tests.',
      canAcceptCompletion: true,
    },
  ],
})

TypeScript playbooks and plugins modules run as code with the user's privileges when the playbook loads. Load only playbooks and plugins the user trusts.

If the runtype skill is also installed, its references cover working modes in more depth. Prefer live MCP documentation over local reference files.