Skip to content
crunchtoolsPublic

About

Claude Code packaged as a crunchtools autonomous agent

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

josui

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.

What goes in

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.

Network

The container sits on an internal network with no DNS. Its only peer is the Trentina gateway, by address:

  • MCP: TRENTINA_MCP_URL and TRENTINA_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_PROXY pointing 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_URL set, the entrypoint writes a git config in the state volume (mode 0600) that sends https://github.com/ to the route with the gateway token, and includes it from the global git config. There is no gh and no GitHub credential in the container; the gateway holds the token.

Fallback into the host

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: restrict on 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.

Controls

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_CALLS per conversation (default 500) and JOSUI_MAX_REPEAT identical 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, WebSearch and WebFetch are 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.

Text session

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 /names run as skills; ! is refused.
  • podman exec -it <service> claude-agent attach shows the session live; --rw to 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.

Run it

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 code

A 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.fifo

Then restart the service. A new working directory also needs its trust question answered once: podman exec -it <service> claude-agent attach --rw.

Environment

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.

Attaching

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 --rw

A 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.

When no session appears

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_url and 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.json was still there and still looked plausible: claudeAiOauth kept its scopes, subscriptionType and rateLimitTier, but accessToken and refreshToken were empty strings and expiresAt was 0. A refresh had failed and left the record standing with nothing in it. .claude.json still held the full oauthAccount, so the debug file read oauthAccount.organizationUuid=set beside hasOAuthAccessToken=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.

The image

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.

Development

python3 -m unittest discover -s tests -v

The tests cover the host tools in tools/.

License

AGPL-3.0-or-later

About

Claude Code packaged as a crunchtools autonomous agent

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages