PtcRunner

A runtime for Code Mode agents

Build AI agents that are bounded in what they can do, easy to change, observable in operation, and designed to improve from evidence.

Today, agents usually choose between two extremes. They either call tools one at a time, paying a model round trip and adding context for every step, or use a full coding environment and an external sandbox for more complex work. PtcRunner provides the missing middle: it lets a model write a small, bounded program that calls several approved tools, processes their results, and returns only what matters.

You normally do not write that program. You provide the task, model, approved tools, data, limits, and agent components. The model writes the mission program; PtcRunner executes it and records what happened.

Authority only narrows. A full-width box labelled OPERATOR, ptc-host.json, holding credentials, endpoints, and outer ceilings. An arrow down to a narrower box labelled AUTHOR, ptc.json, holding aliases, missions, and limits, captioned 'selects from, never adds to'. A second arrow, captioned 'splits, never merges', leads to two separated boxes: WORKFLOW, trusted policy, holds the model; and MISSION, the model-written program, holds the tools.
Every layer selects from the one above it and can only narrow. The operator installs authority, the author selects from it, and the model-written program runs inside what is left.

Inside those two environments, the agent loop itself is ordinary PTC-Lisp (a small, bounded subset of Clojure — see the language specification). It is a library you select, not behaviour baked into the runtime, so you can replace it with a domain-specific loop of your own — and doing so grants no new authority.

The loop is a library, not the runtime. A workflow prelude, compiled from selected components, contains a stack of agent.main, agent.core, agent.prompt, agent.retry and llm, outlined and tagged 'replaceable'. In the centre a four-step ring driven by agent.core: prompt, model writes PTC-Lisp, evaluate, observation. On the right a separate mission prelude holding the generated program, your domain components, and prompt-visible exports. A bar across the bottom reads: every tool: requirement is checked against the assembled providers — never granted by them.
A prelude is the immutable compiled aggregate of the components selected for one environment, frozen for the run. A local component cannot shadow a shipped library ID, and selecting a library installs its dependency closure without granting any tool authority.

Install

On macOS it is a one-command install, or a container image if you would rather have one. Installing directly needs neither a container nor any separate runtime — the executable carries its own. Once it is on your machine:

ptc init hello-ptc
ptc run hello-ptc/ptc-project.json
{"greeting":"hello world"}

That runs without contacting a model, and writes a structured trace you can open in the viewer. The same ptc run drives agentic projects.

0.x, under active development. Breaking changes are expected, and the install routes above land with the next release. The availability table tracks exactly where each one stands today.

JSON Schemas

Schema reference → The stable URLs for the project, application, host, and command-envelope schemas. Point your editor at one to get completion and validation while authoring.

Links