Repos, chains, harnesses and the server

This page lists the board's routes for connecting, changing and disconnecting a repo, chains and the library, harnesses, changes saved but not applied, the update check and editors. Like the other board routes they can change in any release: see Filing, reading and changing work items for the rule, and the stable routes for the two that keep their shape. Prefer the kraft command with --json.

Connecting a repo

GET /api/repos

Answers the connected repos and workspaces, and the checkout the server was started in when it is not connected yet.

POST /api/repos/probe

Reads a repository and changes nothing. The proposal answer says what it returns.

With test_command the answer is the proposal that connecting with that command would save. The probe runs in a process of its own with a two-minute limit, so a repository's files cannot stall the server. How connect proposes commands says how a proposal is made, what limits the probe, and what connect does when the probe fails. The 429 below is only on this page.

POST /api/repos

Connects a repository: it probes it, saves the entry to repos.yaml, and indexes the repo for search. It answers 201 with the saved entry and the proposal answer.

A test_command or setup_command in the body replaces the proposal. If the body gives both, the route connects a repo the probe fails on, with those commands, and says why in probe_failed.

PATCH /api/repos?path=

Changes fields of the connected repo at path, the absolute path of its entry in repos.yaml. The Settings screen calls it. A field the body leaves out keeps its saved value, and one sent as null is cleared. Any save sets managed: true on the entry.

The answer is the whole saved entry, defaults included.

DELETE /api/repos?path=

Disconnects the repo at path: it removes the entry from repos.yaml and from the search index. No file of the repository is touched and no work item is dropped. kraft repo disconnect calls it. It answers 204 with no body.

The proposal answer

POST /api/repos/probe and POST /api/repos answer the proposal beside the repo's facts: test_command, test_scopes, setup_command, and the evidence below. None of the evidence is stored in repos.yaml.

Chain templates

These routes read the chains the Templates editor shows. Each answers 503 when the library or a chain does not load, with template library invalid, refusing work: and the file that broke it.

GET /api/templates/chains

Answers every chain, by id.

Answers 503 as under Chain templates.

GET /api/templates/chains/{id}/resolved

Answers one chain with its extends expanded.

It answers 404 for an unknown chain and 422 for one that does not resolve. Also 503 as under Chain templates.

GET /api/templates/library

Answers {file, text, components}: the path of library.yaml, its text, and every component in it, section by section. See The library component. Also 503 as under Chain templates.

GET /api/templates/library/{ref}

Answers one component, shaped as in the library component, by its id or a bare name no other section shares. It answers 404 when nothing matches, and 409 naming each id when two sections share the bare name. Also 503 as under Chain templates.

GET /api/templates/steering/preview

Answers what the agent task at canonical path task of chain chain reads at launch in the repository whose name or path is repo, section by section in launch order. Nothing launches. The answer is {sections: [{kind, source, text}]}.

A missing parameter answers 422.

kind is one of:

There is one steering section per steering profile: the repository's first, then the task's. Joined, the texts are the launch's context. Per-launch values are placeholders (<work item id>, <session id>, <title>, <task instruction>).

The library component

GET /api/templates/library and GET /api/templates/library/{ref} return components with these fields:

In used_by_paths, path is that component's canonical path, overrides is whether it sets any key besides id, extends and kind, and via is the library node it reaches the chain through, when it sits in that node's own definition. For example, {chain: "default", path: "verification.review.code_review", overrides: false, via: "verification"}.

An add-on's chains and components

A write that would save an add-on's chain or component answers 409, with <id> comes from add-on <addon id>; extend it or copy it to your library. That holds for PUT /api/templates/chains/{id}, for every write to a chains draft of that id, and for a draft op that addresses the component. copy_component and new_chain copy one.

Filing an item on a chain whose add-on store is still being restored answers 503 with add-on <id> is being restored; retry.

Harnesses

The web UI edits harnesses through a draft (/api/drafts/harnesses/...). These routes read the published state.

GET /api/harnesses/profiles

Answers {profiles, agent_profiles, file, error}.

• file is the path of harnesses.yaml, and error is why it does not load, else null.
• Each entry of profiles is a harness profile: {id, provider, enabled, executable, defaults, used_by, chains}.
• Each entry of agent_profiles has id, addon, used_by, chains, effort, model (provider to model id), providers (provider to {model, effort}), fallback, problems and problem_details.
• addon is {id, version} for an agent profile an add-on ships, whose id is qualified (release:careful), and null for one of your own.
• effort is the one effort every provider shares, or null when they differ: read providers then.
• problems is the entry's list of messages, and problem_details the same list as {chain, task, profile, provider, field, message}, where field is model, effort, or null for a profile that is not defined.
• Each fallback entry has its own problems and problem_details.

GET /api/harnesses

Answers one entry per provider: {id, label, executable, executable_found, efforts, models, capabilities}. executable_found is whether the command is on PATH now. There is no version.

GET /api/harnesses/providers

Answers {valid, invalid}: each provider's capability surface by id, and the providers whose files did not load, with why. A provider also lists efforts and models: the plain-word values it limits that option to, [] when it takes any string or a pattern.

Saved but not applied

A restart or a reload applies what you saved. The apply_changed live message says when this list changes.

GET /api/apply

Answers what is saved and not running yet: {restart: [{id, file, text}], reload: [{id, file, text, problem?}], managed}. Both lists are empty when nothing is pending. managed is true when a service manager started this server, the only case POST /api/apply/restart can restart it.

• A restart item is access.bind or access.port: access.yaml names an address the server is not bound to. It is left out when KRAFT_HOST or KRAFT_PORT is set, since the environment wins and a restart would change nothing.
• A reload item is disk:<file> for library.yaml, chains/*.yaml, policy.yaml, intake.yaml, addons.yaml or addons.lock whose bytes differ from the ones last loaded. A file rewritten with the same bytes is no change. problem is the first problem found in the file as it is on disk.

POST /api/apply/reload

Rereads the library, policy.yaml and intake.yaml (and replaces the intake poller), and answers the new GET /api/apply. A policy or an intake.yaml that does not load is refused and stays pending, with its problem, and the running one is kept.

POST /api/templates/reload

Does the same as POST /api/apply/reload, and answers {valid, invalid_templates, refused_policy, refused_intake}: the valid chain ids, the chains that do not load, and the last two each the refusal's reason or null. kraft admin reload prints them and exits 1 on either refusal.

The body is optional. {"only": ["addons.yaml", "addons.lock"]} rebuilds the library from the add-on files alone and leaves a pending edit of policy.yaml or intake.yaml pending. only takes those two names and no other. It is what a kraft admin addon verb sends.

POST /api/apply/restart

Restarts the server when a service manager started it (the launchd or systemd unit kraft admin install-service writes). It answers 202 with {"restarting": true} and runs kraft admin restart detached. Nothing restarts the server unless this is called.

The restart ends the agent of every active item, and each stops as failed until it is retried, as kraft admin restart warns: see A restart ends running agents. The web UI counts the active items from GET /api/work-items (the rows whose status is active) and shows the number in its confirmation.

Update check

GET /api/update

Answers {installed, latest, channel, python, behind, checked_at} from the daily cached check. python is the interpreter the server runs on, as 3.14. ?channel= is one of stable, rc, beta and alpha (400 otherwise) and defaults to the installed version's own. It is not stored.

When the feed cannot be reached, latest and behind are null: unknown, not "up to date". checked_at is the time of the last check that succeeded on that channel (null when there has been none), so it can be old while latest is null. Installing the update is kraft admin update; the server never does it.

POST /api/update/check

Skips the cache, asks the release feed now, and answers the same shape as GET /api/update. It takes the same ?channel=.

Editors

The routes that open a file in an editor start a process on the machine that hosts the server. They are loopback only: any other caller gets 403.

GET /api/editors

Answers {available, system, default}.

• available lists the editors (code, cursor, zed, obsidian) whose executable this server's machine has on its PATH, or, on macOS, whose app is installed in /Applications or ~/Applications (it is then opened with open -a).
• system says whether the system opener (open, xdg-open) is there.
• default is editor from theme.yaml, else KRAFT_EDITOR, else null.

POST /api/documents/{id}/open

Opens an indexed document, by its absolute path, in an editor.

The answer is {document_id, path, editor}.

POST /api/work-items/{id}/artifact/open

Opens the pending gate's document in the item's worktree. GET /api/work-items/{id}/artifact carries its absolute_path. The answer is {work_item_id, path, editor}.

POST /api/work-items/{id}/artifacts/{kind}/open

Opens a task's document of that kind in the item's worktree. The answer is {work_item_id, path, editor}.

POST /api/work-items/{id}/open-worktree

Opens the item's worktree directory. The answer is {path, editor}.

This route checks the item and its worktree before it checks the caller.

Storage

GET /api/storage

Answers the last measurement of the run folder, joined to the work items. It measures first when there is none yet, and when ?refresh=1 is given; one walk runs at a time, and a request made during a walk waits for it. A walk can take many seconds on a large instance.

{"measured_at": "...", "state": "held", "used_bytes": 12989000000,
 "quota_bytes": 8589934592, "limit_bytes": 10737418240, "reclaimable_bytes": 9600000000,
 "categories": {"worktrees": 0, "sandboxes": 0, "logs": 0, "results": 0,
                "databases": 0, "attachments": 0, "other": 0},
 "items": [{"id": "...", "title": "...", "status": "completed", "archived": false,
            "bytes": 1200000000, "updated_at": "...", "reclaimable": true}],
 "orphans": [{"name": "...", "bytes": 0}]}

POST /api/storage/preview

Says what archiving the items in ids (1 to 200) would do, and changes nothing. An id given twice counts once.

{"freed_bytes": 2400000000, "used_after_bytes": 10589000000, "state_after": "over_quota",
 "items": [{"id": "...", "title": "...", "bytes": 1200000000, "archivable": true,
            "refusal": null, "uncommitted_files": 3, "unpushed_commits": 0, "branch_kept": false}]}

freed_bytes assumes each worktree goes: an archive whose detached-HEAD rescue fails keeps it and frees nothing. Archiving is POST /api/work-items/bulk with archive.

Related

• Drafts: the routes the Templates and Settings editors use to change what the read routes here answer.
• repos.yaml: the fields of the repo entry that connecting and changing a repo write.
• Repo verbs: the kraft repo commands that call the repo routes.
• Filing, reading and changing work items and Gates, run control, ending and retry: the routes for a work item, whose editors routes are here.