Map: Rex server on saraksh #1

New issue

Open

opened 2026-10-31 13:08:46 +00:00 by mikluko · 0 comments

mikluko commented

2026-10-31 13:08:46 +00:00

Owner

Destination

Rex server runs on saraksh as a single-user workstation, reachable from my devices over the tailnet.

Notes

The map executes, not only decides: wayfinder:task tickets are done within it.
The image and chart live here; the deployment lands in saraksh/kube as a Flux HelmRelease.
Cluster secrets (the Tailscale join key) live in OpenBao under kv/k8s/saraksh/<namespace>/<name> and reach the pod through ExternalSecrets.
Skills: secret-handoff before bao, kubernetes before the cluster, changelog for releases of this image.
Tickets link to this map with a Map: line in the body; blocking is Forgejo dependencies.

Settled while charting:

Cluster: saraksh, single user, an always-on remote Rex host.
Architecture: the image becomes multi-arch (amd64 + arm64).
Persistence: hostPath /srv/rex on bulgakov at /var/lib/rex for Rex state and home.
Packaging: Rex and Claude Code are preinstalled in the image at versions pinned in this repo; no install at pod start, no overlays. The Rex apt repo is public, so no credential.
Upgrades: the daily pin job watches the Debian snapshot, Rex (channel input, default snapshot) and Claude Code (channel input, default stable); all bumps in one commit and one CHANGELOG entry via actions/changelog append, released by its release as a MINOR.
Delivery: a Helm chart in this repo, published as OCI next to the image; saraksh/kube holds a Flux HelmRelease.
Claude Code on saraksh: logged in interactively in a Rex terminal; credentials stay in the home on /srv/rex.

Decisions so far

Can Rex's HTTP listener sit behind an OIDC Ingress?: no; Rex has no token or OIDC auth on any listener, only Tailscale identity or unix peer; exposure is the tailnet
Pod shape: namespace, pool, sandbox, egress: agents/rex on bulgakov (amd64), hostPath /srv/rex, non-root read-only, open egress minus cluster (all capabilities dropped; the overlay amendment was withdrawn with the startup install)
Image toolchain for agents in Rex terminals: Debian base, multi-arch; Rex and Claude Code later pinned into the image instead of installed at startup (agent tooling since moved out of scope)
Prototype: startup install through a shared overlay: worked on bulgakov with hostUsers: false, CAP_SYS_ADMIN, AppArmor unconfined and userxattr overlays; superseded by pinning into the image, only the fixed rex uid survives
Exposure: joining the tailnet: Rex's built-in node on my Tailscale tailnet, hostname kuberex (TS_HOSTNAME), untagged, one-time join key as a secret file, state on /srv/rex, key expiry off
Image: Debian base, multi-arch, Rex and Claude Code pinned in the image: 0.3.0 published for amd64 and arm64; Rex and Claude Code pinned as Dockerfile ARGs; non-root, no capabilities, read-only root with /run/rex and /var/lib/rex writable
Helm chart for kuberex: oci://sarak.sh/mikluko/charts/kuberex, released with the image at its version; one plain pod, stateVolume for /var/lib/rex, optional Cilium egress policy
Deploy kuberex on saraksh via Flux HelmRelease: HelmRelease rex in agents on bulgakov, /srv/rex a ZFS dataset owned 999:999; kuberex is on the tailnet; the chart follows 0.x, so releases roll out by themselves

Not yet specified

Backups of /srv/rex on bulgakov.
What happens to the published sarak.sh/mikluko/machine-rex image once kuberex ships.

Out of scope

Multi-user or shared server.
Write access to clusters from the pod.
Shared packaging with the progressor agent image.
Agent tooling and credentials in Rex terminals (baox, bao, gh, kubectl, aws, credential helpers, Claude Code managed settings, forgejo-mcp): a separate effort for secret management inside the pod.
OpenBao: identity agent-rex: agent identity belongs to that separate effort; entity agent-rex and role rex already exist, the Forgejo sub rule was never added.

## Destination Rex server runs on `saraksh` as a single-user workstation, reachable from my devices over the tailnet. ## Notes - The map executes, not only decides: `wayfinder:task` tickets are done within it. - The image and chart live here; the deployment lands in `saraksh/kube` as a Flux HelmRelease. - Cluster secrets (the Tailscale join key) live in OpenBao under `kv/k8s/saraksh/<namespace>/<name>` and reach the pod through ExternalSecrets. - Skills: `secret-handoff` before `bao`, `kubernetes` before the cluster, `changelog` for releases of this image. - Tickets link to this map with a `Map:` line in the body; blocking is Forgejo dependencies. Settled while charting: - Cluster: `saraksh`, single user, an always-on remote Rex host. - Architecture: the image becomes multi-arch (amd64 + arm64). - Persistence: hostPath `/srv/rex` on `bulgakov` at `/var/lib/rex` for Rex state and home. - Packaging: Rex and Claude Code are preinstalled in the image at versions pinned in this repo; no install at pod start, no overlays. The Rex apt repo is public, so no credential. - Upgrades: the daily `pin` job watches the Debian snapshot, Rex (channel input, default `snapshot`) and Claude Code (channel input, default `stable`); all bumps in one commit and one CHANGELOG entry via `actions/changelog` `append`, released by its `release` as a MINOR. - Delivery: a Helm chart in this repo, published as OCI next to the image; `saraksh/kube` holds a Flux HelmRelease. - Claude Code on `saraksh`: logged in interactively in a Rex terminal; credentials stay in the home on `/srv/rex`. ## Decisions so far - [Can Rex's HTTP listener sit behind an OIDC Ingress?](https://sarak.sh/mikluko/kuberex/issues/2): no; Rex has no token or OIDC auth on any listener, only Tailscale identity or unix peer; exposure is the tailnet - [Pod shape: namespace, pool, sandbox, egress](https://sarak.sh/mikluko/kuberex/issues/4): `agents`/`rex` on `bulgakov` (amd64), hostPath `/srv/rex`, non-root read-only, open egress minus cluster (all capabilities dropped; the overlay amendment was withdrawn with the startup install) - [Image toolchain for agents in Rex terminals](https://sarak.sh/mikluko/kuberex/issues/5): Debian base, multi-arch; Rex and Claude Code later pinned into the image instead of installed at startup (agent tooling since moved out of scope) - [Prototype: startup install through a shared overlay](https://sarak.sh/mikluko/kuberex/issues/10): worked on `bulgakov` with `hostUsers: false`, `CAP_SYS_ADMIN`, AppArmor unconfined and `userxattr` overlays; superseded by pinning into the image, only the fixed `rex` uid survives - [Exposure: joining the tailnet](https://sarak.sh/mikluko/kuberex/issues/3): Rex's built-in node on my Tailscale tailnet, hostname `kuberex` (`TS_HOSTNAME`), untagged, one-time join key as a secret file, state on `/srv/rex`, key expiry off - [Image: Debian base, multi-arch, Rex and Claude Code pinned in the image](https://sarak.sh/mikluko/kuberex/issues/7): 0.3.0 published for amd64 and arm64; Rex and Claude Code pinned as Dockerfile ARGs; non-root, no capabilities, read-only root with `/run/rex` and `/var/lib/rex` writable - [Helm chart for kuberex](https://sarak.sh/mikluko/kuberex/issues/12): `oci://sarak.sh/mikluko/charts/kuberex`, released with the image at its version; one plain pod, `stateVolume` for `/var/lib/rex`, optional Cilium egress policy - [Deploy kuberex on saraksh via Flux HelmRelease](https://sarak.sh/mikluko/kuberex/issues/8): HelmRelease `rex` in `agents` on `bulgakov`, `/srv/rex` a ZFS dataset owned 999:999; `kuberex` is on the tailnet; the chart follows `0.x`, so releases roll out by themselves ## Not yet specified - Backups of `/srv/rex` on `bulgakov`. - What happens to the published `sarak.sh/mikluko/machine-rex` image once `kuberex` ships. ## Out of scope - Multi-user or shared server. - Write access to clusters from the pod. - Shared packaging with the progressor agent image. - Agent tooling and credentials in Rex terminals (`baox`, `bao`, `gh`, `kubectl`, `aws`, credential helpers, Claude Code managed settings, `forgejo-mcp`): a separate effort for secret management inside the pod. - [OpenBao: identity agent-rex](https://sarak.sh/mikluko/kuberex/issues/6): agent identity belongs to that separate effort; entity `agent-rex` and role `rex` already exist, the Forgejo `sub` rule was never added.

mikluko referenced this issue

2026-10-31 13:09:02 +00:00

Can Rex's HTTP listener sit behind an OIDC Ingress? #2

mikluko referenced this issue

2026-10-31 13:09:02 +00:00

Exposure: joining the tailnet #3

mikluko referenced this issue

2026-10-31 13:09:03 +00:00

Pod shape: namespace, pool, sandbox, egress #4

mikluko referenced this issue

2026-10-31 13:09:03 +00:00

Image toolchain for agents in Rex terminals #5