Documentation

Guides in reading order, the installation routes, and the reference pages. Start at the top if PtcRunner is new to you.

Start

• Quickstart Install ptc, run a project that needs no API key, then run one where the model writes the program.
• Understand a generated project Understand the files, result, and trace created by ptc init without writing an agent loop.
• PtcRunner concepts Use this page as a quick lookup for the names that appear in PtcRunner files, commands, and results. You can run the Quickstart without reading it first.
• Drive ptc as an agent Use the executable's help and embedded documentation when a coding agent drives ptc. They work offline and describe the version you invoke.

Language

• Read and write PTC-Lisp Read what a model wrote in a trace, or try the language by hand before building anything.

Configure

• Keep a runnable project together Use ptc-project.json as one stable command target for local runs, traces, results, and the Viewer.
• Configure an application Use ptc.json to declare code, input, selected providers, missions, and limits.
• Install models and tools The ptc-host.json installs credentials, model routes, MCP tools, and limits. An application selects and narrows aliases without changing host configuration.

Build

• Use a model Select, verify, and observe a model without working on PtcRunner's provider implementation.
• Connect an MCP tool Connect one MCP server while exposing only the tools a mission needs.
• Serve a workflow over MCP You end with a local MCP server that exposes one workflow as a tool, and a client call that returns its result.
• Customize an agent Configure the shipped agent loop or replace its prompt, policy, mission composition, or complete implementation.
• Inspect and customize components Change the shipped agent prompt on a run without editing the manifest. Installing that prompt as application code is a separate graph change.

Design

• Design an agent workflow Build a small support-inbox agent in three runnable steps: grant the data, move the rules into code, then split the work between two specialists.
• Choose a workflow shape Choose how to split a task between missions, agent loops, and trusted workflow code. The shapes compose — a real design usually combines two or three.

Run and debug

• Run and inspect a project Run, validate, and inspect a PtcRunner project through the ptc executable.
• Explore a project interactively Inspect a workflow, mission, or immutable run capture from an interactive or unattended REPL session.
• Inspect source and generated programs The model's narration states intent; the admitted PTC-Lisp program is the executable decision you can inspect.
• Let an agent improve its own workflow A debugging workflow repairs its own navigation helper, then uses the repaired helper to diagnose and fix an application.
• Evaluate changes with replay Compare a prompt or prelude change against fixed model responses before you decide whether to keep it.

Installation

• Standalone installation Install the self-contained ptc executable from GitHub Releases.
• Docker installation Install the self-contained Linux AMD64 or ARM64 image and run the PtcRunner CLI, Viewer, and stdio launcher without a build toolchain.
• Source installation Build PtcRunner from a repository checkout when changing the runtime, validating an unreleased revision, or producing a standalone artifact.

Reference

• PTC-Lisp Language Specification PTC-Lisp is a bounded Clojure-like language for data processing and tool calling through explicitly granted capabilities.
• Agent library reference This reference defines the shipped agent.core and agent.main PTC-Lisp interfaces. For a guided workflow, see Building agents.
• Clojure Conformance Gaps Tracked differences between PTC-Lisp and Clojure semantics, discovered via conformance testing against SCI, Babashka, Joker, and manual investigation.
• Java Interop Reference for PTC-Lisp PTC-Lisp emulates a subset of Java interop for LLM compatibility. These are not real JVM calls — they are BEAM-native implementations that mirror the Java API …
• Kernel limits reference Ordinary limits are positive enforced ceilings. Optional limits are disabled when omitted by the host. Two documents decide an enabled number: the host documen…
• Shipped prelude reference PtcRunner ships 18 reusable PTC-Lisp components with 62 public exports. A component is one named source module with one namespace. A prelude is the immutable c…
• Signature reference Use signatures to describe component and model-visible tool inputs and outputs, then validate both sides of each call.
• Application-manifest reference This is the complete contract for ptc.json.
• Host-configuration reference This is the complete contract for installed providers, credentials, transports, data classes, and outer limits.
• Project-configuration reference This is the complete local path, artifact, override, and Viewer-preference contract.
• Examples reference This is the complete inventory of shipped example trees, the layout every tree follows, and the aspect each one demonstrates.
• Components-and-preludes reference This is the complete component, dependency, visibility, and shipped-library contract.
• MCP reference This is the complete MCP installation, mapping, effect, authentication, and lifecycle contract.
• Command-line reference This is the complete ptc command and process contract.
• Gateway configuration The loopback gateway exposes health checks and an authenticated MCP tool server.
• Viewer reference The Viewer presents captured and live runs for one PtcRunner project. It is a local inspection surface, not a general remote administration service.
• REPL reference This is the complete interactive, unattended, analysis-profile, and private-session contract.
• Source-inspection reference This page says where each kind of source can be retrieved, and which surface owns the details.
• Debug-navigation reference This is the complete frozen-evidence graph and debug.nav contract.