开源AI工作流工具

Deploy the sidecar

The CLI loads .env, validates a redacted configuration, and serves the database-free HTTP/SSE boundary:

tofu-agent doctor
tofu-agent serve                         # loopback-only development default

Remote binds are default-deny. Set a bearer token before exposing the process:

TOFU_AGENT_HOST=0.0.0.0 \
TOFU_AGENT_TOKEN='replace-with-a-secret' \
tofu-agent serve

Or run the release image without cloning the repository:

docker run --rm --name tofu-agent \
  -p 127.0.0.1:15001:15001 \
  -e TOFU_AGENT_TOKEN='replace-with-a-secret' \
  -v tofu-agent-config:/home/tofu/.config/tofu-agent \
  ghcr.io/rangehow/tofu-agent:0.17.0

Open /setup and enter the sidecar token to configure the model. The named volume retains both the encrypted configuration and its key across container replacement. The image contains the installed wheel, agent dependencies, and small setup page only: no source checkout, full Tofu application bundle, application data, SQLAlchemy, or database driver.

Use the remote SDKs

Python, sync or async:

pip install tofu-sdk

from tofu_sdk import AsyncTofu

async with AsyncTofu(
    base_url="https://tofu-agent.internal",
    api_key="sidecar-token",
) as tofu:
    result = await tofu.agents.run(
        messages=[{"role": "user", "content": "Summarize this repository"}],
        config={"tools": ["search", "fetch"]},
    )
    print(result["content"])

TypeScript/JavaScript (Node 18+, browsers, workers, Deno, and Bun):

npm install @rangehow/tofu-sdk

import { Tofu } from '@rangehow/tofu-sdk';

const tofu = new Tofu({
  baseUrl: 'https://tofu-agent.internal',
  apiKey: 'sidecar-token',
});

const result = await tofu.agents.run({
  messages: [{ role: 'user', content: 'Summarize this repository' }],
  config: { tools: ['search', 'fetch'] },
});
console.log(result.content);

Both SDKs generate a stable idempotency key for retried runs. agents.start returns HTTP 202 immediately; agents.stream submits once and resumes the task stream from the last absolute event sequence after a transport drop.

Single-shot runs (harness integration)

Eval harnesses and CI jobs that cannot manage a long-lived sidecar use the single-shot contract: one process, one task, one JSON result.

export TOFU_AGENT_PROVIDER_BASE_URL=https://api.openai.com/v1
export TOFU_AGENT_PROVIDER_API_KEY=sk-...
export TOFU_AGENT_PROVIDER_MODEL=gpt-5.6

tofu-agent run --task-file /tmp/task.txt --cwd /work/repo \
  --timeout-s 7200 --trajectory tofu-native --output result.json

- --task / --task-file: the instruction (file wins). --cwd exposes a project root to the agent tools; run_command and the file tools resolve against it. - --tools: comma-separated tool tags or '*'; the default keeps the storage-free policy, under which project-file and shell tools are already enabled and durable memory/scheduler stay off. - --trajectory: embed a flattened trajectory (sharegpt, openai-finetune, anthropic, tofu-native, atif) in the result. atif is ATIF v1.3 (Agent Trajectory Interchange Format), the shape harbor/terminal-bench trajectory viewers consume. - Exit codes: 0 done, 2 configuration error, 3 timeout, 4 permanent agent error, 5 aborted, 6 retriable upstream error (rate-limit / gateway outage / network after the in-run retry budgets — a harness may rerun the trial). The result JSON carries ok, status, finish_reason, content, usage, n_tool_rounds, and error; the error envelope carries kind and retryable for attribution.

Unattended semantics: write tools (file edits, run_command) execute without human approval because no client is attending; tools in the always-confirm partition (scheduling, durable memory, ...) fail closed instead of blocking.

The default pip install tofu-agent is the slim headless runtime: the LLM loop, tools, network, and MCP — sized for eval containers. Document/media parsing (PDF, Office formats, web extraction) is lazy-imported by the features that need it and lives in pip install tofu-agent[full]; the full workspace installer pulls that extra automatically.

Browser Extension

Install the companion extension once after your first login. It is the bridge that lets the agent work inside your real browser instead of a blank, logged-out fetch, and it unlocks capabilities the server alone cannot provide:

- Browser control: navigate, read, scroll, click, and fill pages in a real tab the agent leases from your browser. - Pages behind login and verification: tasks run in your logged-in session, so pages that block server-side fetchers — sign-in walls, CAPTCHA or anti-bot checks, paywalled or intranet-only pages — remain reachable. - Web debugging evidence: DevTools Bridge, console reads, network capture, and screenshots give the agent direct evidence from the page under test. - Cookie-gated file transfer: a URL that needs your browser cookies streams through the extension into bounded server staging.

The same unpacked build supports Chrome and Edge. Open Settings → Local Control for the canonical install or upgrade action; it detects which supported browser is available and opens that browser's own extensions page when Tofu and the browser run on the same machine.

For a manual local install, enable Developer mode on chrome://extensions in Chrome or edge://extensions in Edge, then load the repository's browser_extension/ directory as an unpacked extension. If the browser runs on a different machine from Tofu, use Settings → Local Control → Download extension ZIP instead; a remote browser cannot read the server's filesystem.