Work directly on your computer.

FIN gives your agent file, process, and command tools. Use the desktop when a task needs it. Protocol 3 helpers return text directly and stream command output without capturing a screenshot after every command.

Connect once. Choose your tools.

1. Download and open the latest FIN helper on the computer you want to use. Approve its connection in FIN.
2. Open Agent bridge and create a credential. It controls this computer for one hour.
3. Download the agent client to the computer running your agent. It needs Python 3.10 or later and no extra packages.
4. Give your MCP client the command below and supply FIN_AGENT_TOKEN through its private environment or secret settings.

python3 /absolute/path/to/fin-agent-client.py mcp

For MCP clients that accept a JSON configuration:

{
  "mcpServers": {
    "fin": {
      "command": "python3",
      "args": ["/absolute/path/to/fin-agent-client.py", "mcp"]
    }
  }
}

Configure FIN_AGENT_TOKEN separately in the client’s private environment. Do not put a credential in prompts, URLs, command arguments, shared configuration, or source control. This guide does not install or connect your agent automatically.

Let the agent choose the shortest route.

Start with fin_status and fin_system_info. Prefer direct tools for files and processes. Use fin_exec for a known executable, or fin_command for a shell script. Use fin_observe and fin_actions for desktop work that has no direct tool.

• Files: list folders, read text, search literal text, write files, and replace an exact section. Paths must be absolute or start with ~/. File reads and edits are bounded to 64 KB.
• Guarded edits: a complete file read returns sha256. Pass it as expected_sha256 when editing. Use missing to create a new file. A mismatch stops the edit. Coordinate other writers; this is not a filesystem-wide lock.
• Processes: list process names, IDs, and parent IDs.
• Commands: output streams while the process runs. fin_exec takes a program, arguments, and an optional working directory without launching a shell. Each shell command still starts fresh.
• Local batches: run up to 16 direct tool calls in order, stopping on a failure. Calls use names such as files.read and files.patch. No nested batches or commands. Earlier effects are not rolled back.
• Desktop fallback: ordered mouse and keyboard input, plus on-demand screenshots. FIN does not yet provide browser DOM or native accessibility tools.

Command-line examples

Keep the credential in the environment. Each action needs a stable ID of 16–80 letters, digits, underscores, or hyphens. Use a fresh ID for new work and the same ID to recover that work.

python3 fin-agent-client.py status
python3 fin-agent-client.py exec --id inspect-python-20261002 --program python3 --args-json '["--version"]'
python3 fin-agent-client.py run --id check-host-20261002 --command "whoami"
python3 fin-agent-client.py tool --id inspect-files-20261002 --tool-file tool.json
python3 fin-agent-client.py observe --id observe-desktop-20261002 --screenshot screen.jpg
python3 fin-agent-client.py result --id check-host-20261002
python3 fin-agent-client.py cancel --id check-host-20261002

Example tool.json:

{"name":"files.list","path":"~/Documents","limit":50}

Command progress goes to stderr. Final structured results go to stdout. Use --capture screenshot or --screenshot result.jpg when a command needs visual verification. The default auto policy only captures for desktop actions and observations. none disables capture.

HTTP API

Use an Authorization Bearer header. POST /api/automation/status discovers protocol and tools. POST /api/automation/run accepts a stable id, kind (command, tool, actions, observe), and capture (auto, none, screenshot). Supply command, tool, or actions as appropriate.

{
  "id": "read-config-20261002-001",
  "kind": "tool",
  "tool": {"name":"files.read","path":"~/project/config.json"},
  "capture": "none"
}

GET /api/automation/events?id=ACTION_ID streams status and output as server-sent events. Streams rotate after 25 seconds; reconnect using the same ID. Fetch POST /api/automation/result with {"id":"ACTION_ID"} for the final result and any screenshot. Use /cancel to request cancellation. Images are deliberately excluded from progress streams.

Connection and recovery

The updated helper prefers a persistent WebSocket and automatically falls back to HTTPS if it is unavailable. FIN’s current hosting still uses a durable database mailbox between separate server instances, checked on a 150 ms timer plus database time. This release does not promise zero polling or a measured latency target. Command results no longer depend on a desktop viewer being open.

Actions keep their IDs across reconnects. The helper records receipt before acknowledgment and records execution before starting. A crash during execution reports an unknown outcome and does not replay the action. A successful input receipt proves delivery, not application success; inspect output, saved-file hashes, or a relevant screenshot.

Only one action runs per computer. Actions have a two-minute limit, and command output is capped at 96 KB. Closing the viewer pauses its screen stream without revoking the approved connection. Disconnect, credential revocation, and local Quit are explicit controls. Revocation cannot undo completed work and must reach the computer to stop running work.

Updating an existing computer

The website cannot replace a helper that is already running. Download the new helper on the remote computer, close the old helper, open the new one, and pair it. For remembered Windows access, use the tray’s Quit control before replacement; after reconnecting, enable remembered access on the new helper. An older helper continues its existing command and desktop behavior, but direct tools need protocol 3.

Computers must be awake, online, and signed in. Windows remembered access starts after login. macOS needs its screen and accessibility permissions; Linux desktop control needs X11. Traffic is encrypted in transit through FIN’s relay; it is not end-to-end encrypted.