Josui, Claude Code run as a crunchtools autonomous agent: its deployment (the
quadlets in deploy/), the host tools beside it (tools/) and its
constitution. This repo builds no image. Josui and every seat run
quay.io/crunchtools/developer,
whose image is tooling only; who the agent is and what it may touch are
mounted in at run time. Until 1.0.0 this repo built quay.io/crunchtools/josui;
that image is no longer built.
The operator reaches it over Remote Control from claude.ai/code or the phone app. Nothing listens for inbound connections — the only ssh in the image is a client, for the fallback.
| Mount | Container path | What it is |
|---|---|---|
| state | /home/podman |
Claude login, sessions, git identity. The only writable home. |
| ssh | JOSUI_SSH_DIR, default /etc/josui/ssh (read-only) |
A private key, config and known_hosts for the fallback. Absent on a copy run elsewhere, and then there is no fallback. |
| identity | /etc/josui (read-only) |
CLAUDE.md, settings.json. Private; kept in the host's config repo. Hooks here are ignored: only the image's managed hooks run. |
| skills | /var/lib/josui/josui-skills |
A git checkout of the skills repo, pulled at start. |
| audit | /var/log/josui |
One JSON line per tool call. |
| workspaces | same path as the host | What this copy may work on. One -v line each. |
A copy can touch what is mounted into it and nothing else: no container
socket, no host shell. Dev sites are mounted whole (/srv/<site>), and a site
exposes its own inner loop through files: edit the checkout, touch data/control/<name> to restart a unit inside the site's container, read
data/logs/<name>.log.
The container sits on an internal network with no DNS. Its only peer is the Trentina gateway, by address:
- MCP:
TRENTINA_MCP_URLandTRENTINA_MCP_TOKEN. The gateway is the only remote MCP server managed settings allow (the local one is the Matrix channel), and claude.ai connectors are off. - Claude Code's own HTTPS (inference, Remote Control, login refresh):
HTTPS_PROXYpointing at the gateway's client egress, which tunnels to an allowlist of hosts and to nothing else. No forge host belongs on it. - GitHub: the gateway's GitHub tools for the API, and its git route for clone
and push. With
TRENTINA_GIT_URLset, the entrypoint writes a git config in the state volume (mode 0600) that sendshttps://github.com/to the route with the gateway token, and includes it from the global git config. There is noghand no GitHub credential in the container; the gateway holds the token.
Every tool this agent has arrives through the gateway. So when the gateway is down the agent has no tools at all — not even the systemd tools that would restart it — and the agent cannot report that, because the thing it would report through is the thing that is down. That is the gap this fills, and it is a measured failure, not a hypothetical: a gateway restart leaves every client's MCP session dead while the agent looks healthy from every other angle.
Mount a key, an ssh config and a known_hosts at JOSUI_SSH_DIR (default
/etc/josui/ssh) and the entrypoint copies them to a tmpfs at mode 0600 and
links ~/.ssh there — copied rather than pointed at, because ssh refuses a
private key that anyone else can read and the mode on a bind mount is whichever
one the host set; and to tmpfs, so no key is written to the home volume. There is no sshd in this image;
this is outbound only.
The image supplies the mechanism and nothing else. Which host, which account and which key are in the mount, because they are facts about one deployment:
# /etc/josui/ssh/config
Host gloval
HostName 10.89.13.1 # the host's address on the agent's own bridge
Port 22422
User <the account the key authorizes>
IdentityFile ~/.ssh/id_ed25519
StrictHostKeyChecking yes
UserKnownHostsFile ~/.ssh/known_hosts
An internal network does not route to the host by default, and a host firewall may drop it besides, so the path needs opening on purpose at the deployment — which is the point: the fallback exists where someone decided it should, and nowhere else.
The account the key authorizes is the whole security decision, and this image does not make it. Two shapes, with everything in between:
- A forced-command principal:
restricton the key,command=running a script that validates its own argument, and a sudoers list of the handful of binaries that script calls. No pty, no shell, no verb that writes anything the emergency does not need. Sized to the emergency, not to the agent. - Root, or an account with full sudo. Sized to what the agent actually does on that host, for a deployment where the mediated path cannot carry the work.
What it costs is worth stating plainly, and the cost scales with that choice. Output read over ssh has not been through the gateway's judgement, unlike every MCP tool result, and an ssh session is logged by sshd and the host rather than by the gateway's audit. A forced command narrows what can be done and logs each invocation itself; without one, sshd records that a session opened and which key opened it, and nothing records what was run. An account with sudo rather than root at least puts every privileged command in syslog.
A deployment that takes this on should say so in its constitution, and say which shape it took.
The agent runtime is claude-agent,
installed from its packages: claude-agent (breakers, audit, prompts-off, the
session supervisor), claude-agent-matrix (the text bridge) and
claude-agent-trentina (the crunchtools policy). Every Claude Code session in
the container runs with CLAUDE_AGENT=1, so all of them are counted and logged.
- Circuit breakers:
JOSUI_MAX_TOOL_CALLSper conversation (default 500) andJOSUI_MAX_REPEATidentical calls in a row (default 5). A tripped conversation stays stopped. - Audit: one JSON line per tool call in
/var/log/josui, kept 120 days. - Prompts off: with
JOSUI_ANSWER_PERMISSIONS=1, every permission question is answered except a question to the person and plan approval. - Policy: the gateway is the only MCP server, only managed hooks run,
WebSearchandWebFetchare denied, and Claude Code's file memory stays empty.
The entrypoint hands the JOSUI_* settings to claude-agent under its own
names. See claude-agent's hooks
and policy pages.
With JOSUI_MATRIX_HOMESERVER set, claude-agent run holds a second Claude
Code session beside the Remote Control server, and its Matrix bridge carries
the operator's texts in and each turn's final answer out. On a crunchtools
host the homeserver is the agent's own, and Trentina's RCS bridge puts the
operator's texts there. The session is not on Remote Control: the operator
reaches it by text, and claude.ai shows only the server's sessions.
- Texts come only from
JOSUI_MATRIX_ALLOW, in a one-to-one room. A text sent while a turn runs waits for it to end;/stop [text]interrupts. The phone shows a typing indicator for the length of a turn. - Built-ins by text:
/clear,/compact,/model,/effort,/fast,/goal,/mcp reconnect,/reload-skills,/reload-plugins; each texts back its result. Other/namesrun as skills;!is refused. podman exec -it <service> claude-agent attachshows the session live;--rwto answer its working-directory trust question.- When either Claude process ends, the container ends and the unit restarts both.
See claude-agent's supervisor and Matrix pages.
deploy/dolza/josui.container is the deployment, a copy of the live quadlet,
and deploy/josui.env.example is the env file it reads, with placeholder
values. The real env file lives on srv-secrets.
First start needs one thing done by hand, once, because the login is personal
and Remote Control refuses long-lived tokens.
A container that is already running takes it directly:
podman exec -it <service> claude auth login # claude.ai account; prints a URL, takes a codeA container with no login never stays up long enough for that, which is the case this is needed in. Remote Control exits immediately with "You must be logged in to use Remote Control", the supervisor stops the other process, and the unit restarts the pair thirty seconds later; measured 2026-11-07, under a second from start to exit. Log in from a one-off container on the same state volume instead, with the unit stopped:
systemctl --user stop <service>
podman run --rm -it \
<the unit's user namespace options, if it sets any> \
--network <the unit's network or pod> \
--env-file <the unit's env file> \
-v <the state volume>:/home/podman:Z \
--entrypoint claude quay.io/crunchtools/developer:latest auth login
systemctl --user start <service>Both details matter. The user mapping has to be the unit's, or the login is
written into the state volume owned by a uid the service cannot read. The env
file is there for HTTPS_PROXY: the login talks to Anthropic, and the
container has no other way out.
Without a terminal on the host, claude auth login still needs a pty and a
stdin that stays open to take the code. A fifo opened read-write gives both,
where script alone does not -- it stops forwarding after its stdin first
reports EOF:
# script -c takes one command, so save the `podman run` above as a file.
install -m 755 /dev/stdin /tmp/login.sh <<'SH'
#!/bin/bash
exec podman run --rm -it <the options above> \
--entrypoint claude quay.io/crunchtools/developer:latest auth login
SH
mkfifo /tmp/login.fifo
setsid bash -c 'exec 9<>/tmp/login.fifo; script -qfc /tmp/login.sh /tmp/login.log <&9' &
grep -ao 'https://claude.com/cai/oauth/authorize[^ ]*' /tmp/login.log # open this, approve
printf '%s\n' '<the code>' > /tmp/login.fifoThen restart the service. A new working directory also needs its trust
question answered once: podman exec -it <service> claude-agent attach --rw.
| Variable | Default | Meaning |
|---|---|---|
TRENTINA_MCP_URL, TRENTINA_MCP_TOKEN |
unset | The gateway. Without both, Josui starts with no MCP server and says so. |
HTTPS_PROXY, NO_PROXY |
unset | Client egress through the gateway. |
TRENTINA_GIT_URL |
unset | The gateway's git route (http://<gateway>:8019/git). Needs TRENTINA_MCP_TOKEN. |
JOSUI_WORKDIR |
~/work |
Where Remote Control sessions start. Not a git checkout unless the Claude GitHub App can see its repository: session creation fails otherwise. |
JOSUI_NAME |
josui |
Session name prefix shown in the app. |
JOSUI_CAPACITY |
2 |
Concurrent sessions. |
JOSUI_PERMISSION_MODE |
acceptEdits |
Claude Code permission mode for new sessions. bypassPermissions asks nothing; hooks and deny rules still apply. The app sets its own mode on a session it opens, which overrides this. See the constitution's human-in-the-loop rule for the hook a deployment that takes that deviation uses there. |
JOSUI_ANSWER_PERMISSIONS |
unset | 1 turns on the prompts-off hook (the constitution's deviation). |
JOSUI_MATRIX_HOMESERVER |
unset | The agent's homeserver (http://<private address>:6167). Set, it turns on the text session. |
JOSUI_MATRIX_TOKEN_FILE |
/etc/josui-matrix/token |
The agent account's access token, in a read-only mount. |
JOSUI_MATRIX_ALLOW |
unset | Comma list of the exact Matrix IDs whose messages reach the session. Empty lets nothing through. |
JOSUI_MAX_TOOL_CALLS, JOSUI_MAX_REPEAT |
500, 5 |
Circuit breakers. |
JOSUI_DEBUG_FILE |
audit dir + /remote-control.log |
Remote Control's --debug-file, emptied at each start. Read it first when a session does not appear. |
JOSUI_MODE |
server |
worker runs one named interactive Claude Code instead of the Remote Control server. Without JOSUI_MATRIX_HOMESERVER it is in tmux session dev (the seats). With it, it is a supervised worker: claude-agent run holds the one conversation, which the Matrix bridge, Remote Control and claude-agent send all reach, with no dev session (Josui Prime). JOSUI_RC=1 turns Remote Control on for that conversation. |
JOSUI_TMUX |
unset | 1 starts a detached tmux session dev holding an interactive Claude Code beside the server. See Attaching. |
JOSUI_SSH_DIR |
/etc/josui/ssh |
Where the fallback's key, config and known_hosts are mounted. |
JOSUI_CONFIG_DIR, JOSUI_SKILLS_DIR |
set in the image | Where the identity and skills mounts are read from. |
The developer image's entrypoint reads these. Its
developer-entrypoint
is the authority when this table and it disagree.
Remote Control is how the agent is reached from claude.ai and the phone. For a copy that is worked in there is a terminal:
podman exec -it <service> tmux attach -t dev # a seat: JOSUI_MODE=worker, or JOSUI_TMUX=1
podman exec -it <service> claude-agent attach --rw # a supervised worker (Josui Prime); read-only without --rwA supervised worker has no dev session: claude-agent holds its one
conversation in tmux on a server of its own (tmux -L claude-agent).
Both follow the attaching terminal's size and survive the disconnect:
claude-agent holds its session in tmux on a server of its own, so run its
attach from outside tmux, not from inside dev. The tmux session is deliberately not watched: quitting your
own shell must not end the container. Quitting Claude Code in window 0 leaves
the pane for prefix + :respawn-pane.
Read the --debug-file first. Nothing else in the container will tell you,
and two of the three failures found so far were invisible from outside:
-
A work item the server has archived. On 2026-11-05 Josui Prime showed no session for a day. The container was healthy and polling the whole time; the debug file said a work item created days earlier was picked up and ended by the server with
reason=archived, after which the bridge returned to idle with no session. Restarting retries the same item and fails the same way. -
A workdir that is a git checkout, which makes Remote Control register a
git_repo_urland Anthropic refuse every session with an HTTP 400 unless the Claude GitHub App can see that repository. -
Credentials with empty tokens. On 2026-11-07 the unit crash-looped with "You must be logged in to use Remote Control" while
.credentials.jsonwas still there and still looked plausible:claudeAiOauthkept its scopes,subscriptionTypeandrateLimitTier, butaccessTokenandrefreshTokenwere empty strings andexpiresAtwas 0. A refresh had failed and left the record standing with nothing in it..claude.jsonstill held the fulloauthAccount, so the debug file readoauthAccount.organizationUuid=setbesidehasOAuthAccessToken=false. Nothing short of a fresh login fixes this; check the token lengths, not whether the file exists. -
A stale MCP client, after the gateway restarts: the gateway logs "client predates a gateway restart" and the agent keeps running without its tools. Restart the container.
What not to build: a watchdog that samples /proc/net/tcp for a
connection to the proxy. 0.6.0 shipped one and 0.7.0 removed it. Remote
Control polls -- a connection roughly every thirty to two hundred seconds,
gone in about a second -- so a healthy idle container shows no connection at
almost any instant (measured: one hit in ten samples over two minutes). The
debug file does not grow while idle either. There is no cheap local signal for
"the bridge is alive", and the one failure actually observed was not a
connectivity failure at all.
This repo built two images and builds none now. The development image, once
Containerfile.dev here, moved to
crunchtools/developer on
2026-11-06. Josui's own quay.io/crunchtools/josui was retired in 1.0.0, once
Josui Prime and every seat ran quay.io/crunchtools/developer:latest. Its
published tags stay where they are and no longer move. A new Claude Code or
claude-agent reaches Josui through the developer image.
python3 -m unittest discover -s tests -vThe tests cover the host tools in tools/.
AGPL-3.0-or-later