Conduit Developer Docs

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
{
  "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. Paste your clipboard into the box below to verify it worked.

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.

At the limit, Conduit enables useful flows that do not fit normal installer packages or browser permission boundaries. For example:

• One-click installers: Install a CLI tool or program through visible local review instead of piping curl to bash.
• Local Credential Bridges: Need to log into a web tool using a local SSH key or API token? Conduit can securely 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 to try it, and automatically delete the footprint when you're done.
• Agentic Workflows: AI assistants can edit files, run tests, and report back, all under a granular permission policy where you retain total veto power.

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.

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.

{
  "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
{
  "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.

{
  "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: "README.md", list: ".", diff: "file", and status: true 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.

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.

{
  "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. Without them, Conduit creates a one-request local review instead of silently executing.
• 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.