hatchway 0.0.2__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
hatchway/__init__.py ADDED
@@ -0,0 +1,38 @@
1
+ """hatchway: a narrow, logged opening through which an outside agent reaches your tools.
2
+
3
+ An agent that lives elsewhere (a personal assistant on its own cloud VM, a phone
4
+ shortcut, another machine's scheduler) gets one SSH key. That key can do one thing:
5
+ run :func:`gate`, which reads the requested command line, checks it against a profile
6
+ (an allowlist kept as data), logs it, and runs it without a shell, or refuses.
7
+
8
+ >>> from hatchway import decide, load_profile
9
+ >>> profile = load_profile("claude-fleet")
10
+ >>> decide("crowsnest triage --quiet", profile).allowed
11
+ True
12
+ >>> decide("crowsnest spawn x --prompt hi", profile).allowed # gated off by default
13
+ False
14
+ """
15
+
16
+ from hatchway.config import Settings, load_profile, load_settings
17
+ from hatchway.gate import gate
18
+ from hatchway.install import authorize, install_schedule, install_skills, key_line, revoke
19
+ from hatchway.policy import Decision, Profile, Rule, decide, describe
20
+ from hatchway.snapshot import snapshot
21
+
22
+ __all__ = [
23
+ "Decision",
24
+ "Profile",
25
+ "Rule",
26
+ "Settings",
27
+ "authorize",
28
+ "decide",
29
+ "describe",
30
+ "gate",
31
+ "install_schedule",
32
+ "install_skills",
33
+ "key_line",
34
+ "load_profile",
35
+ "load_settings",
36
+ "revoke",
37
+ "snapshot",
38
+ ]
hatchway/__main__.py ADDED
@@ -0,0 +1,185 @@
1
+ """The ``hatchway`` command line.
2
+
3
+ hatchway gate --agent muse # the forced command sshd runs (reads $SSH_ORIGINAL_COMMAND)
4
+ hatchway check "crowsnest triage" # what the gate would do, without running it
5
+ hatchway help # every allowed request, one per line
6
+ hatchway snapshot # run the snapshot requests now
7
+ hatchway authorize KEY --agent muse # add the confined authorized_keys line
8
+ hatchway revoke --agent muse # remove it
9
+ hatchway schedule --every 300 # run the snapshot on a timer (launchd / systemd)
10
+ hatchway install-skills # link the bundled skills into Claude homes
11
+ hatchway setup KEY --agent muse # all of the above, in order, on a new machine
12
+ hatchway log # the last calls an agent made
13
+
14
+ The CLI is plain ``argparse`` on purpose: a gate should import as little as possible.
15
+ """
16
+
17
+ from __future__ import annotations
18
+
19
+ import argparse
20
+ import json
21
+ import sys
22
+
23
+ from hatchway.config import load_profile, load_settings
24
+
25
+
26
+ def _print(obj) -> None:
27
+ print(json.dumps(obj, indent=2, ensure_ascii=False) if not isinstance(obj, str) else obj)
28
+
29
+
30
+ def main(argv: list[str] | None = None) -> int:
31
+ ap = argparse.ArgumentParser(prog="hatchway", description=__doc__.splitlines()[1])
32
+ sub = ap.add_subparsers(dest="cmd", required=True)
33
+
34
+ g = sub.add_parser("gate", help="the forced command: decide and run $SSH_ORIGINAL_COMMAND")
35
+ g.add_argument("--agent", default="agent")
36
+ g.add_argument("--profile")
37
+ g.add_argument("--request", help="use this instead of $SSH_ORIGINAL_COMMAND (testing)")
38
+
39
+ c = sub.add_parser("check", help="what the gate would do with a request; runs nothing")
40
+ c.add_argument("request")
41
+ c.add_argument("--profile")
42
+
43
+ h = sub.add_parser("help", help="every allowed request")
44
+ h.add_argument("--profile")
45
+
46
+ s = sub.add_parser("snapshot", help="run the profile's snapshot requests now")
47
+ s.add_argument("--profile")
48
+
49
+ a = sub.add_parser("authorize", help="add the confined authorized_keys line for a key")
50
+ a.add_argument("public_key", help="the whole public key line, quoted")
51
+ a.add_argument("--agent", required=True)
52
+ a.add_argument("--profile")
53
+ a.add_argument(
54
+ "--from",
55
+ dest="from_",
56
+ default=None,
57
+ help="allowed source addresses (default: Tailscale's ranges)",
58
+ )
59
+ a.add_argument("--anywhere", action="store_true", help="no from= restriction")
60
+ a.add_argument("--authorized-keys", default="~/.ssh/authorized_keys")
61
+ a.add_argument("--replace", action="store_true")
62
+ a.add_argument("--dry-run", action="store_true")
63
+
64
+ r = sub.add_parser("revoke", help="remove the gate's lines for an agent")
65
+ r.add_argument("--agent", required=True)
66
+ r.add_argument("--authorized-keys", default="~/.ssh/authorized_keys")
67
+ r.add_argument("--dry-run", action="store_true")
68
+
69
+ t = sub.add_parser("schedule", help="run the snapshot on a timer")
70
+ t.add_argument("--every", type=int, default=300, help="seconds (default 300)")
71
+ t.add_argument("--dry-run", action="store_true")
72
+
73
+ k = sub.add_parser("install-skills", help="link the bundled skills into Claude homes")
74
+ k.add_argument("--home", action="append", help="a Claude home; repeat for several")
75
+ k.add_argument("--force", action="store_true")
76
+ k.add_argument("--dry-run", action="store_true")
77
+
78
+ su = sub.add_parser("setup", help="config, self-test, authorize, snapshot timer, skills")
79
+ su.add_argument("public_key")
80
+ su.add_argument("--agent", required=True)
81
+ su.add_argument("--every", type=int, default=300, help="snapshot seconds; 0 for none")
82
+ su.add_argument("--no-skills", action="store_true")
83
+
84
+ lg = sub.add_parser("log", help="the last calls made through the gate")
85
+ lg.add_argument("-n", type=int, default=20)
86
+
87
+ args = ap.parse_args(argv)
88
+ settings = load_settings()
89
+
90
+ if args.cmd == "gate":
91
+ from hatchway.gate import gate
92
+
93
+ return gate(args.request, agent=args.agent, profile=args.profile, settings=settings)
94
+ if args.cmd in ("check", "help"):
95
+ from hatchway.policy import decide, describe
96
+
97
+ profile = load_profile(args.profile or settings.profile, settings=settings)
98
+ if args.cmd == "help":
99
+ _print("\n".join(describe(profile)))
100
+ return 0
101
+ d = decide(
102
+ args.request,
103
+ profile,
104
+ flags_present=settings.flags_present(),
105
+ dispatch_roots=settings.dispatch_roots,
106
+ roots=settings.all_roots(),
107
+ )
108
+ _print(
109
+ {
110
+ "allowed": d.allowed,
111
+ "reason": d.reason,
112
+ "class": d.klass,
113
+ "argv": list(d.argv),
114
+ "path": d.path,
115
+ }
116
+ )
117
+ return 0 if d.allowed else 126
118
+ if args.cmd == "snapshot":
119
+ from hatchway.snapshot import snapshot
120
+
121
+ _print(snapshot(profile=args.profile, settings=settings))
122
+ return 0
123
+ if args.cmd == "authorize":
124
+ from hatchway.install import TAILNET_FROM, authorize
125
+
126
+ from_ = None if args.anywhere else (args.from_ or TAILNET_FROM)
127
+ res = authorize(
128
+ args.public_key,
129
+ agent=args.agent,
130
+ profile=args.profile,
131
+ from_=from_,
132
+ authorized_keys=args.authorized_keys,
133
+ replace=args.replace,
134
+ dry_run=args.dry_run,
135
+ settings=settings,
136
+ )
137
+ _print(res)
138
+ return 1 if res["action"] == "conflict" else 0
139
+ if args.cmd == "revoke":
140
+ from hatchway.install import revoke
141
+
142
+ _print(
143
+ revoke(
144
+ args.agent,
145
+ authorized_keys=args.authorized_keys,
146
+ dry_run=args.dry_run,
147
+ settings=settings,
148
+ )
149
+ )
150
+ return 0
151
+ if args.cmd == "schedule":
152
+ from hatchway.install import install_schedule
153
+
154
+ _print(install_schedule(every=args.every, dry_run=args.dry_run))
155
+ return 0
156
+ if args.cmd == "install-skills":
157
+ from hatchway.install import install_skills
158
+
159
+ rows = install_skills(homes=args.home, force=args.force, dry_run=args.dry_run)
160
+ _print(rows)
161
+ return 1 if any(r["action"] == "conflict" for r in rows) else 0
162
+ if args.cmd == "setup":
163
+ from hatchway.install import setup
164
+
165
+ res = setup(
166
+ args.public_key,
167
+ agent=args.agent,
168
+ every=args.every or None,
169
+ skills=not args.no_skills,
170
+ settings=settings,
171
+ )
172
+ _print(res)
173
+ return 0 if "stopped" not in res and res["authorize"]["action"] != "conflict" else 1
174
+ if args.cmd == "log":
175
+ path = settings.data_dir / "calls.jsonl"
176
+ lines = (
177
+ [x for x in path.read_text().split("\n") if x][-args.n :] if path.exists() else []
178
+ )
179
+ _print("\n".join(lines) or "(no calls yet)")
180
+ return 0
181
+ return 2
182
+
183
+
184
+ if __name__ == "__main__":
185
+ sys.exit(main())
hatchway/config.py ADDED
@@ -0,0 +1,117 @@
1
+ """Where hatchway keeps its configuration and its records, and how a profile is found.
2
+
3
+ Config: ``$HATCHWAY_CONFIG_DIR`` or ``~/.config/hatchway/`` (``config.toml``, the flag
4
+ files such as ``allow-dispatch``, optional user profiles in ``profiles/``).
5
+ Data: ``$HATCHWAY_DATA_DIR`` or ``~/.local/share/hatchway/`` (``calls.jsonl``, the
6
+ snapshot in ``out/``, backups of files hatchway edited in ``backups/``).
7
+
8
+ The config file is optional; every key has a default::
9
+
10
+ profile = "claude-fleet" # a bundled profile name, or a path to a .toml
11
+ path = ["/opt/bin"] # prepended to PATH for the commands the gate runs
12
+ timeout = 120 # seconds before a command is stopped
13
+ [roots] # directories file rules may serve, by name
14
+ ledger = "~/.local/share/crowsnest/ledger"
15
+ [dispatch]
16
+ roots = ["~/projects"] # where a dispatch (spawn) may start a session
17
+ [snapshot]
18
+ to = "" # optional extra copy: a local dir or host:path (rsync)
19
+ """
20
+
21
+ from __future__ import annotations
22
+
23
+ import os
24
+ import tomllib
25
+ from collections.abc import Mapping
26
+ from dataclasses import dataclass, field
27
+ from pathlib import Path
28
+
29
+ from hatchway.policy import Profile
30
+
31
+ DFLT_PROFILE = "claude-fleet"
32
+ DFLT_TIMEOUT = 120
33
+ BUNDLED_PROFILES = Path(__file__).parent / "data" / "profiles"
34
+
35
+
36
+ def config_dir() -> Path:
37
+ return Path(os.environ.get("HATCHWAY_CONFIG_DIR", "~/.config/hatchway")).expanduser()
38
+
39
+
40
+ def data_dir() -> Path:
41
+ return Path(os.environ.get("HATCHWAY_DATA_DIR", "~/.local/share/hatchway")).expanduser()
42
+
43
+
44
+ @dataclass
45
+ class Settings:
46
+ """The resolved configuration the gate and the snapshot run with."""
47
+
48
+ profile: str = DFLT_PROFILE
49
+ path: list[str] = field(default_factory=list)
50
+ timeout: int = DFLT_TIMEOUT
51
+ roots: dict[str, str] = field(default_factory=dict)
52
+ dispatch_roots: list[str] = field(default_factory=list)
53
+ snapshot_to: str = ""
54
+ config_dir: Path = field(default_factory=config_dir)
55
+ data_dir: Path = field(default_factory=data_dir)
56
+
57
+ @classmethod
58
+ def from_mapping(cls, d: Mapping, **overrides) -> Settings:
59
+ s = cls(
60
+ profile=d.get("profile", DFLT_PROFILE),
61
+ path=list(d.get("path", [])),
62
+ timeout=int(d.get("timeout", DFLT_TIMEOUT)),
63
+ roots=dict(d.get("roots", {})),
64
+ dispatch_roots=list(d.get("dispatch", {}).get("roots", [])),
65
+ snapshot_to=d.get("snapshot", {}).get("to", ""),
66
+ )
67
+ for k, v in overrides.items():
68
+ if v is not None:
69
+ setattr(s, k, v)
70
+ return s
71
+
72
+ @property
73
+ def out_dir(self) -> Path:
74
+ return self.data_dir / "out"
75
+
76
+ def all_roots(self) -> dict[str, str]:
77
+ """File-rule roots: ``out`` (the snapshot) always, plus the configured ones."""
78
+ return {"out": str(self.out_dir), **self.roots}
79
+
80
+ def flags_present(self) -> frozenset[str]:
81
+ d = self.config_dir
82
+ if not d.is_dir():
83
+ return frozenset()
84
+ return frozenset(
85
+ p.name for p in d.iterdir() if p.is_file() and p.name.startswith("allow-")
86
+ )
87
+
88
+
89
+ def load_settings(*, config_file: str | Path | None = None, **overrides) -> Settings:
90
+ """Read ``config.toml`` (absent is fine) into :class:`Settings`."""
91
+ cdir = config_dir()
92
+ path = Path(config_file) if config_file else cdir / "config.toml"
93
+ d = tomllib.loads(path.read_text()) if path.is_file() else {}
94
+ return Settings.from_mapping(d, config_dir=cdir, data_dir=data_dir(), **overrides)
95
+
96
+
97
+ def profile_path(name_or_path: str, *, settings: Settings | None = None) -> Path:
98
+ """A profile by path, else ``<config>/profiles/<name>.toml``, else a bundled one."""
99
+ p = Path(name_or_path).expanduser()
100
+ if p.suffix == ".toml" and p.is_file():
101
+ return p
102
+ cdir = settings.config_dir if settings else config_dir()
103
+ for candidate in (
104
+ cdir / "profiles" / f"{name_or_path}.toml",
105
+ BUNDLED_PROFILES / f"{name_or_path}.toml",
106
+ ):
107
+ if candidate.is_file():
108
+ return candidate
109
+ known = sorted(q.stem for q in BUNDLED_PROFILES.glob("*.toml"))
110
+ raise FileNotFoundError(f"no profile {name_or_path!r}; bundled: {', '.join(known)}")
111
+
112
+
113
+ def load_profile(
114
+ name_or_path: str = DFLT_PROFILE, *, settings: Settings | None = None
115
+ ) -> Profile:
116
+ path = profile_path(name_or_path, settings=settings)
117
+ return Profile.from_dict(tomllib.loads(path.read_text()), name=path.stem)
@@ -0,0 +1,189 @@
1
+ # claude-fleet: what an outside agent may ask of a machine running Claude Code sessions,
2
+ # watched by crowsnest (live sessions) and openloops (what they left owed or blocked).
3
+ #
4
+ # Requests are the words the agent sends; `argv` is what actually runs, with the checked
5
+ # extras appended and any names placed after `--`. Anything not described is refused.
6
+ # Copy this file to ~/.config/hatchway/profiles/<name>.toml to change it for one machine.
7
+
8
+ name = "claude-fleet"
9
+
10
+ [classes.read]
11
+ # reading: always on once the key is authorised
12
+
13
+ [classes.dispatch]
14
+ # starting a session runs an agent with your permissions: off until you create
15
+ # ~/.config/hatchway/allow-dispatch AND list [dispatch] roots in config.toml
16
+ requires_flag = "allow-dispatch"
17
+
18
+ # --- crowsnest: live sessions ---------------------------------------------------------
19
+
20
+ [[rule]]
21
+ match = ["crowsnest"]
22
+ argv = ["crowsnest", "roster", "--all-homes"]
23
+ flags = ["-b", "--brief", "-j", "--json"]
24
+ help = "the roster: waiting on the owner first, then busy, then idle"
25
+
26
+ [[rule]]
27
+ match = ["crowsnest", "roster"]
28
+ argv = ["crowsnest", "roster", "--all-homes"]
29
+ flags = ["-b", "--brief", "-j", "--json"]
30
+ help = "same as bare crowsnest"
31
+
32
+ [[rule]]
33
+ match = ["crowsnest", "triage"]
34
+ argv = ["crowsnest", "triage", "--all-homes"]
35
+ flags = ["-q", "--quiet", "-j", "--json", "-p", "--plain"]
36
+ help = "what needs the owner, what is safe to close, what is working"
37
+
38
+ [[rule]]
39
+ match = ["crowsnest", "show"]
40
+ argv = ["crowsnest", "show", "--all-homes"]
41
+ flags = ["-j", "--json"]
42
+ value_flags = [{ names = ["-r", "--recent"], pattern = "[0-9]{1,2}" }]
43
+ min_positional = 1
44
+ max_positional = 1
45
+ help = "one session in full (quotes its transcript)"
46
+
47
+ [[rule]]
48
+ match = ["crowsnest", "turns"]
49
+ argv = ["crowsnest", "turns", "--all-homes"]
50
+ flags = ["-j", "--json"]
51
+ value_flags = [
52
+ { names = ["-l", "--last"], pattern = "[0-9]{1,2}" },
53
+ { names = ["-b", "--before"], pattern = "[0-9]{1,5}" },
54
+ ]
55
+ min_positional = 1
56
+ max_positional = 1
57
+ help = "the last few turns of one session"
58
+
59
+ [[rule]]
60
+ match = ["crowsnest", "recap"]
61
+ argv = ["crowsnest", "recap", "--all-homes"]
62
+ flags = ["-j", "--json"]
63
+ min_positional = 1
64
+ max_positional = 1
65
+ help = "five lines about one session, from disk"
66
+
67
+ [[rule]]
68
+ match = ["crowsnest", "brief"]
69
+ argv = ["crowsnest", "brief", "--all-homes"]
70
+ flags = ["-j", "--json"]
71
+ min_positional = 1
72
+ max_positional = 1
73
+ help = "openloops' dated digest of one session"
74
+
75
+ [[rule]]
76
+ match = ["crowsnest", "ledger"]
77
+ argv = ["crowsnest", "ledger"]
78
+ flags = ["-j", "--json"]
79
+ max_positional = 8
80
+ help = "every ledger with its age, or the named ones in full"
81
+
82
+ [[rule]]
83
+ match = ["crowsnest", "groups"]
84
+ argv = ["crowsnest", "groups", "--all-homes"]
85
+ flags = ["-j", "--json"]
86
+ value_flags = [{ names = ["-b", "--by"], pattern = "[a-z]{1,20}" }]
87
+ help = "live sessions grouped by theme or project"
88
+
89
+ [[rule]]
90
+ match = ["crowsnest", "synopsis"]
91
+ argv = ["crowsnest", "synopsis", "--all-homes"]
92
+ flags = ["-j", "--json"]
93
+ value_flags = [{ names = ["-b", "--by"], pattern = "[a-z]{1,20}" }]
94
+ min_positional = 1
95
+ max_positional = 1
96
+ positional_pattern = "[A-Za-z0-9][A-Za-z0-9._@:+ -]{0,79}"
97
+ help = "a few lines on one group"
98
+
99
+ [[rule]]
100
+ match = ["crowsnest", "questions"]
101
+ argv = ["crowsnest", "questions", "--all-homes"]
102
+ flags = ["-u", "--unanswered", "-j", "--json"]
103
+ help = "what the owner asked sessions in the last two weeks, and the answers"
104
+
105
+ [[rule]]
106
+ match = ["crowsnest", "lineage"]
107
+ argv = ["crowsnest", "lineage", "--all-homes"]
108
+ flags = ["-j", "--json"]
109
+ help = "who started whom (read only: no backfill)"
110
+
111
+ [[rule]]
112
+ match = ["crowsnest", "report"]
113
+ argv = ["crowsnest", "report", "--all-homes"]
114
+ help = "the roster as one self-contained HTML page, on stdout"
115
+
116
+ # --- openloops: what sessions left owed or blocked ------------------------------------
117
+ # Verify predicates are commands taken from issue bodies: a remote request never runs
118
+ # them (--no-verify). The owner's own scheduled `ol owed` does the verified pass.
119
+
120
+ [[rule]]
121
+ match = ["ol"]
122
+ argv = ["ol", "brief"]
123
+ value_flags = [{ names = ["-l", "--limit"], pattern = "[0-9]{1,2}" }]
124
+ help = "what sessions left open (syncs openloops' own store first)"
125
+
126
+ [[rule]]
127
+ match = ["ol", "brief"]
128
+ argv = ["ol", "brief"]
129
+ value_flags = [{ names = ["-l", "--limit"], pattern = "[0-9]{1,2}" }]
130
+ help = "same as bare ol"
131
+
132
+ [[rule]]
133
+ match = ["ol", "owed"]
134
+ argv = ["ol", "owed", "--no-verify"]
135
+ value_flags = [{ names = ["-l", "--limit"], pattern = "[0-9]{1,2}" }]
136
+ help = "open manual-task issues: what the owner owes the agents"
137
+
138
+ [[rule]]
139
+ match = ["ol", "blocked"]
140
+ argv = ["ol", "blocked"]
141
+ value_flags = [{ names = ["-l", "--limit"], pattern = "[0-9]{1,2}" }]
142
+ help = "what repos wait on, and what stopped waiting"
143
+
144
+ [[rule]]
145
+ match = ["ol", "dashboard"]
146
+ argv = ["ol", "dashboard", "--no-verify"]
147
+ help = "all three openloops answers as one HTML page, on stdout"
148
+
149
+ # --- the snapshot: answers already on disk ---------------------------------------------
150
+
151
+ [[rule]]
152
+ match = ["snapshot"]
153
+ kind = "file"
154
+ root = "out"
155
+ help = "list the snapshot files, or print one (fast: no command runs)"
156
+
157
+ # --- dispatch (gated) ------------------------------------------------------------------
158
+
159
+ [[rule]]
160
+ match = ["crowsnest", "spawn"]
161
+ class = "dispatch"
162
+ # pinned: the session asks before it acts, whatever crowsnest's or the account's default is
163
+ argv = ["crowsnest", "spawn", "--model", "sonnet", "--permission-mode", "default"]
164
+ value_flags = [
165
+ { names = ["-c", "--cwd"], path_under_roots = true },
166
+ { names = ["--prompt"], free = true },
167
+ ]
168
+ min_positional = 1
169
+ max_positional = 1
170
+ positional_pattern = "[a-z0-9][a-z0-9-]{1,40}"
171
+ help = "start a named session (sonnet) in a directory under the dispatch roots"
172
+
173
+ # --- what `hatchway snapshot` keeps fresh ----------------------------------------------
174
+
175
+ [[snapshot]]
176
+ request = "crowsnest triage"
177
+ file = "triage.md"
178
+
179
+ [[snapshot]]
180
+ request = "crowsnest --brief"
181
+ file = "roster.txt"
182
+
183
+ [[snapshot]]
184
+ request = "ol owed"
185
+ file = "owed.txt"
186
+
187
+ [[snapshot]]
188
+ request = "ol blocked"
189
+ file = "blocked.txt"
@@ -0,0 +1,38 @@
1
+ ---
2
+ name: hatchway
3
+ description: >-
4
+ Connect an outside agent (a personal assistant on its own cloud VM such as Meta's Muse, another machine's scheduler, a phone shortcut) to the tools on this machine through one confined SSH key: `hatchway authorize` writes a forced-command authorized_keys line, the gate runs only an allowlist kept as a TOML profile, every call is logged, and a snapshot keeps the answers on disk. Use when asked to "let my assistant read my sessions", "give my assistant access to crowsnest", "set up a bridge", "allow an agent to SSH in but only run X", "forced command", "restricted SSH key", "lock down an agent's access", "what did the agent run", "revoke the agent", and to add a rule, a profile or a gated class. Not for exposing tools over MCP or HTTP (a different surface, not yet built).
5
+ ---
6
+
7
+ # hatchway: one confined key for an outside agent
8
+
9
+ The agent gets a key. The key runs `hatchway gate`, nothing else. The gate runs what the profile allows, without a shell, and logs everything. Read `README.md` in the package for the full model; this skill is the procedure.
10
+
11
+ ## Install a connection (idempotent: rerun any step)
12
+
13
+ 1. **Read the profile first**: `hatchway help` (what the agent will be able to run). The bundled `claude-fleet` profile reads crowsnest and openloops; nothing in it kills, reaps, messages or writes into a session. Copy it to `~/.config/hatchway/profiles/<name>.toml` to change it.
14
+ 2. **Tell the gate where the commands live**: sshd gives a forced command a minimal PATH. Put the directories of `crowsnest`, `ol`, `claude`, `gh` (from `which`) in `~/.config/hatchway/config.toml` as `path = [...]`.
15
+ 3. **Prove the gate before any key exists**, with sshd's environment:
16
+ `env -i HOME=$HOME PATH=/usr/bin:/bin SSH_ORIGINAL_COMMAND="crowsnest triage -q" $(which hatchway) gate --agent test`
17
+ and once more with a forbidden request (`cat ~/.ssh/id_ed25519`, expect exit 126). `hatchway check "<request>"` shows the decision without running anything.
18
+ 4. **Authorise the key**: `hatchway authorize "<the agent's whole public key line>" --agent <name>`. It backs up `authorized_keys`, keeps every other line, adds `restrict` and `from=` Tailscale's ranges. `conflict` means that key is already there with other options: show the user both lines, never pass `--replace` on your own.
19
+ 5. **Snapshot timer** (optional, for pulling without waiting): `hatchway snapshot` once, then `hatchway schedule --every 300`.
20
+ 6. **Skills**: `hatchway install-skills --home ~/.claude --home <each other Claude home>`. Report `conflict` rows; never `--force` over a file that is not ours.
21
+
22
+ ## What only the user can do (file it as a `manual-task`, do not hand over steps)
23
+
24
+ - Turn sshd on if it is off (macOS: Remote Login; Linux: the ssh service). Check with `nc -z localhost 22`.
25
+ - Join this machine to the tailnet and approve the agent's device.
26
+ - **The Tailscale policy**, which is the other half of the security model: the agent's device may reach **only TCP port 22** of the machines it serves, and gets **no `ssh` rule**. Tailscale SSH authenticates by tailnet identity and never reads `authorized_keys`, so it would bypass the gate. A grant to paste into the tailnet policy file:
27
+ ```json
28
+ {"grants": [{"src": ["tag:agent"], "dst": ["tag:fleet"], "ip": ["tcp:22"]}]}
29
+ ```
30
+ with the agent's device tagged `tag:agent`, the machines `tag:fleet`, and no `ssh` section naming `tag:agent`.
31
+ - Switching dispatch on: `touch ~/.config/hatchway/allow-dispatch` plus `[dispatch] roots = [...]` in the config. A started session runs with the user's permissions; never switch it on yourself.
32
+
33
+ ## Operating it
34
+
35
+ - `hatchway log -n 50`: what the agent asked, allowed or refused, and the exit status (never the output).
36
+ - `hatchway revoke --agent <name>`: removes the key's line, after a backup.
37
+ - A refused request the agent legitimately needs is a profile change: add a rule with the narrowest flags, a test in `tests/test_policy.py` for the shape and for its abuse, and never a rule whose argv is a shell, an interpreter, `cat`, `rsync`, `scp` or `ssh`.
38
+ - Profile rules list flags exactly. Argparse accepts abbreviations (`--out` as `--ou`), so never allow a flag by prefix, and keep writing flags (`--out`, `--backfill`, `--home`) out of read rules.
@@ -0,0 +1,53 @@
1
+ ---
2
+ name: hatchway-muse
3
+ description: >-
4
+ Recognise when a task would be better handed to a personal Muse agent (Meta's consumer agent with its own cloud VM, reachable by phone and chat) than done in a Claude Code session, pick the integration pattern that fits (hatchway SSH gate, custom MCP connector, Tailscale, a published connector, Poppy, the Gadget SDK, or Meta's Model API for models), and write the exact prompt to paste to the agent. Use when a session meets non-code work (follow-ups, deadlines, email, calendar, bookings, purchases, monitoring prices or listings, waiting on hold, recurring digests), when the user mentions Muse, "my Meta agent", "personal agent", "can my assistant do this", "hand this to my agent", "muse connector", "Meta Model API", "muse-spark", "muse-wonder", or wants their own product reachable by personal agents.
5
+ ---
6
+
7
+ # hatchway-muse: when to hand work to a personal Muse agent, and how
8
+
9
+ Muse here is **the personal agent** (an assistant with its own cloud VM, persistent across days, reachable from the phone). It is not Muse Code (Meta's terminal coding agent) and not the Muse models on Meta's Model API: say which one you mean every time.
10
+
11
+ Facts below were checked on 2026-11-17. The product changes monthly, and several sources are third parties that disagree. Re-check a link before relying on a detail, and say "unverified" when you have not.
12
+
13
+ ## The signals
14
+
15
+ | You see | Pattern |
16
+ |---|---|
17
+ | Work that is not code: chasing a reply, a deadline, a booking, a purchase, monitoring a price or a listing, a recurring digest, waiting on hold | **Hand it off.** A Claude Code session should not spend context on it. |
18
+ | The agent should read this machine's sessions, owed issues, ledgers | **hatchway** (this package): SSH forced command, allowlist, log. See the `hatchway` skill. |
19
+ | A service with a public API, CLI or remote MCP server the agent has no connector for | **Custom connector.** Third-party write-ups say the agent builds an MCP client on its VM and connects over streamable HTTP with a bearer or API-key header [4]; others say the consumer app has no custom MCP setting [10]. Treat it as unverified until it works for this user. |
20
+ | A tool that runs only on the user's LAN or localhost | **Tailscale**: per Tailscale, the agent joins the tailnet as its own device [9]. A localhost MCP server is otherwise unreachable from its VM [4]. Restrict the device to the ports it needs and give it **no Tailscale SSH rule** (that would bypass any forced command). |
21
+ | A Pi, a Linux box or an ESP32 that should be the agent's eyes or hands | **Muse Gadget SDK** [7]: Apache-2.0 with exceptions, presented as "for hackers, just for fun", paired through the app's developer mode. Not a supported product. |
22
+ | The user's own product should be usable by personal agents | **Publish a connector**: a hosted HTTPS MCP server (streamable HTTP, API-key or OAuth), optionally submitted to the Muse Connector Platform for review [3][5][6]; or a Poppy discovery file at `/.well-known/poppy.json` [8] (open protocol, publisher not stated, Meta's involvement unverified). |
23
+ | Code that should call a Muse **model** | **Meta Model API** [1][2]: base URL `https://api.meta.ai/v1`, a `MODEL_API_KEY` bearer token, and it works with the OpenAI and Anthropic SDKs by swapping the base URL and key. Models include `muse-spark-1.3` and `muse-wonder-1.0` (preview). This is models, not the personal agent. In this fleet, route a model call through `aix` rather than a new client. |
24
+ | Messaging the personal agent from Claude Code | There is **no official API**. A third-party MCP server (useapi.net, `muse_chat`) exists [11]. It is unofficial, draws on the account's Muse allowance, and its auth is undocumented. Do not install it without the user's explicit yes. |
25
+
26
+ ## Every proposal ends with these four lines
27
+
28
+ - **What the agent gains**: one line.
29
+ - **What the user must approve**: the access, by name (a key in `authorized_keys`, a tailnet device, a connector's credentials).
30
+ - **The risk**: one line. Custom connectors are not reviewed by Meta [4][6]. Anything the agent reads leaves the machine for its VM.
31
+ - **The prompt to paste to the agent**, in a code block, with placeholders in `[BRACKETS]`. For a custom connector:
32
+
33
+ > Build a custom connector for [SERVICE] using [its MCP server URL / OpenAPI docs]. It uses streamable HTTP and [needs / does not need] auth: ask me for any key through the secure credential prompt, never in chat. List every tool, test each one end to end, then save it as a reusable skill.
34
+
35
+ For hatchway on a machine:
36
+
37
+ > You can reach my machine [TAILNET NAME] over Tailscale as user [USER] with your SSH key. Every command goes through an allowlist: send `help` first and keep to what it lists. Start with `snapshot triage.md` (already on disk, fast), then `crowsnest triage -q` when you need it live. Never ask me to widen the allowlist in chat; tell me which command you needed and why.
38
+
39
+ Never put the user's keys, tailnet names, hostnames or session names in a public file or issue.
40
+
41
+ ## References
42
+
43
+ 1. Meta Model API overview (Muse Code, SDKs, quickstart): https://ai.developer.meta.com/docs/overview/
44
+ 2. Muse Wonder on the Model API: https://dev.meta.ai/docs/muse-wonder
45
+ 3. Muse Connector Platform (Meta; submit a connector for review): https://muse.ai/platform
46
+ 4. Parallel, "Meta Muse custom integrations" (third party): https://parallel.ai/articles/meta-muse-custom-integrations
47
+ 5. Notra, "How to build a Muse connector" (third party): https://www.usenotra.com/blog/how-to-build-a-muse-connector
48
+ 6. Ship with Muse, connectors guide (independent tracker): https://shipwithmuse.live/blog/muse-connectors-guide
49
+ 7. Muse Gadget SDK: https://github.com/facebookincubator/muse-gadget-sdk
50
+ 8. Personal Agent Protocol (Poppy): https://personalagentprotocol.org
51
+ 9. Tailscale, Muse on a tailnet: https://tailscale.com/blog/meta-muse-ai-agent-tailscale
52
+ 10. Hjarni, Muse and MCP (says no custom MCP in the app): https://hjarni.com/docs/muse
53
+ 11. useapi.net Muse MCP server, `muse_chat` (unofficial): https://glama.ai/mcp/connectors/net.useapi/muse/tools/muse_chat