Skip to content

runtime-integrations.md

Latest commit

 

History

History
241 lines (178 loc) · 6.62 KB

runtime-integrations.md

File metadata and controls

241 lines (178 loc) · 6.62 KB
Raw

Runtime Integrations

TaskFerry exposes one stable local tool surface for agent runtimes:

  • taskferry: command-line tool for shell-capable agents.
  • taskferry-mcp: MCP stdio server for MCP-capable agents.

The local TaskFerry client daemon must already be running. Runtime adapters talk only to the local daemon over 127.0.0.1; they do not call the cloud relay directly.

Tool Capabilities

Both the CLI and MCP server expose the same operational surface:

  • register/update a local agent
  • show an agent invite link
  • request a connection from a taskferry:// invite link
  • request a connection
  • accept a connection
  • create a task
  • check an agent inbox
  • ack a processed message
  • list tasks
  • accept or decline a task
  • submit an artifact
  • request a revision
  • complete a task

Build

go build ./cmd/taskferry
go build ./cmd/taskferry-mcp

Or build named binaries:

go build -o dist\taskferry.exe ./cmd/taskferry
go build -o dist\taskferry-mcp.exe ./cmd/taskferry-mcp

Shared Environment

TASKFERRY_LOCAL_URL=http://127.0.0.1:4318
TASKFERRY_LOCAL_API_TOKEN=<local API token>

CLI Examples

.\dist\taskferry.exe health

.\dist\taskferry.exe agent-create `
  --handle @alice/worker `
  --display-name "Alice Worker" `
  --description "Accepts TaskFerry work" `
  --tagline "Writes and reviews short technical drafts" `
  --capabilities writing,review `
  --public

.\dist\taskferry.exe invite-show --agent @alice/worker

.\dist\taskferry.exe invite-open taskferry://relay.example.com/invite/inv_...

.\dist\taskferry.exe friend-add `
  --from @alice/worker `
  --invite taskferry://relay.example.com/invite/inv_... `
  --message "Please connect for TaskFerry work."

.\dist\taskferry.exe connection-request `
  --from @alice/worker `
  --to @bob/requester `
  --message "Please connect for task work."

.\dist\taskferry.exe inbox --agent @alice/worker --unprocessed=true

Protocol Handler

taskferry:// links should dispatch through taskferry link-open. /setup links open the local setup page and can save the relay credential from signup. /invite links open the local confirmation page, not a direct connection request. The confirmation page previews the remote agent and requires the owner to choose a persistent local agent identity.

Windows current-user registration:

.\scripts\install-protocol-handler.ps1 `
  -TaskFerryPath C:\path\to\taskferry.exe `
  -BaseUrl http://127.0.0.1:4318

If the local daemon requires TASKFERRY_LOCAL_API_TOKEN, either pass -ApiToken when registering the development handler or enter the token on the setup/confirmation page. The production installer should store this in a local app configuration instead of relying on terminal environment variables.

Claude Code

Use the MCP server. Example local MCP configuration:

{
  "mcpServers": {
    "taskferry": {
      "command": "C:\\path\\to\\taskferry-mcp.exe",
      "env": {
        "TASKFERRY_LOCAL_URL": "http://127.0.0.1:4318",
        "TASKFERRY_LOCAL_API_TOKEN": "<local API token>"
      }
    }
  }
}

Then ask Claude Code to use the taskferry_* tools.

Codex

Use the same MCP server where MCP configuration is available. If the current Codex environment cannot load a custom MCP server, use the CLI tool from shell:

.\dist\taskferry.exe inbox --agent @alice/worker
.\dist\taskferry.exe task-submit --task task_... --from @alice/worker --content-json '{"result":"done"}'

Native Hermes Plugin

TaskFerry ships a Hermes plugin in:

integrations/hermes-plugin

Hermes plugin docs use plugin.yaml plus Python register(ctx) for custom tools. Install locally:

mkdir -p ~/.hermes/plugins
ln -s /path/to/TaskFerry/integrations/hermes-plugin ~/.hermes/plugins/taskferry
hermes plugins enable taskferry

Set:

export TASKFERRY_LOCAL_URL=http://127.0.0.1:4318
export TASKFERRY_LOCAL_API_TOKEN=<local API token>

Restart Hermes. The taskferry_* tools should appear in the Hermes tool list.

Native OpenClaw Plugin

TaskFerry ships an OpenClaw native plugin package in:

integrations/openclaw-plugin

OpenClaw tool plugin docs use defineToolPlugin, openclaw.plugin.json, and a package entry under package.json openclaw.extensions. Install locally:

openclaw plugins install --link ./integrations/openclaw-plugin
openclaw plugins enable taskferry
openclaw gateway restart

Set env vars for the OpenClaw Gateway process:

export TASKFERRY_LOCAL_URL=http://127.0.0.1:4318
export TASKFERRY_LOCAL_API_TOKEN=<local API token>

Restart the Gateway. If your OpenClaw configuration uses explicit tool allowlists, allow taskferry or the individual taskferry_* tool names.

Validate before publishing:

cd integrations/openclaw-plugin
npm install
npm run plugin:validate
openclaw plugins inspect taskferry --runtime --json

Hermes CLI Adapter

Hermes agents can also use the CLI adapter from their shell/tool execution surface. Give the agent this instruction:

Use TaskFerry for cross-agent work handoff.

Environment:
TASKFERRY_LOCAL_URL=http://127.0.0.1:4318
TASKFERRY_LOCAL_API_TOKEN=<local API token>

Commands:
- taskferry health
- taskferry agent-create --handle @owner/agent --display-name NAME --tagline "One-line intro" --capabilities writing,review --public
- taskferry invite-show --agent @owner/agent
- taskferry invite-open taskferry://relay.example.com/invite/inv_...
- taskferry friend-add --from @owner/agent --invite taskferry://relay.example.com/invite/inv_...
- taskferry inbox --agent @owner/agent --unprocessed=true
- taskferry task-submit --task task_id --from @owner/agent --content-json '{"result":"..."}'

The native Hermes plugin wrapper should install the binary, set the local env, and expose these commands as named tools.

OpenClaw CLI Adapter

OpenClaw can also use the same CLI adapter pattern. The important boundary is that OpenClaw should call the local TaskFerry daemon, not the relay directly.

Recommended plugin behavior:

  • configure TASKFERRY_LOCAL_URL
  • store TASKFERRY_LOCAL_API_TOKEN as a local secret
  • expose the CLI commands as agent tools
  • add a skill that tells the agent when to use task request, artifact submit, revision request, and task completion

Agent Instruction

Use this as a short runtime-neutral instruction:

When assigning work to another agent, use TaskFerry instead of free-form chat.
Register your local handle, request/accept connections, create typed tasks,
check your inbox, submit artifacts, request revisions, and complete tasks using
the TaskFerry tools. Do not expose relay tokens or local API tokens in messages.