Skip to content
Python

CLI: machine logs, status --json, launchd service on macOS; install.sh

Rohit C Prasada15fb38c931d
diff --git a/coworker/cli.py b/coworker/cli.py
index bbafb3d5..a3d6cd9b 100644
--- a/coworker/cli.py
+++ b/coworker/cli.py
@@ -34,9 +34,10 @@ commands:
join <link> enroll with the join link from the app, then serve
auth join <url> enroll by approving a code in the app, then serve
up serve again with the stored identity
- status show enrollment and the sealing-key fingerprint
+ status show enrollment and the sealing-key fingerprint (--json)
keys manage provider keys stored on this machine
- service run `up` as a background service
+ service run `up` as a background service (systemd, launchd)
+ logs show the service's log (-f to follow)
leave forget this machine's enrollment and identity
version print the version
diff --git a/coworker/remote/joiner.py b/coworker/remote/joiner.py
index 3a56a14c..56e751ba 100644
--- a/coworker/remote/joiner.py
+++ b/coworker/remote/joiner.py
@@ -12,6 +12,7 @@ from __future__ import annotations
import argparse
import asyncio
import json
+import os
import socket
import sys
import time
@@ -574,7 +575,12 @@ def cli(argv: Optional[list[str]] = None, prog: str = "openworker machine") -> i
p_auth_join.add_argument("--name", default=None, help="machine name (default: hostname)")
sub.add_parser("up", help="start serving with the stored identity")
- sub.add_parser("status", help="show this machine's remote-home state")
+ p_status = sub.add_parser("status", help="show this machine's enrollment and key fingerprints")
+ p_status.add_argument("--json", action="store_true", help="print as JSON (for scripts)")
+ p_logs = sub.add_parser("logs", help="show the service's log (when this machine runs as a service)")
+ p_logs.add_argument("-f", "--follow", action="store_true", help="keep printing new lines")
+ p_logs.add_argument("-n", "--lines", type=int, default=200, help="lines to show first (default 200)")
+ p_logs.add_argument("--unit", default=None, help="service name (default: this machine's)")
# Box-side provisioning (remote-home-design.md §Keys wallet, door 2): write
# secrets straight into THIS machine's store — the wallet never in the path.
p_secrets = sub.add_parser("keys", help="manage provider keys stored on this machine")
@@ -586,7 +592,9 @@ def cli(argv: Optional[list[str]] = None, prog: str = "openworker machine") -> i
p_leave = sub.add_parser("leave", help="forget enrollment AND identity on this box")
p_leave.add_argument("--yes", action="store_true", help="skip confirmation")
# The systemd story: `up` under a unit, restarted forever (P1d).
- p_service = sub.add_parser("service", help="run this joined machine under systemd")
+ p_service = sub.add_parser(
+ "service", help="run this joined machine as a background service (systemd or launchd)"
+ )
service_sub = p_service.add_subparsers(dest="service_command", required=True)
p_install = service_sub.add_parser(
"install", help="write + enable a user unit that keeps this machine serving"
@@ -609,7 +617,9 @@ def cli(argv: Optional[list[str]] = None, prog: str = "openworker machine") -> i
if args.command == "up":
return _cmd_up(state)
if args.command == "status":
- return _cmd_status(state)
+ return _cmd_status(state, as_json=getattr(args, "json", False))
+ if args.command == "logs":
+ return _cmd_logs(state, args)
if args.command == "leave":
return _cmd_leave(state, args.yes)
if args.command == "keys":
@@ -828,10 +838,12 @@ def _systemctl_user(*args: str) -> bool:
def _cmd_service(state: Path, args, platform: Optional[str] = None, home: Optional[Path] = None) -> int:
platform = platform or sys.platform
home = home or Path.home()
+ if platform == "darwin":
+ return _cmd_service_macos(state, args, home)
if platform != "linux":
print(
- "error: `service install` targets Linux/systemd (the VM/server the box "
- "runs on). On macOS just run `openworker machine up` in a terminal or via launchd.",
+ "error: `service` supports Linux (systemd) and macOS (launchd). Here, run "
+ "`openworker machine up` in a terminal that stays open.",
file=sys.stderr,
)
return 2
@@ -908,7 +920,221 @@ def _cmd_service(state: Path, args, platform: Optional[str] = None, home: Option
)
return 0
-def _cmd_status(state: Path) -> int:
+# -- macOS: a launchd agent, the counterpart of the systemd user unit ----------------
+
+_AGENT_PREFIX = "com.openworker.machine"
+
+
+def agent_label_for(machine_name: str) -> str:
+ """`com.openworker.machine.<machine>` — one agent per joined identity."""
+ slug = "".join(ch if ch.isalnum() or ch in "-_" else "-" for ch in (machine_name or "")).strip("-")
+ return f"{_AGENT_PREFIX}.{slug}" if slug else _AGENT_PREFIX
+
+
+def service_log_path(state: Path) -> Path:
+ return state / "logs" / "machine.log"
+
+
+def _launchd_plist(state: Path, exe: str, label: str) -> bytes:
+ """A per-user agent running `up`: started at login, restarted when it exits, state dir
+ pinned. launchd starts agents with a bare PATH, and a coworker runs git, node and the
+ like — so the PATH of the shell that installed the service is carried over."""
+ import plistlib
+ import shlex
+
+ log = str(service_log_path(state))
+ return plistlib.dumps(
+ {
+ "Label": label,
+ "ProgramArguments": [*shlex.split(exe), "up"],
+ "EnvironmentVariables": {
+ "COWORKER_STATE_DIR": str(state),
+ "PATH": os.environ.get("PATH", "/usr/bin:/bin:/usr/sbin:/sbin"),
+ },
+ "RunAtLoad": True,
+ "KeepAlive": True,
+ "ThrottleInterval": 5,
+ "ProcessType": "Background",
+ "StandardOutPath": log,
+ "StandardErrorPath": log,
+ }
+ )
+
+
+def installed_agents(agent_dir: Path) -> list[dict]:
+ """Every OpenWorker launchd agent of this user with the state dir it pins."""
+ import plistlib
+
+ rows = []
+ for path in sorted(agent_dir.glob(f"{_AGENT_PREFIX}*.plist")):
+ try:
+ data = plistlib.loads(path.read_bytes())
+ except Exception:
+ continue
+ rows.append(
+ {
+ "unit": str(data.get("Label") or path.stem),
+ "state_dir": str((data.get("EnvironmentVariables") or {}).get("COWORKER_STATE_DIR") or ""),
+ "path": str(path),
+ }
+ )
+ return rows
+
+
+def _launchctl(*args: str) -> bool:
+ import subprocess
+
+ try:
+ return subprocess.run(["launchctl", *args], capture_output=True, timeout=15).returncode == 0
+ except (OSError, Exception):
+ return False
+
+
+def _cmd_service_macos(state: Path, args, home: Path) -> int:
+ agent_dir = home / "Library" / "LaunchAgents"
+ cfg = load_remote_config(state)
+ derived = agent_label_for(str(cfg.get("name") or "")) if cfg else _AGENT_PREFIX
+ domain = f"gui/{os.getuid()}"
+ if args.service_command == "uninstall":
+ wanted = getattr(args, "unit", None) or derived
+ plist = agent_dir / f"{wanted}.plist"
+ _launchctl("bootout", f"{domain}/{wanted}")
+ plist.unlink(missing_ok=True)
+ print(f"removed {plist}")
+ return 0
+ if args.service_command == "list":
+ rows = installed_agents(agent_dir)
+ if not rows:
+ print("no openworker services installed")
+ for row in rows:
+ print(f"{row['unit']} state={row['state_dir'] or '?'}")
+ return 0
+ if cfg is None:
+ print(
+ "error: this machine has not joined a controller yet — run "
+ "`openworker machine join <link>` first, then install the service.",
+ file=sys.stderr,
+ )
+ return 2
+ import shutil
+
+ # Same rule as on Linux: a second service on the SAME state dir is refused (two engines,
+ # one database); services on other state dirs are reported.
+ others = [r for r in installed_agents(agent_dir) if r["unit"] != derived]
+ same = [r for r in others if r["state_dir"] and Path(r["state_dir"]) == Path(state)]
+ if same and not getattr(args, "force", False):
+ for r in same:
+ print(
+ f"error: {r['unit']} already runs on this state dir ({state}). Remove it first "
+ f"(`openworker machine service uninstall --unit {r['unit']}`) or pass --force "
+ "to replace it.",
+ file=sys.stderr,
+ )
+ return 2
+ for r in same:
+ _launchctl("bootout", f"{domain}/{r['unit']}")
+ Path(r["path"]).unlink(missing_ok=True)
+ print(f"replaced {r['unit']}")
+ for r in others:
+ if r not in same:
+ print(
+ f"note: {r['unit']} is also installed (state {r['state_dir'] or '?'}) — "
+ "a second engine on this Mac; remove it if it is stale."
+ )
+
+ exe = shutil.which("openworker") or f"{sys.executable} -m coworker.cli"
+ plist = agent_dir / f"{derived}.plist"
+ plist.parent.mkdir(parents=True, exist_ok=True)
+ service_log_path(state).parent.mkdir(parents=True, exist_ok=True)
+ plist.write_bytes(_launchd_plist(state, exe, derived))
+ print(f"wrote {plist}")
+ _launchctl("bootout", f"{domain}/{derived}") # a reinstall replaces the loaded copy
+ if _launchctl("bootstrap", domain, str(plist)):
+ print("service loaded: it starts at login and restarts if it stops.")
+ print("Logs: openworker machine logs -f")
+ print("It runs while you are logged in. For a Mac that must serve with nobody logged in,")
+ print("turn on automatic login, or keep the session open.")
+ else:
+ print(
+ "launchd was not reachable from here — load it manually:\n"
+ f" launchctl bootstrap {domain} {plist}"
+ )
+ return 0
+
+
+# -- logs ----------------------------------------------------------------------------
+
+
+def logs_command(
+ state: Path, platform: str, unit: Optional[str], lines: int, follow: bool
+) -> Optional[list[str]]:
+ """The command that prints this machine's service log, or None where there is none."""
+ n = str(max(1, int(lines)))
+ if platform == "linux":
+ cfg = load_remote_config(state)
+ name = unit or (unit_name_for(str(cfg.get("name") or "")) if cfg else SERVICE_UNIT_NAME)
+ return ["journalctl", "--user", "-u", name, "-n", n, *(["-f"] if follow else [])]
+ if platform == "darwin":
+ return ["tail", "-n", n, *(["-f"] if follow else []), str(service_log_path(state))]
+ return None
+
+
+def _cmd_logs(state: Path, args, platform: Optional[str] = None) -> int:
+ import subprocess
+
+ platform = platform or sys.platform
+ cmd = logs_command(state, platform, getattr(args, "unit", None), args.lines, args.follow)
+ if cmd is None:
+ print("error: `logs` supports Linux (systemd) and macOS (launchd).", file=sys.stderr)
+ return 2
+ if platform == "darwin" and not service_log_path(state).exists():
+ print(
+ "no service log yet. Logs are kept when this machine runs as a service "
+ "(`openworker machine service install`); in a terminal, `up` prints them there.",
+ file=sys.stderr,
+ )
+ return 1
+ try:
+ return subprocess.call(cmd)
+ except KeyboardInterrupt:
+ return 0
+ except OSError as exc:
+ print(f"error: could not run {cmd[0]}: {exc}", file=sys.stderr)
+ return 2
+
+
+def machine_status(state: Path) -> dict:
+ """What `status` reports, as data (`status --json` prints exactly this)."""
+ from .channel import app_version
+
+ cfg = load_remote_config(state)
+ out: dict = {
+ "version": app_version(),
+ "state_dir": str(state),
+ "joined": cfg is not None,
+ "identity": None,
+ "sealing_key": None,
+ "controller": None,
+ "name": None,
+ "machine_id": None,
+ }
+ if (state / KEY_FILENAME).exists():
+ identity = load_or_create(state)
+ out["identity"] = identity.fingerprint
+ out["sealing_key"] = identity.seal_fingerprint
+ if cfg is not None:
+ out.update(
+ controller=cfg["controller"],
+ name=cfg.get("name", ""),
+ machine_id=cfg.get("machine_id", ""),
+ )
+ return out
+
+
+def _cmd_status(state: Path, as_json: bool = False) -> int:
+ if as_json:
+ print(json.dumps(machine_status(state), indent=2))
+ return 0
cfg = load_remote_config(state)
key_path = state / KEY_FILENAME
print(f"state dir: {state}")
diff --git a/packaging/install.sh b/packaging/install.sh
new file mode 100755
index 00000000..933899b8
--- /dev/null
+++ b/packaging/install.sh
@@ -0,0 +1,89 @@
+#!/bin/sh
+# OpenWorker headless installer — Linux and macOS.
+#
+# curl -fsSL https://openworker.com/install.sh | sh
+#
+# Installs the `openworker` command for the current user (no sudo): it uses `uv` when present,
+# `pipx` when that is what the machine has, and otherwise installs `uv` first (uv brings its
+# own Python, so the system's Python version does not matter). Re-run it to upgrade.
+#
+# Settings (environment variables):
+# OPENWORKER_VERSION install this exact version (default: the latest)
+# OPENWORKER_PACKAGE what to install (default: "openworker"; a wheel path or URL also works)
+#
+# The whole script is one function called on the last line, so a download that is cut off
+# half-way runs nothing.
+
+set -eu
+
+main() {
+ package="${OPENWORKER_PACKAGE:-openworker}"
+ if [ -n "${OPENWORKER_VERSION:-}" ] && [ "$package" = "openworker" ]; then
+ package="openworker==${OPENWORKER_VERSION}"
+ fi
+
+ say() { printf '%s\n' "$*"; }
+ fail() { printf 'error: %s\n' "$*" >&2; exit 1; }
+
+ case "$(uname -s)" in
+ Linux | Darwin) ;;
+ *) fail "this installer supports Linux and macOS. On Windows, use the desktop app: https://openworker.com" ;;
+ esac
+
+ if [ "$(id -u)" = "0" ]; then
+ say "note: running as root installs OpenWorker for root only. A normal user account is the usual choice."
+ fi
+
+ if command -v uv >/dev/null 2>&1; then
+ installer="uv"
+ elif command -v pipx >/dev/null 2>&1; then
+ installer="pipx"
+ else
+ command -v curl >/dev/null 2>&1 || fail "curl is needed to fetch uv. Install curl, or install uv or pipx yourself, then run this again."
+ say "Installing uv (https://docs.astral.sh/uv/) — it manages Python for OpenWorker…"
+ curl -LsSf https://astral.sh/uv/install.sh | sh
+ # uv's installer puts it here; this shell has not re-read its profile yet.
+ PATH="${UV_INSTALL_DIR:-${XDG_BIN_HOME:-$HOME/.local/bin}}:$HOME/.cargo/bin:$PATH"
+ export PATH
+ command -v uv >/dev/null 2>&1 || fail "uv was installed but is not on PATH. Open a new terminal and run this again."
+ installer="uv"
+ fi
+
+ say "Installing ${package} with ${installer}…"
+ if [ "$installer" = "uv" ]; then
+ uv tool install --upgrade "$package"
+ bin_dir="$(uv tool dir --bin 2>/dev/null || printf '%s' "$HOME/.local/bin")"
+ else
+ pipx install --force "$package"
+ bin_dir="${PIPX_BIN_DIR:-$HOME/.local/bin}"
+ fi
+
+ openworker_bin="${bin_dir}/openworker"
+ [ -x "$openworker_bin" ] || openworker_bin="$(command -v openworker || true)"
+ [ -n "$openworker_bin" ] || fail "the install finished but the openworker command was not found."
+
+ version_line="$("$openworker_bin" version 2>&1 || true)"
+ case "$version_line" in
+ *placeholder*)
+ fail "the OpenWorker runtime is not published to PyPI yet (the name holds a placeholder). See https://github.com/andrewyng/openworker"
+ ;;
+ esac
+
+ say ""
+ say "Installed: ${version_line}"
+ case ":${PATH}:" in
+ *":${bin_dir}:"*) ;;
+ *)
+ say ""
+ say "Add it to your PATH (then open a new terminal):"
+ say " export PATH=\"${bin_dir}:\$PATH\""
+ ;;
+ esac
+ say ""
+ say "Next:"
+ say " 1. In the OpenWorker app: Settings > Machines > Add a machine, and copy the join link."
+ say " 2. Here: openworker machine join <link>"
+ say " 3. To keep it running in the background: openworker machine service install"
+}
+
+main "$@"
diff --git a/tests/test_cli_surface.py b/tests/test_cli_surface.py
index 62adf547..97c5c47b 100644
--- a/tests/test_cli_surface.py
+++ b/tests/test_cli_surface.py
@@ -60,3 +60,137 @@ def test_keys_is_the_public_name_and_secrets_still_works(tmp_path, monkeypatch,
assert joiner.cli(["secrets", "list"]) == 0
out = capsys.readouterr().out
assert "openai" in out and "sk-local" not in out
+
+
+# -- status --json, logs, and the macOS service ---------------------------------------
+
+import argparse
+import json
+import plistlib
+from pathlib import Path
+
+
+def _joined(tmp_path: Path, name: str = "mini") -> Path:
+ state = tmp_path / "state"
+ state.mkdir()
+ joiner.save_remote_config(
+ state, {"controller": "http://10.0.0.5:9787", "name": name, "machine_id": "m1"}
+ )
+ return state
+
+
+def test_status_json_is_machine_readable(tmp_path, monkeypatch, capsys):
+ monkeypatch.setenv("COWORKER_STATE_DIR", str(tmp_path))
+ assert joiner.cli(["status", "--json"]) == 0
+ data = json.loads(capsys.readouterr().out)
+ assert data["joined"] is False and data["controller"] is None and data["identity"] is None
+ assert data["state_dir"] == str(tmp_path) and data["version"][0].isdigit()
+
+ joiner.save_remote_config(tmp_path, {"controller": "http://c:1", "name": "box", "machine_id": "m9"})
+ assert joiner.cli(["status", "--json"]) == 0
+ data = json.loads(capsys.readouterr().out)
+ assert data["joined"] is True and data["name"] == "box" and data["machine_id"] == "m9"
+
+
+def test_logs_command_per_platform(tmp_path):
+ state = _joined(tmp_path, "cloud vm")
+ assert joiner.logs_command(state, "linux", None, 50, True) == [
+ "journalctl", "--user", "-u", "openworker-cloud-vm.service", "-n", "50", "-f",
+ ]
+ assert joiner.logs_command(state, "linux", "openworker.service", 10, False)[3] == "openworker.service"
+ mac = joiner.logs_command(state, "darwin", None, 200, False)
+ assert mac == ["tail", "-n", "200", str(state / "logs" / "machine.log")]
+ assert joiner.logs_command(state, "win32", None, 200, False) is None
+
+
+def test_logs_on_macos_without_a_service_log_explains(tmp_path, capsys):
+ state = _joined(tmp_path)
+ args = argparse.Namespace(unit=None, lines=200, follow=False)
+ assert joiner._cmd_logs(state, args, platform="darwin") == 1
+ assert "service install" in capsys.readouterr().err
+
+
+def test_macos_service_install_writes_a_launchd_agent(tmp_path, monkeypatch, capsys):
+ state = _joined(tmp_path, "mac mini")
+ calls: list[tuple] = []
+ monkeypatch.setattr(joiner, "_launchctl", lambda *a: calls.append(a) or True)
+ args = argparse.Namespace(service_command="install", force=False)
+ assert joiner._cmd_service(state, args, platform="darwin", home=tmp_path) == 0
+
+ plist_path = tmp_path / "Library" / "LaunchAgents" / "com.openworker.machine.mac-mini.plist"
+ data = plistlib.loads(plist_path.read_bytes())
+ assert data["Label"] == "com.openworker.machine.mac-mini"
+ assert data["ProgramArguments"][-1] == "up"
+ assert data["EnvironmentVariables"]["COWORKER_STATE_DIR"] == str(state)
+ assert data["EnvironmentVariables"]["PATH"] # launchd's own PATH is too bare for a coworker
+ assert data["RunAtLoad"] is True and data["KeepAlive"] is True
+ assert data["StandardOutPath"] == str(state / "logs" / "machine.log")
+ assert any(c[0] == "bootstrap" and c[-1] == str(plist_path) for c in calls)
+ assert "openworker machine logs -f" in capsys.readouterr().out
+
+ # list shows it with its state dir; uninstall unloads and removes it.
+ assert joiner._cmd_service(state, argparse.Namespace(service_command="list"), platform="darwin", home=tmp_path) == 0
+ assert f"com.openworker.machine.mac-mini state={state}" in capsys.readouterr().out
+ assert joiner._cmd_service(
+ state, argparse.Namespace(service_command="uninstall", unit=None), platform="darwin", home=tmp_path
+ ) == 0
+ assert not plist_path.exists()
+ assert any(c[0] == "bootout" for c in calls)
+
+
+def test_macos_service_install_refuses_a_twin_on_the_same_state_dir(tmp_path, monkeypatch, capsys):
+ state = _joined(tmp_path, "mini")
+ monkeypatch.setattr(joiner, "_launchctl", lambda *a: True)
+ agent_dir = tmp_path / "Library" / "LaunchAgents"
+ agent_dir.mkdir(parents=True)
+ (agent_dir / "com.openworker.machine.old.plist").write_bytes(
+ joiner._launchd_plist(state, "/old/openworker", "com.openworker.machine.old")
+ )
+ args = argparse.Namespace(service_command="install", force=False)
+ assert joiner._cmd_service(state, args, platform="darwin", home=tmp_path) == 2
+ assert "com.openworker.machine.old already runs" in capsys.readouterr().err
+ assert not (agent_dir / "com.openworker.machine.mini.plist").exists()
+
+ args.force = True
+ assert joiner._cmd_service(state, args, platform="darwin", home=tmp_path) == 0
+ assert not (agent_dir / "com.openworker.machine.old.plist").exists()
+ assert (agent_dir / "com.openworker.machine.mini.plist").exists()
+
+
+def test_service_needs_a_joined_machine_and_a_supported_platform(tmp_path, capsys):
+ args = argparse.Namespace(service_command="install", force=False)
+ assert joiner._cmd_service(tmp_path, args, platform="darwin", home=tmp_path) == 2
+ assert "machine join" in capsys.readouterr().err
+ assert joiner._cmd_service(tmp_path, args, platform="win32", home=tmp_path) == 2
+ assert "systemd" in capsys.readouterr().err
+
+
+# -- packaging/install.sh --------------------------------------------------------------
+
+import shutil
+import subprocess
+
+INSTALL_SH = Path(__file__).resolve().parents[1] / "packaging" / "install.sh"
+
+
+def test_install_script_is_valid_posix_shell_and_runs_nothing_if_truncated():
+ text = INSTALL_SH.read_text()
+ # One function, called on the last line: a download cut off half-way defines nothing runnable.
+ assert text.rstrip().endswith('main "$@"')
+ assert text.count("\nmain() {") == 1
+ for shell in ("sh", "dash"):
+ exe = shutil.which(shell)
+ if exe:
+ assert subprocess.run([exe, "-n", str(INSTALL_SH)]).returncode == 0
+ # No sudo, and it points people at the public command spelling.
+ assert "sudo" not in text.replace("(no sudo)", "")
+ assert "openworker machine join <link>" in text
+
+
+def test_install_script_refuses_an_unsupported_os(tmp_path):
+ fake = tmp_path / "uname"
+ fake.write_text("#!/bin/sh\necho Plan9\n")
+ fake.chmod(0o755)
+ env = {"PATH": f"{tmp_path}:/usr/bin:/bin", "HOME": str(tmp_path)}
+ done = subprocess.run(["sh", str(INSTALL_SH)], env=env, capture_output=True, text=True)
+ assert done.returncode == 1 and "Linux and macOS" in done.stderr
diff --git a/tests/test_remote_home.py b/tests/test_remote_home.py
index 6e329fa7..340b8bfd 100644
--- a/tests/test_remote_home.py
+++ b/tests/test_remote_home.py
@@ -1661,9 +1661,9 @@ def test_service_install_refuses_non_linux_and_unjoined(tmp_path, capsys):
from coworker.remote import joiner
args = argparse.Namespace(service_command="install")
- # Not Linux → clear refusal.
- assert joiner._cmd_service(tmp_path, args, platform="darwin", home=tmp_path) == 2
- assert "targets Linux/systemd" in capsys.readouterr().err
+ # Neither Linux nor macOS → clear refusal (macOS has its own launchd path now).
+ assert joiner._cmd_service(tmp_path, args, platform="win32", home=tmp_path) == 2
+ assert "Linux (systemd) and macOS (launchd)" in capsys.readouterr().err
# Linux but never joined → point at `join` first.
assert joiner._cmd_service(tmp_path, args, platform="linux", home=tmp_path) == 2
assert "has not joined" in capsys.readouterr().err