hatchway 0.0.2__tar.gz
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-0.0.2/.github/workflows/ci.yml +24 -0
- hatchway-0.0.2/.gitignore +132 -0
- hatchway-0.0.2/LICENSE +21 -0
- hatchway-0.0.2/PKG-INFO +91 -0
- hatchway-0.0.2/README.md +66 -0
- hatchway-0.0.2/hatchway/__init__.py +38 -0
- hatchway-0.0.2/hatchway/__main__.py +185 -0
- hatchway-0.0.2/hatchway/config.py +117 -0
- hatchway-0.0.2/hatchway/data/profiles/claude-fleet.toml +189 -0
- hatchway-0.0.2/hatchway/data/skills/hatchway/SKILL.md +38 -0
- hatchway-0.0.2/hatchway/data/skills/hatchway-muse/SKILL.md +53 -0
- hatchway-0.0.2/hatchway/gate.py +206 -0
- hatchway-0.0.2/hatchway/install.py +375 -0
- hatchway-0.0.2/hatchway/policy.py +290 -0
- hatchway-0.0.2/hatchway/snapshot.py +124 -0
- hatchway-0.0.2/pyproject.toml +60 -0
- hatchway-0.0.2/tests/test_gate_install.py +143 -0
- hatchway-0.0.2/tests/test_policy.py +145 -0
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
# wads CI — calls the reusable workflow hosted in i2mint/wads.
|
|
2
|
+
#
|
|
3
|
+
# All configuration comes from this repo's pyproject.toml [tool.wads.ci.*].
|
|
4
|
+
# To customize the workflow itself (rare), replace this file with the
|
|
5
|
+
# full inline template `wads/data/github_ci_uv.yml` from i2mint/wads.
|
|
6
|
+
#
|
|
7
|
+
# Permissions: the reusable workflow needs `contents: write` (version-bump
|
|
8
|
+
# push-back, gh-pages branch push) and `pages: write` (Pages REST config).
|
|
9
|
+
# Both default to read-only on personal-account callers, so they are granted
|
|
10
|
+
# explicitly here.
|
|
11
|
+
name: Continuous Integration
|
|
12
|
+
on: [push, pull_request]
|
|
13
|
+
jobs:
|
|
14
|
+
ci:
|
|
15
|
+
uses: i2mint/wads/.github/workflows/uv-ci.yml@master
|
|
16
|
+
permissions:
|
|
17
|
+
contents: write
|
|
18
|
+
pages: write
|
|
19
|
+
# Explicit pass-through (not `secrets: inherit`, which does not reliably
|
|
20
|
+
# propagate caller-repo secrets to a reusable workflow owned by a different
|
|
21
|
+
# account). hatchway never reaches the network itself, so
|
|
22
|
+
# PYPI_PASSWORD is the only secret it needs.
|
|
23
|
+
secrets:
|
|
24
|
+
PYPI_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
|
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
docs/_build/
|
|
2
|
+
wads_configs.json
|
|
3
|
+
data/wads_configs.json
|
|
4
|
+
wads/data/wads_configs.json
|
|
5
|
+
|
|
6
|
+
# Byte-compiled / optimized / DLL files
|
|
7
|
+
__pycache__/
|
|
8
|
+
*.py[cod]
|
|
9
|
+
*$py.class
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
.DS_Store
|
|
13
|
+
# C extensions
|
|
14
|
+
*.so
|
|
15
|
+
|
|
16
|
+
# Distribution / packaging
|
|
17
|
+
.Python
|
|
18
|
+
build/
|
|
19
|
+
develop-eggs/
|
|
20
|
+
dist/
|
|
21
|
+
downloads/
|
|
22
|
+
eggs/
|
|
23
|
+
.eggs/
|
|
24
|
+
lib/
|
|
25
|
+
lib64/
|
|
26
|
+
parts/
|
|
27
|
+
sdist/
|
|
28
|
+
var/
|
|
29
|
+
wheels/
|
|
30
|
+
*.egg-info/
|
|
31
|
+
.installed.cfg
|
|
32
|
+
*.egg
|
|
33
|
+
MANIFEST
|
|
34
|
+
_build
|
|
35
|
+
|
|
36
|
+
# PyInstaller
|
|
37
|
+
# Usually these files are written by a python script from a template
|
|
38
|
+
# before PyInstaller builds the exe, so as to inject date/other infos into it.
|
|
39
|
+
*.manifest
|
|
40
|
+
*.spec
|
|
41
|
+
|
|
42
|
+
# Installer logs
|
|
43
|
+
pip-log.txt
|
|
44
|
+
pip-delete-this-directory.txt
|
|
45
|
+
|
|
46
|
+
# Unit test / coverage reports
|
|
47
|
+
htmlcov/
|
|
48
|
+
.tox/
|
|
49
|
+
.coverage
|
|
50
|
+
.coverage.*
|
|
51
|
+
.cache
|
|
52
|
+
nosetests.xml
|
|
53
|
+
coverage.xml
|
|
54
|
+
*.cover
|
|
55
|
+
.hypothesis/
|
|
56
|
+
.pytest_cache/
|
|
57
|
+
|
|
58
|
+
# Translations
|
|
59
|
+
*.mo
|
|
60
|
+
*.pot
|
|
61
|
+
|
|
62
|
+
# Django stuff:
|
|
63
|
+
*.log
|
|
64
|
+
local_settings.py
|
|
65
|
+
db.sqlite3
|
|
66
|
+
|
|
67
|
+
# Flask stuff:
|
|
68
|
+
instance/
|
|
69
|
+
.webassets-cache
|
|
70
|
+
|
|
71
|
+
# Scrapy stuff:
|
|
72
|
+
.scrapy
|
|
73
|
+
|
|
74
|
+
# Sphinx documentation
|
|
75
|
+
docs/_build/
|
|
76
|
+
|
|
77
|
+
# PyBuilder
|
|
78
|
+
target/
|
|
79
|
+
|
|
80
|
+
# Jupyter Notebook
|
|
81
|
+
.ipynb_checkpoints
|
|
82
|
+
|
|
83
|
+
# pyenv
|
|
84
|
+
.python-version
|
|
85
|
+
|
|
86
|
+
# celery beat schedule file
|
|
87
|
+
celerybeat-schedule
|
|
88
|
+
|
|
89
|
+
# SageMath parsed files
|
|
90
|
+
*.sage.py
|
|
91
|
+
|
|
92
|
+
# Environments
|
|
93
|
+
.env
|
|
94
|
+
.venv
|
|
95
|
+
env/
|
|
96
|
+
venv/
|
|
97
|
+
ENV/
|
|
98
|
+
env.bak/
|
|
99
|
+
venv.bak/
|
|
100
|
+
|
|
101
|
+
# Spyder project settings
|
|
102
|
+
.spyderproject
|
|
103
|
+
.spyproject
|
|
104
|
+
|
|
105
|
+
# Rope project settings
|
|
106
|
+
.ropeproject
|
|
107
|
+
|
|
108
|
+
# mkdocs documentation
|
|
109
|
+
/site
|
|
110
|
+
|
|
111
|
+
# mypy
|
|
112
|
+
.mypy_cache/
|
|
113
|
+
|
|
114
|
+
# PyCharm
|
|
115
|
+
.idea
|
|
116
|
+
|
|
117
|
+
# Ruff
|
|
118
|
+
.ruff_cache/
|
|
119
|
+
|
|
120
|
+
# VS Code
|
|
121
|
+
.vscode/
|
|
122
|
+
|
|
123
|
+
# Temporary test outputs
|
|
124
|
+
batch_results.json
|
|
125
|
+
*.tmp
|
|
126
|
+
tmp/
|
|
127
|
+
temp/
|
|
128
|
+
# Local session handoffs (not for commit)
|
|
129
|
+
.claude/handoffs/
|
|
130
|
+
|
|
131
|
+
# Session worktrees created by `claude --worktree` (not for commit)
|
|
132
|
+
.claude/worktrees/
|
hatchway-0.0.2/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Thor Whalen
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
hatchway-0.0.2/PKG-INFO
ADDED
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: hatchway
|
|
3
|
+
Version: 0.0.2
|
|
4
|
+
Summary: A narrow, logged opening through which an outside agent reaches your tools: an SSH forced command that runs only an allowlist kept as data
|
|
5
|
+
Project-URL: Homepage, https://github.com/thorwhalen/hatchway
|
|
6
|
+
Project-URL: Repository, https://github.com/thorwhalen/hatchway
|
|
7
|
+
Project-URL: Issues, https://github.com/thorwhalen/hatchway/issues
|
|
8
|
+
Author: Thor Whalen
|
|
9
|
+
License-Expression: MIT
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Keywords: agents,allowlist,claude-code,forced-command,gateway,mcp,ssh
|
|
12
|
+
Classifier: Development Status :: 3 - Alpha
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: Operating System :: POSIX
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Topic :: Security
|
|
19
|
+
Classifier: Topic :: Utilities
|
|
20
|
+
Requires-Python: >=3.11
|
|
21
|
+
Provides-Extra: dev
|
|
22
|
+
Requires-Dist: pytest>=7.0; extra == 'dev'
|
|
23
|
+
Requires-Dist: ruff>=0.1.0; extra == 'dev'
|
|
24
|
+
Description-Content-Type: text/markdown
|
|
25
|
+
|
|
26
|
+
# hatchway
|
|
27
|
+
|
|
28
|
+
A narrow, logged opening through which an outside agent reaches your tools.
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
pip install hatchway
|
|
32
|
+
hatchway authorize "ssh-ed25519 AAAA... my-agent" --agent assistant # one confined key
|
|
33
|
+
hatchway check "crowsnest triage" # what the gate would do
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
An agent that lives somewhere else (a personal assistant on its own cloud VM, another machine's scheduler, a phone shortcut) gets one SSH key. That key can do exactly one thing: run `hatchway gate`, which reads the requested command line, checks it against a **profile** (an allowlist kept as a TOML file), logs the call, and runs the allowed command directly, never through a shell. Anything not in the profile is refused with a reason.
|
|
37
|
+
|
|
38
|
+
It is the "reach in" half of connecting an outside agent to the tools on your machine, with no new server, no open port and no new dependency: OpenSSH already has forced commands, and hatchway is the policy and the bookkeeping around one.
|
|
39
|
+
|
|
40
|
+
## What you get
|
|
41
|
+
|
|
42
|
+
- **An allowlist as data.** A rule names the words the agent sends, the command that actually runs (with fixed arguments the agent cannot remove, such as `--no-verify`), and exactly which flags and names it may add. Names are checked against a pattern and passed after `--`, so they can never be read as options. Shell characters are refused outright.
|
|
43
|
+
- **A confined key.** `hatchway authorize` writes one `authorized_keys` line with `command="hatchway gate --agent NAME"`, `restrict` (no shell, no port, agent or X11 forwarding, no pty), and by default `from="100.64.0.0/10,fd7a:115c:a1e0::/48"`, so the key works only from a Tailscale tailnet even if sshd is reachable elsewhere. It keeps every other line, backs the file up first, and is idempotent. `hatchway revoke --agent NAME` takes it out.
|
|
44
|
+
- **A log of every call** in `~/.local/share/hatchway/calls.jsonl`: when, which agent, from where, what was asked, allowed or refused, exit status. Never the output. `hatchway log` shows the tail.
|
|
45
|
+
- **Gated classes.** A rule can belong to a class that stays off until a flag file exists. The bundled profile's `dispatch` class (starting a Claude Code session) needs both `~/.config/hatchway/allow-dispatch` and a list of directories it may start sessions in.
|
|
46
|
+
- **A snapshot for pulling instead of waiting.** `hatchway snapshot` runs the profile's snapshot requests (through the same allowlist) and writes the answers atomically to `~/.local/share/hatchway/out/`, with an `index.json`. The agent reads them through the gate (`snapshot triage.md`) without waiting for anything to run. `hatchway schedule --every 300` keeps them fresh with launchd (macOS) or a systemd user timer (Linux).
|
|
47
|
+
- **Skills for the agents that set it up.** `hatchway install-skills` links the bundled skills into one or more Claude Code homes.
|
|
48
|
+
|
|
49
|
+
## The bundled profile: `claude-fleet`
|
|
50
|
+
|
|
51
|
+
For a machine running Claude Code sessions watched by [crowsnest](https://github.com/thorwhalen/crowsnest) (live sessions) and [openloops](https://github.com/thorwhalen/openloops) (what sessions left owed or blocked). `hatchway help` prints it, and it is what the agent gets when it sends `help`:
|
|
52
|
+
|
|
53
|
+
| Request | Runs |
|
|
54
|
+
|---|---|
|
|
55
|
+
| `crowsnest [--brief\|--json]` | the roster across every configured Claude home |
|
|
56
|
+
| `crowsnest triage [-q] [--json]` | what needs you, what is safe to close, what is working |
|
|
57
|
+
| `crowsnest show\|turns\|recap\|brief NAME` | one session (show and turns quote its transcript) |
|
|
58
|
+
| `crowsnest ledger [NAME...]`, `groups`, `synopsis GROUP`, `questions`, `lineage`, `report` | the rest of crowsnest's read side |
|
|
59
|
+
| `ol`, `ol owed`, `ol blocked`, `ol dashboard` | openloops, always with `--no-verify` (verify predicates are commands taken from issue bodies, and a remote request never runs them) |
|
|
60
|
+
| `snapshot [FILE]` | list or print the snapshot files |
|
|
61
|
+
| `crowsnest spawn NAME --cwd DIR --prompt TEXT` | **gated**: starts a session on `sonnet`, in a directory under the dispatch roots |
|
|
62
|
+
|
|
63
|
+
Nothing in it kills, reaps, messages or writes into a running session.
|
|
64
|
+
|
|
65
|
+
To change it for one machine, copy `hatchway/data/profiles/claude-fleet.toml` to `~/.config/hatchway/profiles/<name>.toml`, edit it, and set `profile = "<name>"` in `~/.config/hatchway/config.toml` (or pass `--profile <name>` to `authorize`, which puts it in that key's forced command).
|
|
66
|
+
|
|
67
|
+
## Configuration
|
|
68
|
+
|
|
69
|
+
`~/.config/hatchway/config.toml`, every key optional:
|
|
70
|
+
|
|
71
|
+
```toml
|
|
72
|
+
profile = "claude-fleet"
|
|
73
|
+
path = ["~/.local/bin"] # where the commands live (sshd's PATH is minimal)
|
|
74
|
+
timeout = 120
|
|
75
|
+
[roots] # extra directories file rules may serve, by name
|
|
76
|
+
[dispatch]
|
|
77
|
+
roots = ["~/projects"] # where a gated spawn may start a session
|
|
78
|
+
[snapshot]
|
|
79
|
+
to = "" # optional private copy: a local dir or host:path
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
## The security model, in one paragraph
|
|
83
|
+
|
|
84
|
+
What the key can do is the profile, so read it before you authorise a key. Read commands still send what they read to wherever the agent runs: `crowsnest show` quotes your sessions' transcripts, so authorise only an agent you would show them to. Keep the `from=` restriction. If the agent joins your Tailscale tailnet, give it a policy that allows **only TCP port 22** to the machines it serves and **no Tailscale SSH rule**: Tailscale SSH authenticates by tailnet identity and never reads `authorized_keys`, so it would bypass the gate entirely. `100.64.0.0/10` is also ordinary carrier-grade NAT space, so once you know the agent's own tailnet address, narrow `--from` to it (`--from 100.x.y.z/32`). Leave dispatch off until you have watched the log for a while: a session it starts runs code as you. The bundled rule pins `--model sonnet` and `--permission-mode default` (the session asks before acting), refuses a prompt that starts with `-`, and starts sessions only under the directories you list.
|
|
85
|
+
|
|
86
|
+
Also built in: the commands run with an allowlisted environment (nothing the connecting client can set reaches them beyond `LANG`), in their own process group so a timeout stops their children too, one call at a time per agent (a concurrent call is refused with exit 75), and every allowed call is logged before it runs, so a dropped connection still leaves its line.
|
|
87
|
+
|
|
88
|
+
## Agents
|
|
89
|
+
|
|
90
|
+
- `hatchway` skill: install and verify a connection for an outside agent on this machine (the steps, the checks, the Tailscale policy).
|
|
91
|
+
- `hatchway-muse` skill: when a task would be better handed to a personal Muse agent (Meta), which integration pattern fits, and the exact prompt to give it.
|
hatchway-0.0.2/README.md
ADDED
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
# hatchway
|
|
2
|
+
|
|
3
|
+
A narrow, logged opening through which an outside agent reaches your tools.
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
pip install hatchway
|
|
7
|
+
hatchway authorize "ssh-ed25519 AAAA... my-agent" --agent assistant # one confined key
|
|
8
|
+
hatchway check "crowsnest triage" # what the gate would do
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
An agent that lives somewhere else (a personal assistant on its own cloud VM, another machine's scheduler, a phone shortcut) gets one SSH key. That key can do exactly one thing: run `hatchway gate`, which reads the requested command line, checks it against a **profile** (an allowlist kept as a TOML file), logs the call, and runs the allowed command directly, never through a shell. Anything not in the profile is refused with a reason.
|
|
12
|
+
|
|
13
|
+
It is the "reach in" half of connecting an outside agent to the tools on your machine, with no new server, no open port and no new dependency: OpenSSH already has forced commands, and hatchway is the policy and the bookkeeping around one.
|
|
14
|
+
|
|
15
|
+
## What you get
|
|
16
|
+
|
|
17
|
+
- **An allowlist as data.** A rule names the words the agent sends, the command that actually runs (with fixed arguments the agent cannot remove, such as `--no-verify`), and exactly which flags and names it may add. Names are checked against a pattern and passed after `--`, so they can never be read as options. Shell characters are refused outright.
|
|
18
|
+
- **A confined key.** `hatchway authorize` writes one `authorized_keys` line with `command="hatchway gate --agent NAME"`, `restrict` (no shell, no port, agent or X11 forwarding, no pty), and by default `from="100.64.0.0/10,fd7a:115c:a1e0::/48"`, so the key works only from a Tailscale tailnet even if sshd is reachable elsewhere. It keeps every other line, backs the file up first, and is idempotent. `hatchway revoke --agent NAME` takes it out.
|
|
19
|
+
- **A log of every call** in `~/.local/share/hatchway/calls.jsonl`: when, which agent, from where, what was asked, allowed or refused, exit status. Never the output. `hatchway log` shows the tail.
|
|
20
|
+
- **Gated classes.** A rule can belong to a class that stays off until a flag file exists. The bundled profile's `dispatch` class (starting a Claude Code session) needs both `~/.config/hatchway/allow-dispatch` and a list of directories it may start sessions in.
|
|
21
|
+
- **A snapshot for pulling instead of waiting.** `hatchway snapshot` runs the profile's snapshot requests (through the same allowlist) and writes the answers atomically to `~/.local/share/hatchway/out/`, with an `index.json`. The agent reads them through the gate (`snapshot triage.md`) without waiting for anything to run. `hatchway schedule --every 300` keeps them fresh with launchd (macOS) or a systemd user timer (Linux).
|
|
22
|
+
- **Skills for the agents that set it up.** `hatchway install-skills` links the bundled skills into one or more Claude Code homes.
|
|
23
|
+
|
|
24
|
+
## The bundled profile: `claude-fleet`
|
|
25
|
+
|
|
26
|
+
For a machine running Claude Code sessions watched by [crowsnest](https://github.com/thorwhalen/crowsnest) (live sessions) and [openloops](https://github.com/thorwhalen/openloops) (what sessions left owed or blocked). `hatchway help` prints it, and it is what the agent gets when it sends `help`:
|
|
27
|
+
|
|
28
|
+
| Request | Runs |
|
|
29
|
+
|---|---|
|
|
30
|
+
| `crowsnest [--brief\|--json]` | the roster across every configured Claude home |
|
|
31
|
+
| `crowsnest triage [-q] [--json]` | what needs you, what is safe to close, what is working |
|
|
32
|
+
| `crowsnest show\|turns\|recap\|brief NAME` | one session (show and turns quote its transcript) |
|
|
33
|
+
| `crowsnest ledger [NAME...]`, `groups`, `synopsis GROUP`, `questions`, `lineage`, `report` | the rest of crowsnest's read side |
|
|
34
|
+
| `ol`, `ol owed`, `ol blocked`, `ol dashboard` | openloops, always with `--no-verify` (verify predicates are commands taken from issue bodies, and a remote request never runs them) |
|
|
35
|
+
| `snapshot [FILE]` | list or print the snapshot files |
|
|
36
|
+
| `crowsnest spawn NAME --cwd DIR --prompt TEXT` | **gated**: starts a session on `sonnet`, in a directory under the dispatch roots |
|
|
37
|
+
|
|
38
|
+
Nothing in it kills, reaps, messages or writes into a running session.
|
|
39
|
+
|
|
40
|
+
To change it for one machine, copy `hatchway/data/profiles/claude-fleet.toml` to `~/.config/hatchway/profiles/<name>.toml`, edit it, and set `profile = "<name>"` in `~/.config/hatchway/config.toml` (or pass `--profile <name>` to `authorize`, which puts it in that key's forced command).
|
|
41
|
+
|
|
42
|
+
## Configuration
|
|
43
|
+
|
|
44
|
+
`~/.config/hatchway/config.toml`, every key optional:
|
|
45
|
+
|
|
46
|
+
```toml
|
|
47
|
+
profile = "claude-fleet"
|
|
48
|
+
path = ["~/.local/bin"] # where the commands live (sshd's PATH is minimal)
|
|
49
|
+
timeout = 120
|
|
50
|
+
[roots] # extra directories file rules may serve, by name
|
|
51
|
+
[dispatch]
|
|
52
|
+
roots = ["~/projects"] # where a gated spawn may start a session
|
|
53
|
+
[snapshot]
|
|
54
|
+
to = "" # optional private copy: a local dir or host:path
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
## The security model, in one paragraph
|
|
58
|
+
|
|
59
|
+
What the key can do is the profile, so read it before you authorise a key. Read commands still send what they read to wherever the agent runs: `crowsnest show` quotes your sessions' transcripts, so authorise only an agent you would show them to. Keep the `from=` restriction. If the agent joins your Tailscale tailnet, give it a policy that allows **only TCP port 22** to the machines it serves and **no Tailscale SSH rule**: Tailscale SSH authenticates by tailnet identity and never reads `authorized_keys`, so it would bypass the gate entirely. `100.64.0.0/10` is also ordinary carrier-grade NAT space, so once you know the agent's own tailnet address, narrow `--from` to it (`--from 100.x.y.z/32`). Leave dispatch off until you have watched the log for a while: a session it starts runs code as you. The bundled rule pins `--model sonnet` and `--permission-mode default` (the session asks before acting), refuses a prompt that starts with `-`, and starts sessions only under the directories you list.
|
|
60
|
+
|
|
61
|
+
Also built in: the commands run with an allowlisted environment (nothing the connecting client can set reaches them beyond `LANG`), in their own process group so a timeout stops their children too, one call at a time per agent (a concurrent call is refused with exit 75), and every allowed call is logged before it runs, so a dropped connection still leaves its line.
|
|
62
|
+
|
|
63
|
+
## Agents
|
|
64
|
+
|
|
65
|
+
- `hatchway` skill: install and verify a connection for an outside agent on this machine (the steps, the checks, the Tailscale policy).
|
|
66
|
+
- `hatchway-muse` skill: when a task would be better handed to a personal Muse agent (Meta), which integration pattern fits, and the exact prompt to give it.
|
|
@@ -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
|
+
]
|
|
@@ -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())
|