Computers on demand

Build an API for a desktop app

A computer tool is a Python function that drives an app on a Maritime Windows computer. You write the functions in a tools.py file and deploy the folder to the computer. Maritime then serves each function as an HTTPS endpoint that returns JSON. Use it for an app that has no API, such as a practice-management system, an EHR or a desktop accounting app.

Tools run only on Windows desktops, which need the Growth plan or above, once the plan is paid. Maritime runs only tools marked read-only (read_only=True).

How a call runs

Your code calls an HTTPS endpoint. Your function runs on the computer, inside the signed-in Windows session, where it can see and click the app.

  1. Your code sends POST /api/v1/computers/{id}/tools/{tool}/call with an API key.
  2. Maritime checks the key, checks that you own the computer and checks that the tool is read-only. A sleeping computer wakes first.
  3. Maritime starts the kit on the computer with the tool name and its arguments.
  4. The kit hands the call to the tool server. The tool server runs in the desktop session of the signed-in user, so your function sees the same screen a person would.
  5. Your function returns a dict, and Maritime returns it as JSON.

Tools on one computer run one at a time, because they share one screen. Maritime stops waiting for a call after 300 seconds. A scheduled task starts the tool server when the Windows user signs in, and a supervisor restarts it when it stops.

Build a tool

  1. Create a Windows computer with maritime computers create --os windows, or from New sandbox in the dashboard.
  2. Install the app and sign in. Open the computer's page in the dashboard and click Take over to use its screen. For a silent installer, run PowerShell on the computer with exec instead. Your tools then use the app that is already open and signed in, so they never need its password.
  3. Install the Maritime CLI, version 2.4.0 or later: npm i -g maritime-cli. To work from Python instead, run pip install -U maritime (0.12.0 or later), which adds the maritime-tools command.
  4. Make a folder with a tools.py. The example below reads the text of an open Notepad window. Add a requirements.txt next to it if your tools need packages.
my-tools/tools.py
from maritime_tools import ToolError, desktop, tool


@tool(read_only=True, title="Read Notepad")
def read_notepad() -> dict:
	"""The text in the open Notepad window."""
	window = desktop.find_window(process="notepad.exe")
	if window is None:
		raise ToolError("Notepad is not open")
	edit = desktop.find_control(window, class_name="Edit") or desktop.find_control(window, class_name="RichEditD2DPT")
	if edit is None:
		raise ToolError("Notepad has no text box")
	return {"title": window.title, "text": desktop.window_text(edit.hwnd)}
  1. Deploy the folder. The first deploy installs Python on the computer and takes about a minute. Later deploys take about 25 seconds. Deploy again after every change.
maritime computers tools deploy <computer_id> ./my-tools
  1. List the tools with maritime computers tools list <computer_id>. After that, the computer's page in the dashboard has a Tools tab with the same list.
  2. Call a tool.
curl -X POST https://api.maritime.sh/api/v1/computers/<computer_id>/tools/read_notepad/call \
  -H "Authorization: Bearer $MARITIME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"arguments": {}}'

Write tools.py

The kit imports tools.py from the folder you deploy, and the folder is on the import path, so tools.py can import other modules next to it. On each deploy the kit installs the packages in requirements.txt. The @tool decorator registers a function as a tool and takes these arguments:

ArgumentWhat it does
read_onlyTrue when the tool changes nothing. Maritime refuses to run a tool without it.
nameThe tool's name in the URL. Defaults to the function's name.
titleA short title for the dashboard.
viewOptional. A table for the dashboard's Tools tab: {"title", "items", "columns": [{"key", "label"}]}.

Write each function by these rules:

  • The docstring becomes the tool's description. Write it for the person or the model that calls the tool.
  • The parameters become the input schema. Use str, int, float, bool, list[...], dict, or one of these with | None.
  • Return a dict. A list comes back as {"items": [...]}.
  • To refuse, raise ToolError("sentence"). The caller gets HTTP 422 with your sentence.
  • Start every tool from a known screen. Close stray windows and go back to the app's home view first. The last tool may have left the app anywhere.
  • Never write arguments or results to a file or a log. The kit logs only the tool name, the outcome and the time.

Drive the screen

Import desktop from maritime_tools. Boxes are (left, top, right, bottom) in screen pixels. Prefer the methods near the top of this list, because they break least when the app changes:

  1. Controls. Standard buttons, edit boxes, labels and dialogs such as Save As have exact text you can read and set without the mouse.
  2. Keys. Menu shortcuts such as Alt+R work no matter where the window is.
  3. OCR. For text the app draws itself, such as menus and grids.
  4. Fixed coordinates. Only when nothing else works. They break when a window moves.
MethodWhat it does
windows()The visible windows, front to back, each with hwnd, title, class_name, process and rect.
find_window(title, process, class_name)The front window that matches. title is a regular expression. Returns None when no window matches.
wait_window(..., timeout)Like find_window, but waits up to timeout seconds.
focus(window), close(window)Brings a window to the front, or asks it to close as its X button does.
controls(window)The window's controls, each with class_name, text, rect and center.
find_control(window, text, class_name)The first control that matches. text is a regular expression.
set_text(control, text), press_button(control)Fills an edit box or clicks a button through Windows messages.
window_text(hwnd)The text of a window or control.
dialogs(), dialog_text(window)The open standard dialogs, and all the text in one.
press(key, mods), type_text(text), paste(text)Keys: press("s", ("ctrl",)) is Ctrl+S. type_text types any Unicode text.
get_clipboard(), set_clipboard(text)Reads or sets the clipboard text.
click(x, y, count), right_click(x, y), move(x, y), scroll(x, y, notches)The mouse, in screen pixels.
screen_size(), screenshot(box)The screen size, or a picture of the screen or one box of it.
ocr(box), screen_text(box)The text in a box: words with their boxes, or plain lines.
find_text(phrase, box), wait_text(phrase, box, timeout)A phrase on screen, with a center to click. Ignores case and punctuation.
wait_settled(box, timeout)True once a box stops changing. Use it instead of a fixed sleep.

These habits keep a tool working:

  • Confirm the screen before you click. Check that the menu is open or that the window has the title you expect. A click that misses can land on something else.
  • Keep each OCR search to the box you mean. Text elsewhere on the screen, such as a side panel, can match the same words.
  • OCR misreads a letter now and then. Match menu text loosely, then confirm the result through a control's exact text, such as the title of the window that opened.
  • Some apps open their own dialogs behind their main window. Check every window of the app's process, not only the front one.
  • Wait for the screen with wait_window, wait_text or wait_settled, not with a fixed sleep.

Find what to click

Every Windows computer with tools has a built-in read-only tool, inspect. It returns the windows, the controls of one window and its OCR text with boxes. Pass title to pick a window, and ocr: false to skip the slower text read.

curl -X POST https://api.maritime.sh/api/v1/computers/<computer_id>/tools/inspect/call \
  -H "Authorization: Bearer $MARITIME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"arguments": {"title": "Notepad"}}'

Build in a loop. Call inspect, write or change one tool, deploy, call the tool, and compare its result with the screen. Keep the computer's page open in the dashboard to watch the screen while a tool runs.

Return files

To return a report or a spreadsheet, save it under C:\data and return its path. Read it with GET /api/v1/computers/{id}/files?path=/data/..., which reads up to 8 MiB. Zip a bigger file with Python's zipfile before you return it. Many apps save through a standard Save As dialog, which you can fill through its controls:

tools.py
import os
import time

from maritime_tools import ToolError, desktop, tool

EXPORT_DIR = r"C:\data\exports"
SAVE_AS_WAIT_S = 20
FILE_WAIT_S = 120
POLL_S = 2


def wait_for_file(path: str) -> bool:
	"""True once the file exists and its size stops changing."""
	deadline = time.monotonic() + FILE_WAIT_S
	last = -1
	while time.monotonic() < deadline:
		size = os.path.getsize(path) if os.path.exists(path) else -1
		if size > 0 and size == last:
			return True
		last = size
		time.sleep(POLL_S)
	return False


@tool(read_only=True, title="Export the open report")
def export_report(file_name: str) -> dict:
	"""Saves the report open in the app as an Excel file and returns its path."""
	window = desktop.find_window(title="Acme PM")
	button = desktop.find_control(window, text=r"^Excel\.\.\.$") if window else None
	if button is None:
		raise ToolError("no report is open")
	desktop.click(*button.center)
	dialog = desktop.wait_window(title="^Save As$", class_name="#32770", timeout=SAVE_AS_WAIT_S)
	if dialog is None:
		raise ToolError("the app did not open Save As")
	os.makedirs(EXPORT_DIR, exist_ok=True)
	path = os.path.join(EXPORT_DIR, os.path.basename(file_name))
	desktop.set_text(desktop.find_control(dialog, class_name="Edit"), path)
	desktop.press_button(desktop.find_control(dialog, text=r"^&?Save$", class_name="Button"))
	if not wait_for_file(path):
		raise ToolError("the app did not finish the file")
	return {"api_path": "/data/exports/" + os.path.basename(path), "bytes": os.path.getsize(path)}

Keep tools read-only

Maritime refuses to run a tool without read_only=True and answers 409 tool_not_read_only. The flag is your promise. Maritime does not check what the function does. In an app that holds real records, follow these rules:

  • Never press a button that saves, submits, posts or deletes in the app.
  • Close a dialog only with a button you expect, such as OK on a notice. If a dialog asks a question, stop with ToolError and leave it open.
  • Type only into fields that change what the screen shows, such as a report's date range.

API reference

Both endpoints take Authorization: Bearer mk_..., an API key with the computers scope. The CLI commands maritime computers tools list and call use the same endpoints.

EndpointWhat it does
GET /api/v1/computers/{id}/toolsThe computer's tools with their input schemas, and the tool server's status. The state is ready, paused (the computer is asleep, and a call wakes it) or unreachable.
POST /api/v1/computers/{id}/tools/{tool}/callRuns one read-only tool now. The body is {"arguments": {...}}, up to 16 KiB of arguments. Returns the tool's dict as result.
{
  "object": "tools",
  "computer_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": {"state": "ready", "detail": "", "checked_at": "2026-11-17T09:30:00Z"},
  "data": [
    {
      "name": "read_notepad",
      "title": "Read Notepad",
      "description": "The text in the open Notepad window.",
      "input_schema": {"type": "object", "properties": {}, "additionalProperties": false},
      "read_only": true,
      "view": null
    }
  ]
}

Errors

Errors come back as {"error": {"code", "message"}}.

Status and codeMeaning
401 unauthenticatedThe API key is missing or invalid.
403 scope_missingThe key does not have the computers scope.
404 computer_not_foundYou have no computer with that id, or no tools are deployed on it.
404 tool_not_foundNo tool has that name. GET .../tools lists them.
409 tool_not_read_onlyThe tool is not marked read_only=True.
422 tool_errorThe tool raised ToolError, crashed (the tool crashed: <type>), or got arguments that do not match its schema (missing argument 'name').
422 invalid_requestThe body is not JSON, or the arguments are over 16 KiB.
501 runs_not_supportedThese tools run only through POST .../call. POST .../runs answers this code.
503 tools_unavailableThe tool server did not answer. It restarts itself, so retry.

Limits

LimitValue
ComputersWindows desktops only, on the Growth plan or above, once the plan is paid.
ToolsRead-only tools only.
Call timeMaritime stops waiting after 300 seconds.
Arguments16 KiB per call.
ConcurrencyOne tool at a time on each computer.
File reads8 MiB per read through the files API.
Deploy timeAbout a minute the first time, then about 25 seconds.

Debug a tool

  • Call inspect to see the windows and text your tool sees.
  • Watch the screen on the computer's page in the dashboard while you call the tool.
  • Call the built-in status tool to check that the tool server answers. It returns the state and the kit version.
  • Read the logs with the files API. /data/maritime-tools/server.log has the tool name, outcome and time of each call. /data/maritime-tools/install.log has each deploy.

Build with a coding agent

maritime computers tools guide prints the kit's guide. The guide is also a Claude Code skill, so a coding agent can write, deploy and test tools for you. Give it a computer id and the app's name, and sign in to the app yourself first.