werkregie/doc/satellite-inventory.md

Satellite Inventory

What an account with coding agents needs, as found on think (Ubuntu 24.04) on 2026-10-13. It is the input for the profile of a satellite, #sat in werkregie.werkbaum. Secrets appear by name only.

Setups

A satellite is an account in which agents work; Werkregie sets it up and reads its agents. The setup differs from case to case, and the satellite assumes none of them:

• another Unix account on the user's laptop;
• a local virtual machine;
• a remote virtual machine;
• the agent as a user, or as root in its own virtual machine.

The user's main account keeps the relay with Matrix; it is no satellite. Today think has both in the one account mi. satellite-omarchy.md shows how an Omarchy VM on think became a satellite.

System Packages

Package	Version	Used by
git		everything
bubblewrap	0.9.0	the Codex runner hides the home directory from Codex
curl, jq		scripts, the bootstrap of a satellite

A satellite runs Omarchy Linux, an Arch Linux, so the profile names pacman packages; think shows what is needed, not the target system.

Agents

Component	Installed as	Configuration	Login, per device
Claude Code	native installer, ~/.local/bin/claude, 2.1.280	~/.claude/settings.json, ~/.claude/CLAUDE.md, plugin typesafe	subscription, interactive
Codex CLI, for the Codex runner only	npm under nvm, Node 24.21.0, codex-cli 0.162.1	~/.codex/config.toml (model, trusted projects), ~/.codex/AGENTS.md	subscription, ~/.codex/auth.json
nvm, Node	~/.nvm, default alias	the Codex runner uses the default Node
JDK	SDKMAN, ~/opt/jdk25	Gradle starts on it; builds take Temurin 25 from Foojay (ADR 0001)

The memory of Claude Code lies in ~/.claude/projects/<project>/memory/; a satellite does not get it (#sat.memory).

Gitea Access

• tea 0.16.0 in ~/bin, with the logins javagil (mi), claude-code and hsh-michaelhoennig.
• The global git identity is the human's; a worktree of an agent gets claude-code by ~/.config/ai-coding-agents/git-push-as-claude-code.sh, which reads the token from secrets.env at each push.
• The global credential.helper store keeps the human's credentials in a file; an agent account must not get it.
• SSH keys and ~/.ssh/config belong to the human; an agent pushes over HTTPS with its token.

Secrets

~/.config/ai-coding-agents/secrets.env, mode 0600:

Group	Names	Needed by a satellite
Gitea javagil, agent	GITEA_CLAUDE_CODE_TOKEN	yes
Gitea javagil, reviewer	GITEA_BOT_TOKEN	yes, Codex runner
Gitea javagil, human	GITEA_TOKEN, GITEA_AUTHOR_TOKEN, GITEA_ADMIN_TOKEN, GITEA_SETUP_TOKEN	no
Gitea Hostsharing	HOSTSHARING_GITEA_READ_TOKEN, HOSTSHARING_GITEA_REVIEW_TOKEN	to be decided
Models	OPENROUTER_API_KEY, TYPESAFE_API_KEY	yes
werkrevisor statistics	WERKREVISOR_STATS_SOURCE_TOKEN_*, WERKREVISOR_STATS_READ_TOKEN	to be decided
Taiga	TAIGA_USER, TAIGA_PASSWORD, besides ~/.config/ai-coding-agents/taiga.refresh	no, the server reads Taiga

Besides secrets.env:

• ~/.config/werkregie/relay-token: the access token of the Werkregie server; all relays share it today.
• ~/.config/werkregie/dashboard.env: TYPESAFE_API_KEY and OPENROUTER_API_KEY for the relay.

Services

Unit (systemd user)	Runs	Needs
werkregie-relay.service	~/opt/werkregie-dashboard/bin/werkregie-dashboard relay	runtime bundle, ~/.config/werkregie/dashboard.yml, relay token, dashboard.env
werkrevisor-codex-runner.timer	every 5 min tools/codex-runner in ~/Projekte/werkrevisor	werkrevisor checkout, nvm, Codex login, bubblewrap, secrets.env

dashboard.yml of the relay holds the server URL, the relay name think, Matrix (homeserver, rooms, link) and the environment names of the keys for Jev and the summaries. The Matrix session lies in the state directory of the relay; matrix login and matrix verify are interactive.

Repositories

Checkouts under ~/Projekte: werkregie, werkator, werkbaum, werkcrappit, werkdock, werkjournal, werkprobe, werkrevisor, and the Hostsharing repositories under ~/Projekte/Hostsharing. An agent works in a worktree of its own below .claude/worktrees/.

Interactive Steps

These steps cannot be copied, because the login belongs to the device:

1. Claude Code: subscription login.
2. Codex, where the Codex runner runs: subscription login.
3. Matrix, in the main account only: werkregie-dashboard matrix login, then matrix verify with the recovery key.