Build
For programs
Any program, in any language, can use every Hop command. For one call, run hop call. For many, or to watch events, keep hop api running and talk to it in JSON lines.
One call: hop call
hop call <command> '<json>' runs one command with its arguments as a JSON object, and prints the result as JSON. The arguments can come on stdin instead. On an error it prints {"error": {…}} and exits with 1.
$ hop call machine.status '{"machine":"tower"}' { "machines": [ { "battery": null, "cores": 16, "helper": true, "load": 0.12, "machine": "tower", "system": "Linux", "up": true, "uptime": "1:16", "windows": true } ] } $ hop call port.list '{"machine":"nowhere"}' {"error":{"code":"not_found","message":"unknown machine \"nowhere\" (not in hop's config or ~/.ssh/config)"}}
That is all a shell script needs. With jq:
$ hop call window.list '{"machine":"tower"}' | jq -r '.windows[].app' Desktop Azahar AppImage
hop call refuses commands that stream (event.watch); use hop events --json or hop api for those.
Many calls: hop api
hop api reads requests on stdin, one JSON object a line, and writes answers on stdout, one a line. It runs until stdin closes. Because it is plain stdio, it works the same over SSH: ssh -T tower hop api gives a program on any computer the commands of tower's Hop. (The machine needs hop on the PATH of a non-interactive login, or give its full path.)
The hello
The first line hop api writes says what it is, which version of the protocol it speaks, and how many commands it has:
{"commands":42,"hop":"api","version":1}
Requests and answers
A request has an id of your choosing, the command's name in call, and its arguments in args. Its answer has the same id and either ok (the result, always an object) or error.
{"id": 1, "call": "machine.status", "args": {"machine": "tower"}}
{"id": 3, "call": "nope.nope"}
{"id": 4, "call": "session.read", "args": {"machine": "tower"}}
{"commands":42,"hop":"api","version":1}
{"error":{"code":"not_found","message":"hop has no command named nope.nope"},"id":3}
{"error":{"code":"bad_args","message":"\"name\" is needed"},"id":4}
{"id":1,"ok":{"machines":[{"battery":null,"cores":16,"helper":true,"load":0.74,"machine":"tower","system":"Linux","up":true,"uptime":"1:17","windows":true}]}}
Calls run side by side, so answers can come in any order: above, the two quick errors arrived before the status, which had to ask tower. Match answers to requests by id. A line that is not JSON gets an error with "id": null.
Events and cancel
A command that streams, such as event.watch, sends event lines with its call's id as things happen. It runs until you cancel it with {"id": …, "cancel": true}, then sends its ok line.
{"id": 2, "call": "event.watch", "args": {"machines": ["tower"], "types": ["session.state"]}}
{"id": 2, "cancel": true}
{"id":2,"event":{"type":"session.state","machine":"tower","address":"tower:session/build","at":1794672000,"session":"build","state":"blocked","was":"working","title":"claude"}}
{"id":2,"ok":{"stopped":true}}
Every event has its type, machine, the address of what changed and at (seconds since 1970), plus what that type carries: session, state and was for sessions; window, app and title for windows; port and program for ports.
When stdin closes, hop api stops everything still streaming, waits for every call to answer, and exits.
What there is: hop api schema
hop api schema prints every command as JSON: its name, summary, a longer description (about), its level, its MCP tool name, whether it streams, and its arguments as a JSON Schema. The same comes over the wire as {"id": 1, "call": "api.schema"}. SDKs and these docs are made from it.
$ hop api schema { "hop": "api", "version": 1, "commands": [ { "name": "session.read", "summary": "What a session shows, as plain text", "about": "Read what a session shows: its last lines as plain text, scrolled-off history included.", "level": "read", "mcp": "session_read", "streams": false, "cli": null, "order": ["machine", "name", "lines"], "args": { "type": "object", "properties": { "lines": { "description": "How many lines from the end (default 80)", "type": "integer" }, "machine": { "description": "Machine the session is on", "type": "string" }, "name": { "description": "Session name", "type": "string" } }, "required": ["machine", "name"] } }, …
An argument that takes an address has "format": "hop-address". order lists the arguments in the order the command line fills them, and cli is the command's short form ("windows" for window.list), or null. hop api docs writes the same as Markdown, and hop api commands as one line each.
An example in Python
Nothing but the standard library: start hop api, skip the hello, send a call, read lines until its answer.
import json, subprocess
hop = subprocess.Popen(["hop", "api"], stdin=subprocess.PIPE, stdout=subprocess.PIPE, text=True)
hello = json.loads(hop.stdout.readline())
def call(name, args, id=[0]):
id[0] += 1
hop.stdin.write(json.dumps({"id": id[0], "call": name, "args": args}) + "\n")
hop.stdin.flush()
for line in hop.stdout:
answer = json.loads(line)
if answer.get("id") == id[0] and "event" not in answer:
if "error" in answer:
raise RuntimeError(answer["error"]["message"])
return answer["ok"]
for m in call("machine.status", {})["machines"]:
print(m["machine"], "up" if m["up"] else "down")
Error codes
Every error has a code a program can act on and a message a person can read, which says what to do where it can. The codes are stable within a version.
| Code | Means |
|---|---|
bad_args | An argument is missing or of the wrong kind, or the request is not JSON |
not_found | No such command, machine, session, window, element or file |
no_helper | The machine has no Hop helper (or window helper) to do this |
needs_permission | Someone at the machine has to allow something first, such as Screen Recording or Accessibility on a Mac |
unreachable | The machine could not be reached |
denied | The caller is not allowed to do this (a token without that level or machine) |
unsupported | This machine or host cannot do this yet, or the other side speaks another API version |
timeout | Waited as long as was asked, and it did not happen |
failed | Anything else; the message says what |
Versions
The protocol and the command names are version 1. Within a version, changes only add: new commands, new optional arguments, new fields in results. Nothing is renamed or removed. A change that would break a caller needs version 2, and version 1 keeps answering. Ignore fields you do not know.
SDKs
The TypeScript and Python SDKs speak hop api for you. Every command is a method named after it, grouped by namespace: window.list is hop.window.list(…). They live in the Hop repository under sdk/; sdk/README.md has the details.
TypeScript
Package hop-sdk in sdk/ts, for Node 18 and later, Bun, Deno and browsers, with no dependencies. The commands and their arguments are typed, made from hop api schema.
import { Hop } from 'hop-sdk'
const hop = await Hop.connect() // runs `hop api`
const { machines } = await hop.machine.list()
const said = await hop.shell.run({ machine: 'tower', command: 'uptime' })
for await (const e of hop.event.watch({ types: ['session.state'] }))
if (e.state === 'blocked') await hop.person.notify({ text: `${e.session} needs you` })
hop.close()
Hop.connect()runshop apifrom yourPATH(or{ command: '/path/to/hop' }).{ ssh: 'me@box' }runs it on another machine instead.{ http: { url, token } }talks tohop api serve, which is how a web page gets in.- Calls run side by side; start as many as you like without waiting for each.
- A streaming command is an async iterator. Leaving the loop cancels it.
- A failed call rejects with a
HopErrorthat has acodeand amessage. hop.call(name, args)andhop.watch(name, args)reach any command by name, including ones newer than the SDK.- Results are plain objects. Hop does not describe its results in the schema yet, so check a field before using it.
- Call
close()when done: until then the child process keeps Node running.
Examples in sdk/ts/examples: machines.ts, notify-when-blocked.ts, and browser.html, a page that uses HTTP.
Python
One file, sdk/python/hop.py, for Python 3.9 and later with nothing but the standard library. Copy it next to your script, or put sdk/python on PYTHONPATH.
from hop import Hop, HopError
with Hop.connect() as hop: # or Hop.connect(ssh="me@box")
print(hop.machine.list()["machines"])
print(hop.shell.run(machine="tower", command="uptime")["text"])
for event in hop.event.watch(types=["session.state"]):
if event["state"] == "blocked":
hop.person.notify(text=f"{event['session']} needs you")
- It reads the commands from
hopwhen it connects, so they always match thehopit reached.help(hop.session.read)shows a command's arguments. - An argument whose name Python keeps for itself takes an underscore:
hop.file.copy(from_="tower:~/a", to="studio:~/b"). Or pass a dict:hop.call("file.copy", {"from": …, "to": …}). watchis a generator; leaving the loop cancels it. A failed call raisesHopErrorwithcodeandmessage.
Other languages
Swift calls libhop directly, through its C interface; see Build on Hop. Anything else can speak hop api as above.
HTTP API
hop api serve serves the same commands over HTTP, for web pages, web apps and programs on other machines. It listens on 127.0.0.1:7362; --listen 127.0.0.1:0 picks a free port and prints the one it got.
$ hop api serve hop api: http://127.0.0.1:7362/v1/ (1 token in ~/.config/hop/api-tokens.json)
| Request | Answer |
|---|---|
POST /v1/call/<name> | The arguments as a JSON body; answers {"ok": …} or {"error": …} |
GET /v1/stream/<name>?args=<json> | A streaming command as server-sent events: one data: line an event, then an end event with its answer |
GET /v1/schema | Every command, as hop api schema prints it |
Tokens
Over stdio a program runs as you and can do anything you can. Over HTTP, every request needs a token, and a token allows only some levels on some machines. Make one per program:
$ hop api token add stream-deck --levels read --machines local hop_cee3…53c53 That is the token for stream-deck (shown this once): it may do read on local. $ hop api token list stream-deck read local $ hop api token remove stream-deck
Send it as Authorization: Bearer <token>, or, for GET /v1/stream/… only, as ?token=, since a browser's EventSource cannot set headers. A call outside what the token allows gets denied, and says why:
$ curl -s -X POST -H "Authorization: Bearer $TOKEN" -d '{"machine":"local"}' localhost:7362/v1/call/machine.status {"ok":{"machines":[{"battery":null,"cores":10,"helper":true,"load":6.24,"machine":"local","system":"Darwin","up":true,"uptime":"39 days, 4:12","windows":true}]}} $ curl -s -X POST -H "Authorization: Bearer $TOKEN" -d '{"machine":"local","command":"id"}' localhost:7362/v1/call/shell.run {"error":{"code":"denied","message":"the token stream-deck may not do shell.run (risky level); it may do read"}} $ curl -s -X POST -H "Authorization: Bearer $TOKEN" -d '{"machine":"tower"}' localhost:7362/v1/call/port.list {"error":{"code":"denied","message":"the token stream-deck may not reach tower"}}
Only a hash of each token is kept, in api-tokens.json in Hop's folder. It is read again on every request, so removing a token takes effect at once. Every call made with a token is written to api-log.jsonl beside it: when, which token, which command, and whether it was allowed.
It speaks plain HTTP. It listens only on this computer unless told otherwise. Reach it from elsewhere over something that encrypts, such as Tailscale or an SSH tunnel, as with hop hub.