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.
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.
- Your code sends
POST /api/v1/computers/{id}/tools/{tool}/callwith an API key. - Maritime checks the key, checks that you own the computer and checks that the tool is read-only. A sleeping computer wakes first.
- Maritime starts the kit on the computer with the tool name and its arguments.
- 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.
- 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
- Create a Windows computer with
maritime computers create --os windows, or from New sandbox in the dashboard. - 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
execinstead. Your tools then use the app that is already open and signed in, so they never need its password. - Install the Maritime CLI, version 2.4.0 or later:
npm i -g maritime-cli. To work from Python instead, runpip install -U maritime(0.12.0 or later), which adds themaritime-toolscommand. - Make a folder with a
tools.py. The example below reads the text of an open Notepad window. Add arequirements.txtnext to it if your tools need packages.
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)}- 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- 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. - 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:
| Argument | What it does |
|---|---|
| read_only | True when the tool changes nothing. Maritime refuses to run a tool without it. |
| name | The tool's name in the URL. Defaults to the function's name. |
| title | A short title for the dashboard. |
| view | Optional. 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:
- Controls. Standard buttons, edit boxes, labels and dialogs such as Save As have exact text you can read and set without the mouse.
- Keys. Menu shortcuts such as Alt+R work no matter where the window is.
- OCR. For text the app draws itself, such as menus and grids.
- Fixed coordinates. Only when nothing else works. They break when a window moves.
| Method | What 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_textorwait_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:
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
ToolErrorand 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.
| Endpoint | What it does |
|---|---|
| GET /api/v1/computers/{id}/tools | The 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}/call | Runs 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 code | Meaning |
|---|---|
| 401 unauthenticated | The API key is missing or invalid. |
| 403 scope_missing | The key does not have the computers scope. |
| 404 computer_not_found | You have no computer with that id, or no tools are deployed on it. |
| 404 tool_not_found | No tool has that name. GET .../tools lists them. |
| 409 tool_not_read_only | The tool is not marked read_only=True. |
| 422 tool_error | The tool raised ToolError, crashed (the tool crashed: <type>), or got arguments that do not match its schema (missing argument 'name'). |
| 422 invalid_request | The body is not JSON, or the arguments are over 16 KiB. |
| 501 runs_not_supported | These tools run only through POST .../call. POST .../runs answers this code. |
| 503 tools_unavailable | The tool server did not answer. It restarts itself, so retry. |
Limits
| Limit | Value |
|---|---|
| Computers | Windows desktops only, on the Growth plan or above, once the plan is paid. |
| Tools | Read-only tools only. |
| Call time | Maritime stops waiting after 300 seconds. |
| Arguments | 16 KiB per call. |
| Concurrency | One tool at a time on each computer. |
| File reads | 8 MiB per read through the files API. |
| Deploy time | About a minute the first time, then about 25 seconds. |
Debug a tool
- Call
inspectto 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
statustool 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.loghas the tool name, outcome and time of each call./data/maritime-tools/install.loghas 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.
Related
- Windows desktops
- Linux desktops, for the screen actions and takeover
- CLI
- REST API