Cloister 0.4.2

Cloister 0.4.2 fixes routine Host Exec audit messages appearing in interactive Claude and Codex input areas. The embedded bridge previously echoed an audit summary to stderr after every execution, sharing the Agent terminal. Routine lifecycle records now stay in the existing owner-only JSONL audit file. Command output remains available through MCP, and audit-write failure diagnostics remain visible.

Profile V7/V8, tool schemas, authentication, and execution policies are unchanged. Base tools remain Node.js 24.19.0 and Rust 1.97.1. Agent software continues to be installed and updated independently.

Upgrade

brew update
brew upgrade yi427/tap/cloister
cloister profile upgrade --dry-run
cloister profile upgrade
cloister check

Restart existing Agent sessions after upgrading. Their Host MCP bridges run in the CLI process that launched them; reconnecting an old session does not replace that process.

Direct source installation is also supported:

cargo install --locked --git https://github.com/yi427/Cloister.git --tag v0.4.2 cloister

Verified on 2026-10-12

• Local make verify and the staged-snapshot pre-commit gate passed all 231 tests and Clippy. The new regression reproduces the terminal-output failure before the fix and passes afterward for Claude and Codex with successful and nonzero command exits, real authenticated local HTTP MCP calls, preserved command output, and persisted lifecycle records.
• Fix PR #12 and release-commit Verify passed.
• Release image publication passed. Anonymous GHCR access verified Linux ARM64 manifests for 0.4.2 and 0.4, the intended source revision, and the unchanged immutable SHA image.
• A clean temporary source installation from the exact v0.4.2 tag succeeded with --locked and reported cloister 0.4.2.
• Apple container 1.5.0 and the exact release image passed initialization and readiness, including actual Guest-to-Host connectivity, with no warnings.
• Codex 0.162.1 and Claude Code 2.1.296 passed first-use installation, offline reuse, explicit update, exact-version launch, controlled update-failure fallback, concurrent-session port separation, and bridge cleanup.
• Actual Claude Code 2.1.296 in the release image loaded all five Host tools from both the tag-installed and Homebrew-installed bridges. These checks used isolated state and the client's control protocol; no real credentials or model requests were used.
• Both installed CLI artifacts passed PTY checks for successful and nonzero Host executions: no routine audit echo reached the Agent terminal, while MCP output and file auditing remained intact.
• Homebrew strict online audit, source upgrade, and brew test passed locally. The macOS/Linux tap CI passed, and tap PR #4 is merged with the 0.4.2 Formula.

Release commit: 69e92550c8d868fb775383ff029a5d5473289d11.

Exact image: ghcr.io/yi427/cloister:0.4.2, index digest sha256:9d4009522ea6c6692ab168f38c732a2ed50ddcef41b2c43fd6be50492eac1230.

Source archive SHA-256: 11e58c726ba1a18e669c8bd9e2eb25e778a91ba1b028856de405c51cf82ae21b.

Security boundary and coverage

On-demand execution grants the macOS user's authority; purpose text and Guest-first guidance influence behavior without containing Host access. The selected workspace remains a live read-write Host bind mount. Host credential directories and privileged sockets are never mounted silently.

The client checks establish tool discovery for the recorded Claude version. The PTY checks use a simulated container with a real local MCP client; they establish terminal-output behavior for the installed artifacts. These checks do not certify authenticated model routing, Skill selection, or approval behavior in future independently updated Agents. This release has no prebuilt binary attachments.

Cloister 0.4.1

Cloister 0.4.1 fixes Host MCP tool discovery in strict clients such as Claude Code 2.1.296. Previously, cloister_host could connect while Claude rejected tools/list because ttlMs and cacheScope were missing. The bridge now returns ttlMs: 0 and cacheScope: "private" with its five tools.

Profile V7/V8, tool schemas, approval metadata, authentication, and execution policies are unchanged. Base tools remain Node.js 24.19.0 and Rust 1.97.1. Agent software continues to be installed and updated independently.

Upgrade

brew update
brew upgrade yi427/tap/cloister
cloister profile upgrade --dry-run
cloister profile upgrade
cloister check

Restart existing Agent sessions after upgrading. Their Host MCP bridges run in the CLI process that launched them; reconnecting an old session does not replace that process.

Direct source installation is also supported:

cargo install --locked --git https://github.com/yi427/Cloister.git --tag v0.4.1 cloister

Verified on 2026-10-12

• make verify and the staged-snapshot pre-commit gate passed all 230 tests and Clippy. The new authenticated HTTP regression test fails before the fix and passes after it.
• Fix PR #11 and release-commit Verify passed.
• Release image publication passed. Anonymous GHCR access verified Linux ARM64 manifests for 0.4.1 and 0.4, the intended source revision, and the unchanged immutable SHA image.
• A clean temporary source installation from the exact v0.4.1 tag succeeded with --locked and reported cloister 0.4.1.
• Apple container 1.5.0 and the exact release image passed initialization and readiness, including actual Guest-to-Host connectivity, with no warnings.
• Codex 0.162.1 and Claude Code 2.1.296 passed first-use installation, offline reuse, explicit update, exact-version launch, controlled update-failure fallback, concurrent-session port separation, and bridge cleanup.
• Actual Claude Code 2.1.296 in the release image loaded all five Host tools from both the tag-installed and Homebrew-installed bridges. These checks used isolated state and the client's control protocol; no real credentials or model requests were used.
• Homebrew strict online audit, source upgrade, and brew test passed locally. The macOS/Linux tap CI passed, and tap PR #3 is merged with the 0.4.1 Formula.

Release commit: 75ba927a615d616bc6e7eb9684b2b2b07d5d199b.

Exact image: ghcr.io/yi427/cloister:0.4.1, index digest sha256:7e75c0265eda78648dab2590d94ba273bc60478043a5c1629a6c56195e29f6cf.

Source archive SHA-256: f56169a8e68d97149f2a51549eb6881561ff47d00f8ef0e7362ab1b978e1881b.

Security boundary and coverage

On-demand execution grants the macOS user's authority; purpose text and Guest-first guidance influence behavior without containing Host access. The selected workspace remains a live read-write Host bind mount. Host credential directories and privileged sockets are never mounted silently.

The client checks establish tool discovery for the recorded Claude version. They do not certify authenticated model routing, Skill selection, or approval behavior in future independently updated Agents. This release has no prebuilt binary attachments.

Cloister 0.4.0

Cloister 0.4.0

Release tag: v0.4.0. The matching base image is
ghcr.io/yi427/cloister:0.4.0.

This release adds explicit on-demand Host tools and Profile V8. Agents can
discover installed macOS commands and use them in the same conversation,
without editing the Profile or restarting the session for each command.
The default mode remains allowlist.

The base tool versions are unchanged:

Base tool	Version
Node.js	24.19.0
Rust	1.97.1

On-demand Host tools

Create a separate Profile to deliberately enable broad Host access:

cloister init --host-exec-mode on-demand --profile /path/to/new-profile.toml
cloister codex --profile /path/to/new-profile.toml
# or: cloister claude --profile /path/to/new-profile.toml

Initialization discloses broad macOS-user authority before the normal Profile
creation confirmation. On-demand mode makes bare commands from the bridge's
startup PATH available without per-command registration or Cloister execution
prompts. Agent-client policies may still deny tools or request confirmation.

host.list_commands reports the selected mode and pinned commands.
The new read-only host.find_command checks one installed command without
executing it. Discovery is cached for the session, pinned commands take
precedence, and a changed canonical executable target requires rediscovery
after restarting the bridge. Relative and empty PATH entries are ignored.

Every on-demand host.exec requires a short reason. The canonical Host Skill
and MCP instructions guide both Agents to use Guest tools for routine workspace
work, explain Host operations, and reuse discovered commands. Execution still
uses literal arguments, bounded output/status polling, cancellation, and
metadata-only audit logs. Audit logs omit argument values, purpose text, and
environment values.

Profile compatibility and upgrade

New Profiles use schema_version = 8 and require explicit host.exec.mode:

[host.exec]
enabled = true
mode = "on-demand" # or "allowlist"
allow = []

Existing V7 Profiles remain supported with allowlist behavior. Installing the
CLI does not silently broaden their authority. After upgrading the CLI, update
the matching official image with:

cloister profile upgrade --dry-run
cloister profile upgrade
cloister check

profile upgrade changes only the official image reference and does not migrate
the schema or enable on-demand access. To enable the new mode, create a separate
V8 Profile or deliberately review a manual V8 configuration change. V6 and
earlier remain unsupported. Published 0.3.1 images lack the updated canonical
Host Skill and cannot be paired with the 0.4.0 CLI.

Security boundary and validation

On-demand grants broad execution with the macOS user's permissions. Required
purpose text and Guest-first guidance influence Agent behavior; they do not
contain Host filesystem, network, shell, or interpreter access. Executables can
change at the same path, and discovery does not eliminate filesystem races.
The selected workspace remains a live read-write Host bind mount. Shared Agent
state remains separate Cloister-managed state; credentials and Agent software
are not baked into the base image.

Development checks passed all 229 tests and Clippy, including real authenticated
loopback MCP discovery, execution, purpose validation, status, cancellation,
audit redaction, V7/V8 parsing, and both Agent approval configurations. On
2026-10-11, the local development image passed Apple container 1.5 readiness
and actual Guest-to-Host connectivity checks; Codex 0.162.1 and Claude Code
2.1.296 were installed independently and passed executable launch checks.

Publication checks against the exact release image are recorded separately in
the GitHub release.
Version output and deterministic configuration tests do not establish
authenticated model routing, Skill selection, or future Agent-client approval
behavior. Agent software continues to update independently of Cloister.

Publication verification on 2026-10-11

Release commit: b89d08b70a184faf6cb86692b7d38814b2ffb173.

• Local make verify and the staged-snapshot pre-commit hook passed all 229
  tests and Clippy. GitHub Verify passed for PR #10
  and the merged release commit.
• The release image workflow
  passed. Anonymous GHCR access returns Linux ARM64 for 0.4.0 and 0.4;
  both identify the same index. The existing sha-b89d08b70a184faf6cb86692b7d38814b2ffb173
  image remained unchanged after the tag build.
• Source installation with cargo install --locked --git ... --tag v0.4.0
  into a clean temporary installation root succeeded and reports cloister 0.4.0.
• The exact release CLI/image passed init, readiness, actual Guest-to-Host
  connectivity, base tool version checks, canonical Skill hash comparison,
  and a Guest workspace write observed on the Host.
• Fresh isolated-state launches passed with Codex 0.162.1 and Claude Code
  2.1.296. Both passed cached/offline and exact-version launches. An explicit
  update check passed; a deliberately rejecting local proxy caused an automatic
  update failure and successfully preserved/reused installed Codex. Two parallel
  Codex sessions used different workspaces and distinct Host bridge ports.
• A Guest in the exact release image authenticated to the Host MCP bridge and
  passed discovery, literal argument execution, missing-command, status, and
  cancellation checks. Purpose/argument/environment values were absent from
  the audit file. The temporary bridge, processes, and token file were cleaned up.
• Homebrew strict online audit, build-from-source installation, and brew test
  passed for the verified archive and Formula. The macOS and Linux Homebrew CI
  checks passed, and homebrew-tap PR #2
  was merged as 27e6f65ebf2dfc05fb09a0d3143868ae847b4a81.

These smoke checks used temporary isolated Agent state and did not log in or
perform model tasks. They do not certify model routing, Skill selection, or
future Agent-client approvals. The actual MCP checks used a test client in the
Guest, separately from the two Agent executable-launch checks.

Locked source installation emitted Cargo's existing yanked-dependency warning
for chacha20 0.10.1, inherited through rmcp and rand; installation still
completed with the unchanged dependency lockfile. This release does not make
an additional dependency-security certification.

Image index digest: sha256:03242c3c2ef897ad7bd6c57901eabc615a25ad3d2b5eda9ebfaedc8fcd4367db.
Release source archive SHA-256: 9604b270dd0bb5adb85121e366f90edde01b45c91581fd8101f866b51ca0408c.

Cloister 0.3.1

Cloister 0.3.1

Release tag: v0.3.1. The matching base image is
ghcr.io/yi427/cloister:0.3.1.

This patch fixes project workspace paths without changing Profile V7. After
upgrading the CLI, preview and apply the matching image update:

cloister profile upgrade --dry-run
cloister profile upgrade
cloister check

The upgrade creates an owner-only backup and preserves unrelated Profile
settings. Agent software continues to install and update independently.
The base tool versions are unchanged:

Base tool	Version
Node.js	24.19.0
Rust	1.97.1

Project-specific workspace paths

Different projects previously shared Guest /workspace, so Agent session
history recorded the same working directory and resume pickers could mix
unrelated projects.

The selected canonical Host path now appears under Guest /workspace, and
the Agent starts at that exact mount target. For example:

/Volumes/Projects/app -> /workspace/Volumes/Projects/app

Projects with the same directory name at different locations remain distinct.
Repeated launches and symbolic-link aliases of the same project use a stable
path. The rule applies to Codex, Claude, and explicit --workspace selection.
Only the selected project is mounted; its Host ancestors are not exposed.

Profile V7 and the shared Agent-state policy are unchanged. Project filtering
is an Agent feature, not a restriction on access to shared history. Codex users
can explicitly show all projects with cloister codex -- resume --all.

Existing sessions recorded at /workspace are left untouched and can be found
with resume --all. Moving a project changes its canonical path and therefore
its Guest working directory. The workspace remains a live read-write bind mount.

Documentation corrections

Installation instructions, Profile examples, and preview assets match 0.3.1.
Historical release records include the published 0.3.0 validation, and earlier
ADRs point to the decisions that amended them.

Development validation on 2026-10-10

• make verify passed all 216 tests and Clippy.
• Regression tests cover namesake projects with shared state for both Agents,
  repeated launches, symbolic-link aliases, explicit workspace selection,
  Unicode names, spaces, literal shell characters, and resume argument forwarding.
• A real Apple container 1.5 smoke check verified a nested workspace path with
  Unicode and spaces, a read-only root, and Guest writes visible on the Host.
  Its temporary container was removed.
• The user tested the fix and reported no problems. This confirmation did not
  record exact Agent versions or a separate per-operation acceptance trace.

Release validation on 2026-10-10

• Local make verify and the staged-snapshot hook passed all 216 tests and Clippy. GitHub Verify passed on the release commit fe2a79e9928683d3e45975edee54b54573ea87dc.
• The annotated v0.3.1 tag points to that verified main commit. The exact release image is sha256:8a54d60dad47cf90b4fa52732720a6411d067418f11dbf914bbac2fe64bec8d4; anonymous Linux ARM64 access and its source revision were verified. The 0.3 channel matches 0.3.1, the immutable SHA image was preserved, and the previous 0.3.0 image digest is unchanged.
• cargo install --locked --git https://github.com/yi427/Cloister.git --tag v0.3.1 cloister succeeded in a clean temporary installation root. Homebrew source installation, strict online audit, and brew test passed for the versioned source archive and its SHA-256.
• The exact image started with Node.js 24.19.0 and Rust 1.97.1, with neither Agent preinstalled. A project path containing Unicode and spaces mapped to its full canonical path under /workspace; its working directory matched the mount, Guest writes appeared on the Host, the root filesystem rejected writes, and the canonical Host Exec skill matched the release source.
• Isolated-state first-use launches installed Codex 0.162.1 and Claude Code 2.1.296. Cached offline launches and exact-version selection passed for both. An explicit Codex update check and two concurrent Codex launches with distinct bridge ports passed.
• Fresh init selected the exact 0.3.1 image, created an owner-only temporary Profile, and passed readiness including actual container-to-host connectivity. The existing local V7 Profile was backed up and upgraded while preserving unrelated fields and permissions. The upgraded Homebrew CLI passed the final local cloister check with no warnings after preparing both Agent caches without mounting user credentials.
• A temporary authenticated Host MCP server passed tool discovery, literal command execution, status reads, cancellation, and owner-only audit checks. Its server stopped and temporary token was removed.

No authenticated model tasks were performed. Release Agent smoke checks used isolated state without existing user credentials; the recorded Agent versions do not certify future independently installed versions. MCP checks used a temporary allowlist with harmless echo and sleep commands. Project workspaces remain read-write, shared Agent history remains shared when selected, and the default network permits internet access.

Cloister 0.3.0

Cloister 0.3.0

Release tag: v0.3.0. The matching base image is
ghcr.io/yi427/cloister:0.3.0.

This breaking release uses Profile V7. Older Profiles are rejected; no migration
or backwards compatibility is provided. Create a new Profile explicitly.

The base image no longer downloads or includes Codex or Claude Code. First use
installs the selected official npm package in a dedicated preparation container.
Cloister manages automatic update checks, exact-version selection, and cached
offline launches independently of the base image release.

Base tool	Version
Node.js	24.19.0
Rust	1.97.1

Profile [agent] now requires codex, claude, and update_interval_hours in
addition to state. Versions accept latest or an exact stable semantic version.
New Profiles select latest and a 24-hour check interval. --agent-version,
--update-agent, and --offline expose per-invocation controls.

Each Agent session uses an OS-allocated bridge port, a separate bearer token,
execution records, fixed workspace, and named container. Explicit ports remain
available. Installation uses a cross-process lock and atomic inventory updates;
running sessions keep their software directory while new versions are prepared.

Software caches are separate from credentials and mounted read-only in Agent
sessions. Preparation containers receive no workspace, Agent credentials, or Host
MCP token. Shared Agent state is still shared across projects when selected.
The workspace remains read-write and Host Exec still runs with macOS user
permissions. Network access remains unrestricted by Cloister's default network.

Automatic update failures reuse an installed version with a warning; first-use
and explicit-update failures stop launch. Corrupt metadata fails closed. Old
software versions remain on disk; automatic garbage collection is deferred.
--offline disables software downloads/checks only, not Agent network access.

CLI/image pairing now covers base runtime integration only. Independent Agent
updates may introduce upstream integration incompatibilities; record actual
versions during acceptance and select an exact version to recover.

SIGINT, SIGTERM, and SIGHUP request container and bridge cleanup. Runtime removal
failures report the container name. SIGKILL and machine failure cannot guarantee
cleanup.

Readiness checks recognize both Apple container PF-anchor layouts and verify
container-to-host HTTP connectivity with a bounded, isolated temporary container.
DNS and on-disk forwarding configuration alone do not establish connectivity.

Real Apple-container smoke checks passed, and the user accepted the current
development build on 2026-10-10; see the
acceptance record for the tested versions and
coverage limits. Authenticated task, tool-approval, and Host Exec behavior were
not independently recorded against every subsequently installed Agent version.

Release validation on 2026-10-10

• Local make verify passed all 212 tests and Clippy; GitHub CI passed for the release commit f883ea1901188dfad0bf9610e07321907c5b23f4.
• Anonymous GHCR access, Linux ARM64 architecture, and the image's source revision were verified. The exact image digest is sha256:bf2528421b37aaf89863a76576b0a4375e8841c3549a99481d5cbe07733ff02d.
• Installation from v0.3.0 with cargo install --locked, Homebrew source installation, strict online audit, and brew test passed.
• The published base image started with Node.js 24.19.0 and Rust 1.97.1, with neither Agent preinstalled.
• Isolated-state first-use launches installed Codex 0.162.1 and Claude Code 2.1.296. Cached offline launches, exact installed-version selection, an explicit update check, and two concurrent Codex launches with distinct bridge ports passed.
• init and the upgraded default Profile passed readiness checks, including actual container-to-host connectivity. The final local check reported no warnings.

These release smoke checks did not perform authenticated model tasks. Agent software remains independently updated; these versions identify the tested launches.

Cloister 0.2.0

Cloister 0.2.0

Cloister 0.2.0 makes long-running Host Exec work easier to inspect and makes
the macOS CLI and Linux ARM64 Guest image an explicit, fail-closed release
pair. It keeps Profile V6 unchanged while adding an explicit upgrade path for
existing official release Profiles.

Highlights

Clear Guest workspace routing

The canonical Host Exec skill now tells Codex and Claude to read, write, list,
and patch /workspace with Guest file tools. /workspace is the live
read-write bind mount of the selected Host project; it is not a delayed or
separate copy.

Host Exec remains for Profile-allowed macOS executables. The skill explicitly
rejects Base64, Python, or another allowed interpreter as a workspace
file-transfer workaround, reducing unnecessary Host approvals and broad
interpreter use.

Discoverable and waitable Host execution

host.list_commands now reports the fixed Host working directory used by
allowed commands, without adding a model-selected working directory or a
separate pwd capability.

host.exec_status accepts an optional wait_ms. A bounded wait returns when
new output arrives after the supplied cursor, the execution becomes terminal,
or the interval expires. Immediate status reads and cancellation remain
available, output cursors remain incremental, and status reads do not require
another execution approval.

Exact CLI and image release pairing

Official ghcr.io/yi427/cloister:X.Y.Z images must exactly match the running
CLI version. Cloister rejects older, newer, moving, and unsupported official
references before Codex or Claude can create state, start the Host bridge, or
call Apple container; Agent --dry-run follows the same rule.

Full sha-<40-hex> tags remain available as immutable testing images with a
warning. Local and third-party images remain available with an explicit
unverified-compatibility warning. Official main, latest, and X.Y tags are
not valid persistent Profile references.

cloister check reports release compatibility separately from runtime image
availability. A paired release is PASS, a testing or custom image is WARN,
and an invalid official reference is FAIL.

Explicit Profile image upgrade

After installing the 0.2.0 CLI, a Profile that selects the official 0.1.0 image
must be upgraded before launching an Agent:

cloister profile upgrade --dry-run
cloister profile upgrade
cloister check

The command upgrades only an older official exact-release image in a valid
current-schema Profile. Dry-run does not inspect or pull an image and does not
change files. The apply flow verifies the exact Linux ARM64 target, confirms
image pulling when needed, separately confirms the Profile edit, creates a new
owner-only backup, and atomically replaces only the TOML image value while
preserving comments, unrelated settings, and the original file mode.

Testing images, custom images, moving tags, future official images, symlink
Profiles, existing backup paths, and incompatible Profile schemas require
manual review.

Installation

Cloister 0.2.x is distributed through the official Homebrew tap. The Formula
builds the CLI from the immutable release source and installs Apple container
as a runtime dependency. It does not start the runtime, create a Profile, pull
the Guest image, or rewrite an existing Profile.

brew install yi427/tap/cloister

Alternatively, compile directly from the exact Git tag:

cargo install --locked \
  --git https://github.com/yi427/Cloister.git \
  --tag v0.2.0 \
  cloister

The CLI and Guest image form one immutable release pair:

CLI:   v0.2.0
Image: ghcr.io/yi427/cloister:0.2.0

The Linux ARM64 image pins:

Tool	Version
Node.js	24.19.0
Rust	1.97.1
Codex	0.147.0
Claude Code	2.1.227

Security boundary

Cloister narrows ambient Host access but does not make every exposed
capability safe:

• /workspace is a live read-write bind mount. Guest writes, modifications,
  and deletions affect the selected Host project directly.
• Apple container's default network may reach the internet. A named or default
  network is not an egress firewall.
• Host Exec is an explicit escape hatch. An allowed executable runs with the
  macOS permissions and complete inherited environment of the user who
  started Cloister.
• Profile V6 still supports arguments = "any"; interpreters and build tools
  can therefore provide broad Host execution.
• Shared Agent-state directories contain credentials, settings, history, and
  sessions and must be treated as secrets.
• Approval prompts are interaction policy rather than a security boundary, and
  audit logs are observational rather than tamper-proof.

Cloister does not silently mount Host credential directories, existing Codex
or Claude directories, home directories, or privileged sockets.

Read the tagged
security model
and
architecture decisions
before enabling Host Exec for sensitive work.

Requirements and known limitations

• Apple silicon Mac with Apple container 1.2 or newer.
• No Intel Mac, Linux-host, Docker, or general-purpose container-runtime
  support.
• No automatic Profile schema migration; 0.2.0 continues to use Profile V6.
• No automatic replacement of testing or custom images.
• No argument-level Host Exec restrictions beyond arguments = "any".
• No Host-level CPU, memory, filesystem, or network containment for Host Exec.
• Running Host Exec jobs and captured output do not survive bridge shutdown.
• No GUI, prebuilt standalone CLI binary, or floating latest image tag.

Release verification

The release procedure requires staged-snapshot and GitHub verification,
anonymous access to the exact Linux ARM64 image, installation from the
immutable v0.2.0 tag, a real 0.1.0-to-0.2.0 Profile image upgrade, and smoke
tests for init, check, Codex, Claude, Host Exec discovery, bounded status
waiting, cancellation, and audit logging.

The exact release image and tag are immutable. A defective release is replaced
by a new patch version rather than by moving v0.2.0 or its 0.2.0 image.

Cloister 0.1.0

Cloister 0.1.0

Cloister 0.1.0 is the first public release of a terminal-first development
environment for running Codex and Claude Code in Linux ARM64 guests managed by
Apple's container CLI. It keeps the selected workspace, agent state, network
policy, and optional host-command access explicit in a versioned Profile.

Highlights

• Run Codex and Claude Code through the same Profile V6 contract and Apple
  container command planner.
• Create a Profile interactively with cloister init. Runtime startup, image
  pulls, and the required localhost DNS mapping remain separate, confirmed
  operations, and an existing Profile path is never overwritten.
• Inspect Profile, proxy, host-command, runtime, image, and DNS readiness
  without changing state with cloister check.
• Preserve Codex and Claude state in separate owner-only Cloister directories,
  or keep agent state isolated inside an ephemeral guest.
• Expose explicitly allowlisted macOS commands through the authenticated
  cloister_host MCP server and its canonical Host Exec skill.
• Discover host commands, start work, stream incremental output, inspect long
  executions, and cancel complete process groups through host.list_commands,
  host.exec, host.exec_status, and host.exec_cancel.
• Record bounded, owner-only Host Exec lifecycle metadata without persisting
  raw arguments, output, environment values, bearer tokens, or credentials.

Installation

Cloister 0.1.x is available from the official Homebrew tap. The Formula builds
the CLI from the exact release source and installs Apple container as a
runtime dependency. It does not start the runtime, create a Profile, or pull
the guest image.

brew install yi427/tap/cloister

Alternatively, compile directly from the exact Git tag:

cargo install --locked \
  --git https://github.com/yi427/Cloister.git \
  --tag v0.1.0 \
  cloister

The CLI and guest image form one release pair:

CLI:   v0.1.0
Image: ghcr.io/yi427/cloister:0.1.0

The image is published for Linux ARM64. It runs as a non-root user and pins the
following primary tools:

Tool	Version
Node.js	24.18.0
Rust	1.97.1
Codex	0.146.0
Claude Code	2.1.220

Security boundary

Cloister reduces ambient host access, but it does not make every exposed
capability safe:

• /workspace is a live read-write bind mount. Guest writes, modifications,
  and deletions affect the selected host project directly.
• Apple container's default network may reach the internet. A named or default
  network is not an egress firewall.
• Host Exec is an explicit escape hatch. An allowed executable runs with the
  macOS permissions and complete inherited environment of the user who started
  Cloister.
• Profile V6 supports arguments = "any". Interpreters and build tools can
  therefore provide broad host execution even when the executable allowlist is
  narrow.
• Agent approval prompts are interaction policy, not a security boundary. A
  guest process with the ephemeral bridge token can call enabled tools, while
  the server still enforces the immutable Profile allowlist.
• Shared agent-state directories contain credentials, settings, history, and
  sessions and must be treated as secrets.
• Audit logs are observational rather than tamper-proof because a sufficiently
  powerful allowed host command may be able to alter them.

Cloister does not silently mount the host's existing Codex or Claude
directories, credential directories, or privileged sockets.

Read the full
security model
and accepted
architecture decisions
before enabling Host Exec for sensitive work.

Requirements and known limitations

• Apple silicon Mac with Apple container 1.2 or newer.
• No Intel Mac, Linux-host, Docker, or general-purpose container-runtime
  support.
• No automatic migration from an incompatible Profile schema; 0.1.0 accepts
  Profile V6.
• No argument-level Host Exec restrictions beyond arguments = "any".
• No host-level CPU, memory, filesystem, or network containment for Host Exec.
• Running Host Exec jobs and captured output do not survive bridge shutdown.
• The default Host MCP port is 17834; another port must be selected manually
  when it is already in use.
• No GUI, prebuilt standalone CLI binary, or floating latest image tag.

First run

cloister init
cloister check

cd /path/to/project
cloister codex
# or
cloister claude

Review the generated Profile before launching an agent, especially the
workspace, proxy mode, shared-state choice, and Host Exec allowlist.

Release verification

The release procedure requires the local staged-snapshot checks and GitHub
Verify workflow to pass, anonymous access to the exact Linux ARM64 image,
installation from the immutable v0.1.0 tag, and end-to-end smoke tests for
init, check, Codex, Claude, Host Exec, cancellation, and audit logging.

The exact release image is immutable. Cloister does not publish latest; a
defective release is replaced by a new patch version rather than by moving the
0.1.0 tag.