Connect your AI agent

1. Open the latest FIN helper on the computer you want to control.
2. Download the MCP client on the computer running your agent. It needs Python 3.10+.
3. Add the configuration below to your agent’s MCP settings, using the downloaded file’s actual path.
4. Tell your agent to call fin_connect with the 5-letter code shown by the helper, such as RWKTP. It can pass hours (up to 24) to ask for that much access. Approve the matching “AI agent” request on the remote computer and choose how long it lasts.
5. The agent calls fin_connect again without a code. It can now use the computer.

For MCP clients that accept a JSON configuration:

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

No token copy or environment setup is needed for code pairing. After approval, the client saves the connection in ~/.fin, readable only by you, until access ends. Restarting the agent reconnects without a new code, and reconnecting never extends access. A different code replaces the saved connection. The standalone CLI uses the same saved connection, or a credential from a browser session in FIN_AGENT_TOKEN.

Available tools

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 starts fresh. Windows uses PowerShell: enter the script directly, without nesting another powershell -Command. macOS and Linux use /bin/sh.
• 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

Reuse the exact action ID after an interruption; do not submit the same work under a new ID.

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.

Access & helper updates

The person approving on the remote computer chooses how long access lasts: 1, 4, 8, or 24 hours, or a custom time from 15 minutes to 24 hours. The default is 8 hours. The helper, the connecting browser, and every agent credential end at that time. Stop access on the remote computer ends it immediately. A remembered Windows computer stays connected, but agent credentials for it still last at most 24 hours at a time. The updated helper shows the end time and enforces it even if it goes offline. Older helpers still work, with the deadline enforced by the server.

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.