Skip to content

docs: install from the 0.1.0 release, and fetch the unit from its tag #85

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
groupsky merged 1 commit into from
Oct 16, 2026
Merged

docs: install from the 0.1.0 release, and fetch the unit from its tag #85

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 40 additions & 14 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,12 @@
nodkey lets an AI coding agent use a secret or an SSH key only after a
person approves that one request on a phone.

**Status:** on 2026-10-15, the code of version 1 is on `main`, and the
test with a real Telegram bot
([#17](https://github.com/code6x/nodkey/issues/17)) is done. There is no
release yet. Try it on a test setup first. See the
**Status:** on 2026-10-15, the code of version 1 is on `main`, the test
with a real Telegram bot
([#17](https://github.com/code6x/nodkey/issues/17)) is done, and the
first release,
[0.1.0](https://github.com/code6x/nodkey/releases/tag/v0.1.0), is out.
Try it on a test setup first. See the
[v1 milestone](https://github.com/code6x/nodkey/milestone/1).

## How it works
Expand Down Expand Up @@ -48,17 +50,31 @@ clipboard, terminals and browser. Keep no SSH key or other way to get
root on the broker host on the agent machine
([docs/setup.md section 1](docs/setup.md#where-you-do-the-setup)).

1. **Install** `nodkey` on both machines. There is no release yet, so
build it from this repository with Go 1.26 or newer, on a trusted
machine, never on the agent machine:
1. **Install** `nodkey` on both machines. Get it on a trusted machine,
never on the agent machine. The easy way is the
[latest release](https://github.com/code6x/nodkey/releases/latest):
download the tarball for the CPU of each machine, such as
`nodkey_0.1.0_linux_amd64.tar.gz` or `nodkey_0.1.0_linux_arm64.tar.gz`,
and `SHA256SUMS`. Check them as
[docs/releasing.md](docs/releasing.md#verify-a-download) says, and
take the file `nodkey` out of the tarball:

```sh
tar -xzf nodkey_0.1.0_linux_amd64.tar.gz nodkey
```

If the two machines have different CPUs, take each file out in a
folder of its own, and copy each to its machine.

Or build it from this repository with Go 1.26 or newer:

```sh
CGO_ENABLED=0 go build -trimpath -o nodkey ./cmd/nodkey
```

Copy the file straight to both machines, not through the agent
machine. On the broker host, `sha256sum nodkey` must print the same
SHA-256 as on the build machine. Install it as root:
Copy the file `nodkey` straight to both machines, not through the
agent machine. On the broker host, `sha256sum nodkey` must print the
same SHA-256 as on the trusted machine. Install it as root:

```sh
install -o root -g root -m 0755 nodkey /usr/local/bin/nodkey
Expand Down Expand Up @@ -136,10 +152,20 @@ root on the broker host on the agent machine
ask = "always"
```

Copy [contrib/systemd/nodkey.service](contrib/systemd/nodkey.service)
to `/etc/systemd/system/`. Keep only the `LoadCredentialEncrypted=`
lines of `broker-tls-key`, `telegram-token` and `bws-token`. Then
start the broker, and read its log:
Take the example unit from the tag of your version, such as
[v0.1.0](https://github.com/code6x/nodkey/blob/refs/tags/v0.1.0/contrib/systemd/nodkey.service),
never through the agent machine
([docs/setup.md section 8](docs/setup.md#8-the-systemd-unit)). After
a build from the source, use the unit in your copy of the repository
instead. For the release 0.1.0:

```sh
curl -fL -o /etc/systemd/system/nodkey.service https://raw.githubusercontent.com/code6x/nodkey/refs/tags/v0.1.0/contrib/systemd/nodkey.service
```

Keep only the `LoadCredentialEncrypted=` lines of `broker-tls-key`,
`telegram-token` and `bws-token`. Then start the broker, and read its
log:

```sh
systemctl daemon-reload
Expand Down
5 changes: 4 additions & 1 deletion SECURITY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,4 +33,7 @@ normal issues.

## Supported versions

There is no release yet. Until 1.0, only the latest release gets fixes.
Until 1.0, only the
[latest release](https://github.com/code6x/nodkey/releases/latest) gets
fixes. To get a fix, upgrade to the newest release
([docs/setup.md section 13](docs/setup.md#a-new-version-of-nodkey)).
55 changes: 39 additions & 16 deletions docs/setup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -100,21 +100,23 @@ section 5, item 8). So:
## 2. Get nodkey

Install the same version of nodkey on the broker host and on each agent
machine, as `/usr/local/bin/nodkey`, owned by root.
machine, as `/usr/local/bin/nodkey`, owned by root. There are two ways
to get it: from a release, or from the source. Use a trusted machine for
both, never an agent machine ([section 1](#where-you-do-the-setup)).

**From a release.** Download the tarball for your machine and
`SHA256SUMS` from the
[release page](https://github.com/code6x/nodkey/releases). Check both,
as [docs/releasing.md](releasing.md#verify-a-download) says. Then:
**From a release.** This is the easier way. Download the tarball for
your machine, such as `nodkey_0.1.0_linux_amd64.tar.gz`
(`nodkey_0.1.0_linux_arm64.tar.gz` on 64-bit ARM), and `SHA256SUMS` from
the [release page](https://github.com/code6x/nodkey/releases). Check
both, as [docs/releasing.md](releasing.md#verify-a-download) says. Then
take the file `nodkey` out of the tarball:

```sh
tar -xzf nodkey_0.1.0_linux_amd64.tar.gz nodkey
install -o root -g root -m 0755 nodkey /usr/local/bin/nodkey
```

**From the source.** There is no release yet on 2026-10-15. Build nodkey
with Go 1.26 or newer, on a trusted machine. Never build it on an agent
machine: the agent could change the build.
**From the source.** Build nodkey with Go 1.26 or newer. Never build it
on an agent machine: the agent could change the build.

```sh
git clone https://github.com/code6x/nodkey.git
Expand All @@ -125,13 +127,14 @@ CGO_ENABLED=0 go build -trimpath -ldflags "-X main.version=$(git rev-parse --sho
The `-ldflags` part is optional. It puts the commit into
`nodkey version` and into the `broker_started` entry of the audit log.

Copy the file straight from the build machine to each machine, never
through an agent machine ([section 1](#where-you-do-the-setup)). On the
broker host, check that it is the same file: `sha256sum nodkey` must
print the same SHA-256 as on the build machine. Then install it with the
`install` command above, and check it:
**Then, for both ways:** copy the file `nodkey` straight from the
trusted machine to each machine, never through an agent machine
([section 1](#where-you-do-the-setup)). On the broker host, check that it
is the same file: `sha256sum nodkey` must print the same SHA-256 as on
the trusted machine. Then install it, and check it:

```sh
install -o root -g root -m 0755 nodkey /usr/local/bin/nodkey
nodkey version
```

Expand Down Expand Up @@ -777,6 +780,18 @@ instead.
Copy the example unit
[contrib/systemd/nodkey.service](../contrib/systemd/nodkey.service), of
the same version as your nodkey, to `/etc/systemd/system/nodkey.service`.
Never copy it through an agent machine: whoever can change the unit can
run a program as root on the broker host. After a build from the source,
the unit is in your copy of the repository. The release tarball does not
hold it. Take it from the tag of your version in the repository, such as
[v0.1.0](https://github.com/code6x/nodkey/blob/refs/tags/v0.1.0/contrib/systemd/nodkey.service),
on the broker host or on the trusted machine. For 0.1.0, on the broker
host:

```sh
curl -fL -o /etc/systemd/system/nodkey.service https://raw.githubusercontent.com/code6x/nodkey/refs/tags/v0.1.0/contrib/systemd/nodkey.service
```

Then change it to fit your setup:

- Keep one `LoadCredentialEncrypted=` line for each credential that you
Expand Down Expand Up @@ -1181,9 +1196,17 @@ cut shows as an anchor whose entry is missing.

1. Read the release notes.
2. Get the new version, and check it ([section 2](#2-get-nodkey)).
3. Compare the example unit of the new version with your unit, and take
3. Get the example unit of the new version from its tag, as in
[section 8](#8-the-systemd-unit), but save it as `nodkey.service`, not
over your unit. After a build from the source, use the unit in your
copy of the repository instead. Compare it with your unit, and take
over the changes:
`diff -u /etc/systemd/system/nodkey.service contrib/systemd/nodkey.service`.

```sh
VERSION=0.1.0 # the new version
curl -fL -o nodkey.service "https://raw.githubusercontent.com/code6x/nodkey/refs/tags/v$VERSION/contrib/systemd/nodkey.service"
diff -u /etc/systemd/system/nodkey.service nodkey.service
```
4. Install it, and restart the broker:

```sh
Expand Down
Loading