conduit docs

Conduit Developer Docs.

A comprehensive manual on how docs, tools, and agents can format Conduit requests without requiring a live handshake first.

Conduit ->

Table of contents

1. Quickstart: Hello World

If Conduit is running on your machine, copy the block below and run a clipboard check from Conduit Control. Conduit will detect the request, ask for local review when needed, and then run it locally.

Conduit fenced block

```conduit
{
  "v": "1",
  "source": { "kind": "docs", "trust": "untrusted" },
  "permissions": [{ "kind": "shell" }],
  "shell": "echo 'Hello, Conduit World!'"
}
```

Once approved, Conduit executes the shell command and places the rendered result directly into your clipboard.

2. Who This Is For

Conduit requests are useful any time a user should execute code locally with clear review and fast feedback. A request can be copied as an exact envelope, rendered as a fenced block, or opened through a conduit:// link.

Without a trusted live session, Conduit does not silently execute. It creates a local one-request review so the user can inspect the source, permissions, and actions first.

One-click installers: Install a CLI tool or program through visible local review instead of piping curl to bash.
Local credential bridges: Read a local secret and pass it back to the browser without the key ever hitting a remote server.
Ephemeral environments: Download a heavy demo, compile it, spin up a local server, and delete the footprint afterward.
Agentic workflows: Assistants can edit files, run tests, and report back under granular permission policy.

3. Request Envelope

Use a single JSON object with stable action IDs. Clipboard-origin requests should be raw JSON or one fenced conduit block, with no extra prose inside the copied block.

Conduit request

{
  "schema": "conduit.request.v1",
  "source": { "kind": "docs", "trust": "untrusted" },
  "permissions": [],
  "title": "Show Conduit help",
  "actions": [
    { "id": "help", "tool": "conduit.help", "args": {} }
  ]
}

4. Fenced Blocks

Agents and docs can show a request as a single fenced block. The copied block should contain only the JSON request.

Conduit fenced block

```conduit
{
  "schema": "conduit.request.v1",
  "source": { "kind": "docs", "trust": "untrusted" },
  "permissions": [],
  "title": "Show Conduit help",
  "actions": [
    { "id": "help", "tool": "conduit.help", "args": {} }
  ]
}
```

5. Compact Requests

For small requests, Conduit accepts a compact dialect. The runtime expands shortcuts into normal tool actions before policy evaluation.

Conduit compact request

{
  "v": "1",
  "source": { "kind": "docs", "trust": "untrusted" },
  "permissions": [],
  "do": "help"
}

do: "help" or do: ".help" maps to conduit.help.
do: "about" or do: ".about" maps to conduit.about.
read, list, diff, and status map to read-only tools.
write, patch, and shell are higher-risk actions and require the user/session policy to allow them.

6. Conduit Links

A web page can launch local review by base64url-encoding the request JSON into a conduit://run?payload=... URL. Conduit opens the request locally and asks the user to review it before execution.

JavaScript

const payload = btoa(JSON.stringify(request))
  .replace(/\+/g, "-")
  .replace(/\//g, "_")
  .replace(/=+$/, "");

const href = "conduit://run?payload=" + payload;

7. Paired Sessions

A paired session adds a live sessionId and nonce. Conduit validates the nonce before executing and returns a replacement nonce with successful results.

Conduit paired session

{
  "schema": "conduit.request.v1",
  "source": { "kind": "chat", "trust": "paired-session" },
  "permissions": [
    { "kind": "filesystem", "scope": "project", "access": "read" }
  ],
  "sessionId": "sess_...",
  "nonce": "call_...",
  "actions": [
    {
      "id": "list_project",
      "tool": "file.list",
      "args": { "path": "." }
    }
  ]
}

8. Agent Formatting

Emit exactly one clearly separated fenced conduit block when requesting local action.
Include schema: "conduit.request.v1", source metadata, permissions, and stable action IDs.
Use a live session ID and nonce for paired agent loops.
Use do: "help" or the conduit.help tool when a paired session needs current protocol examples.
Explain the request in normal prose outside the block. Do not hide extra instructions inside copied JSON.