# jackin-capsule (https://jackin.tailrocks.com/reference/crates/jackin-capsule/)



{/* GENERATED from crates/jackin-capsule/README.md — edit the README, not this file */}

In-container control plane for jackin❯ role containers.

`jackin-capsule` is copied into derived role images and runs as PID 1 under `/jackin/runtime/jackin-capsule`. It owns the terminal sessions, PTYs, pane layout, status bar, attach socket, runtime setup, and the in-container git trailer hook. The host `jackin` binary starts containers detached and attaches through the Capsule client so the operator sees the multiplexer instead of raw container logs.

Design rationale and cross-cutting capsule behaviour live under [Capsule reference](/reference/capsule/) — this README is the crate orientation record only.

## What this crate owns [#what-this-crate-owns]

* PID 1 + the in-container multiplexer daemon (session/PTY supervision, attach socket, status bar, control protocol).
* Host-side capsule client (stdin/stdout forward, resize, host-affordance bridge).
* In-container runtime setup (git/GitHub init, trailer hooks, agent home seeding, auth handoff, Claude MCP registration).
* Capsule TUI surfaces, clipboard image staging, firewall/sudo-provision helpers, and usage/telemetry re-exports from `jackin-usage`.

Not responsible for: protocol encoding (`jackin-protocol`), host-side launch orchestration (`jackin-runtime`), or config schema migration.

## Architecture tier and allowed dependencies [#architecture-tier-and-allowed-dependencies]

**L4 entry/glue (binary + lib).** Allowed workspace dependencies: `jackin-core`, `jackin-diagnostics` (OTLP), `jackin-protocol`, `jackin-usage`, `jackin-term`, `jackin-tui`, `jackin-agent-status`, `jackin-build-meta` (build.rs). Must **not** depend on host-side runtime (`jackin-runtime`) or other host binary crates — the capsule is a different process tree.

## Structure [#structure]

| Module                                                                                                                                                                                              | Owns                                             | Tests                                                                                       |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------- |
| <RepoFile path="crates/jackin-capsule/src/lib.rs">`lib.rs`</RepoFile>                                                                                                                               | crate root, logging/usage re-exports             | —                                                                                           |
| <RepoFile path="crates/jackin-capsule/src/main.rs">`main.rs`</RepoFile>                                                                                                                             | binary entry (PID 1 / client / exec subcommands) | —                                                                                           |
| <RepoFile path="crates/jackin-capsule/src/daemon.rs">`daemon.rs`</RepoFile> · <RepoFile path="crates/jackin-capsule/src/daemon.rs">`daemon/`</RepoFile>                                             | multiplexer daemon event loop                    | <RepoFile path="crates/jackin-capsule/src/daemon/tests.rs">`tests.rs`</RepoFile>            |
| <RepoFile path="crates/jackin-capsule/src/session.rs">`session.rs`</RepoFile> · <RepoFile path="crates/jackin-capsule/src/session.rs">`session/`</RepoFile>                                         | per-agent PTY sessions                           | <RepoFile path="crates/jackin-capsule/src/session/tests.rs">`tests.rs`</RepoFile>           |
| <RepoFile path="crates/jackin-capsule/src/client.rs">`client.rs`</RepoFile> · <RepoFile path="crates/jackin-capsule/src/client.rs">`client/`</RepoFile>                                             | host-side attach client                          | <RepoFile path="crates/jackin-capsule/src/client/tests.rs">`tests.rs`</RepoFile>            |
| <RepoFile path="crates/jackin-capsule/src/client_writer.rs">`client_writer.rs`</RepoFile>                                                                                                           | sole attach-socket writer                        | —                                                                                           |
| <RepoFile path="crates/jackin-capsule/src/attach_context.rs">`attach_context.rs`</RepoFile>                                                                                                         | single host-connection state                     | —                                                                                           |
| <RepoFile path="crates/jackin-capsule/src/attach_protocol.rs">`attach_protocol.rs`</RepoFile>                                                                                                       | attach lifecycle helpers                         | —                                                                                           |
| <RepoFile path="crates/jackin-capsule/src/protocol.rs">`protocol.rs`</RepoFile> · <RepoFile path="crates/jackin-capsule/src/protocol.rs">`protocol/`</RepoFile>                                     | capsule wire framing helpers                     | —                                                                                           |
| <RepoFile path="crates/jackin-capsule/src/tui.rs">`tui.rs`</RepoFile> · <RepoFile path="crates/jackin-capsule/src/tui.rs">`tui/`</RepoFile>                                                         | in-container TUI render/input                    | nested                                                                                      |
| <RepoFile path="crates/jackin-capsule/src/clipboard.rs">`clipboard.rs`</RepoFile> · <RepoFile path="crates/jackin-capsule/src/clipboard.rs">`clipboard/`</RepoFile>                                 | clipboard image staging + idle expiry            | <RepoFile path="crates/jackin-capsule/src/clipboard/tests.rs">`tests.rs`</RepoFile>         |
| <RepoFile path="crates/jackin-capsule/src/runtime_setup.rs">`runtime_setup.rs`</RepoFile> · <RepoFile path="crates/jackin-capsule/src/runtime_setup.rs">`runtime_setup/`</RepoFile>                 | in-container git/auth/MCP setup                  | <RepoFile path="crates/jackin-capsule/src/runtime_setup/tests.rs">`tests.rs`</RepoFile>     |
| <RepoFile path="crates/jackin-capsule/src/config.rs">`config.rs`</RepoFile>                                                                                                                         | `CapsuleConfig` load/validate                    | —                                                                                           |
| <RepoFile path="crates/jackin-capsule/src/container_context.rs">`container_context.rs`</RepoFile> · <RepoFile path="crates/jackin-capsule/src/container_context.rs">`container_context/`</RepoFile> | container identity metadata                      | <RepoFile path="crates/jackin-capsule/src/container_context/tests.rs">`tests.rs`</RepoFile> |
| <RepoFile path="crates/jackin-capsule/src/agent_status.rs">`agent_status.rs`</RepoFile> · <RepoFile path="crates/jackin-capsule/src/agent_status.rs">`agent_status/`</RepoFile>                     | capsule-facing status hooks                      | nested                                                                                      |
| <RepoFile path="crates/jackin-capsule/src/pid1.rs">`pid1.rs`</RepoFile> · <RepoFile path="crates/jackin-capsule/src/pid1.rs">`pid1/`</RepoFile>                                                     | reaper + signal forward                          | <RepoFile path="crates/jackin-capsule/src/pid1/tests.rs">`tests.rs`</RepoFile>              |
| <RepoFile path="crates/jackin-capsule/src/exec.rs">`exec.rs`</RepoFile> · <RepoFile path="crates/jackin-capsule/src/exec.rs">`exec/`</RepoFile>                                                     | `jackin-exec` / capsule exec                     | <RepoFile path="crates/jackin-capsule/src/exec/tests.rs">`tests.rs`</RepoFile>              |
| <RepoFile path="crates/jackin-capsule/src/firewall.rs">`firewall.rs`</RepoFile> · <RepoFile path="crates/jackin-capsule/src/firewall.rs">`firewall/`</RepoFile>                                     | allowlist egress apply                           | <RepoFile path="crates/jackin-capsule/src/firewall/tests.rs">`tests.rs`</RepoFile>          |
| <RepoFile path="crates/jackin-capsule/src/sudo_provision.rs">`sudo_provision.rs`</RepoFile> · <RepoFile path="crates/jackin-capsule/src/sudo_provision.rs">`sudo_provision/`</RepoFile>             | per-profile sudo grant                           | <RepoFile path="crates/jackin-capsule/src/sudo_provision/tests.rs">`tests.rs`</RepoFile>    |
| <RepoFile path="crates/jackin-capsule/src/exit_assess.rs">`exit_assess.rs`</RepoFile> · <RepoFile path="crates/jackin-capsule/src/exit_assess.rs">`exit_assess/`</RepoFile>                         | dirty-exit modal assessment                      | <RepoFile path="crates/jackin-capsule/src/exit_assess/tests.rs">`tests.rs`</RepoFile>       |
| <RepoFile path="crates/jackin-capsule/src/git_context.rs">`git_context.rs`</RepoFile>                                                                                                               | branch/dirty/PR for status bar                   | —                                                                                           |
| <RepoFile path="crates/jackin-capsule/src/pr_context.rs">`pr_context.rs`</RepoFile>                                                                                                                 | GitHub PR lookup                                 | —                                                                                           |
| <RepoFile path="crates/jackin-capsule/src/pull_request.rs">`pull_request.rs`</RepoFile> · <RepoFile path="crates/jackin-capsule/src/pull_request.rs">`pull_request/`</RepoFile>                     | PR snapshots for TUI                             | <RepoFile path="crates/jackin-capsule/src/pull_request/tests.rs">`tests.rs`</RepoFile>      |
| <RepoFile path="crates/jackin-capsule/src/socket.rs">`socket.rs`</RepoFile> · <RepoFile path="crates/jackin-capsule/src/socket.rs">`socket/`</RepoFile>                                             | Unix attach socket helpers                       | <RepoFile path="crates/jackin-capsule/src/socket/tests.rs">`tests.rs`</RepoFile>            |
| <RepoFile path="crates/jackin-capsule/src/mcp_server.rs">`mcp_server.rs`</RepoFile>                                                                                                                 | MCP stdio for `jackin_exec`                      | —                                                                                           |
| <RepoFile path="crates/jackin-capsule/src/output.rs">`output.rs`</RepoFile>                                                                                                                         | plain stdout/stderr writers                      | —                                                                                           |
| <RepoFile path="crates/jackin-capsule/src/services.rs">`services.rs`</RepoFile> · <RepoFile path="crates/jackin-capsule/src/services.rs">`services/`</RepoFile>                                     | side-effect adapters                             | —                                                                                           |
| <RepoFile path="crates/jackin-capsule/src/util.rs">`util.rs`</RepoFile> · <RepoFile path="crates/jackin-capsule/src/util.rs">`util/`</RepoFile>                                                     | shared bounded helpers                           | <RepoFile path="crates/jackin-capsule/src/util/tests.rs">`tests.rs`</RepoFile>              |
| <RepoFile path="crates/jackin-capsule/src/wordlist.rs">`wordlist.rs`</RepoFile> · <RepoFile path="crates/jackin-capsule/src/wordlist.rs">`wordlist/`</RepoFile>                                     | tab codenames                                    | <RepoFile path="crates/jackin-capsule/src/wordlist/tests.rs">`tests.rs`</RepoFile>          |
| <RepoFile path="crates/jackin-capsule/src/alloc_telemetry.rs">`alloc_telemetry.rs`</RepoFile> · <RepoFile path="crates/jackin-capsule/src/alloc_telemetry.rs">`alloc_telemetry/`</RepoFile>         | opt-in heap telemetry                            | <RepoFile path="crates/jackin-capsule/src/alloc_telemetry/tests.rs">`tests.rs`</RepoFile>   |
| <RepoFile path="crates/jackin-capsule/src/debug_panic.rs">`debug_panic.rs`</RepoFile> · <RepoFile path="crates/jackin-capsule/src/debug_panic.rs">`debug_panic/`</RepoFile>                         | force-panic debug hook                           | <RepoFile path="crates/jackin-capsule/src/debug_panic/tests.rs">`tests.rs`</RepoFile>       |

## Public API [#public-api]

`tui::pane_snapshot` exposes `pane_content_from_damagegrid` and range-scoped `pane_content_range_from_damagegrid` for content-coordinate row materialization (bench + selection/link paths).

Library surface for integration tests and the binary: `daemon`, `client`, `config`, `session`, `tui`, `protocol`, `runtime_setup`, plus `logging`/`telemetry`/`usage` re-exports from `jackin-usage`. Most modules are `pub` so `tests/` and the binary can call them without spawning a PTY; production consumers outside this crate should not depend on capsule internals.

## How to verify [#how-to-verify]

```sh
cargo nextest run -p jackin-capsule
cargo clippy -p jackin-capsule --all-targets -- -D warnings
```

Capsule e2e/smoke is a CI mandate under `.github/` — any PR that touches this crate must note the smoke block.