# akitaonrails/ai-jail architecture

> Architecture diagram of the GitHub repository akitaonrails/ai-jail, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/akitaonrails/ai-jail
- Repository: https://github.com/akitaonrails/ai-jail

## Overview

ai-jail is a CLI supervisor that runs coding agents inside OS-enforced sandboxes. The main workflow is invocation and configuration, policy and mount preparation, platform sandbox construction, then supervised command execution with optional terminal handling and filtered egress. Major supporting capabilities include browser profiles, credential-state mounting, phantom-secret substitution, bootstrap policy generation, and opt-in audit logging. The graph reflects README capabilities as well as sampled source; unsampled implementation details are represented only where the tree or README supports them.

Main entry points: [`src/main.rs`](https://github.com/akitaonrails/ai-jail/blob/master/src/main.rs) (Supervisor), [`src/proxy.rs`](https://github.com/akitaonrails/ai-jail/blob/master/src/proxy.rs) (Filtered Egress), [`src/sandbox/mod.rs`](https://github.com/akitaonrails/ai-jail/blob/master/src/sandbox/mod.rs) (Sandbox Preparation), [`src/sandbox/bwrap.rs`](https://github.com/akitaonrails/ai-jail/blob/master/src/sandbox/bwrap.rs) (Linux Bubblewrap)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Invocation"]
  node_main["Supervisor<br/>[main.rs]"]
  node_cli["CLI Parser<br/>[cli.rs]"]
  node_config["Configuration<br/>[config.rs]"]
end

subgraph group_policy["Policy Setup"]
  node_command["Command Resolution<br/>[command.rs]"]
  node_sandboxmod["Sandbox Preparation<br/>[mod.rs]"]
  node_bootstrap["Agent Bootstrap<br/>[bootstrap.rs]"]
end

subgraph group_sandbox["Sandbox Runtime"]
  node_bwrap["Linux Bubblewrap<br/>[bwrap.rs]"]
  node_seatbelt["macOS Seatbelt<br/>[seatbelt.rs]"]
  node_landlock["Landlock Limits<br/>[landlock.rs]"]
  node_seccomp["Seccomp Filter<br/>[seccomp.rs]"]
  node_proxy["Filtered Egress<br/>[proxy.rs]"]
  node_secret["Secret Substitution<br/>[secret.rs]"]
end

subgraph group_support["Supervision"]
  node_pty["PTY Filtering<br/>[pty.rs]"]
  node_status["Status Bar<br/>[statusbar.rs]"]
  node_audit[("Audit Log<br/>[audit.rs]")]
end

node_user(("User"))
node_agent["Agent Command"]
node_hostos["Host OS"]
node_remote(("Allowed Hosts"))
node_github(("GitHub"))

node_user -->|"invokes"| node_main
node_main -->|"parses"| node_cli
node_main -->|"loads"| node_config
node_config -->|"returns settings"| node_main
node_main -->|"resolves command"| node_command
node_main -->|"prepares policy"| node_sandboxmod
node_sandboxmod -->|"builds Linux sandbox"| node_bwrap
node_sandboxmod -->|"builds macOS sandbox"| node_seatbelt
node_bwrap -->|"applies limits"| node_landlock
node_bwrap -->|"applies filter"| node_seccomp
node_main -.->|"generates setup"| node_bootstrap
node_main -.->|"starts proxy"| node_proxy
node_proxy -.->|"dials allowed hosts"| node_remote
node_proxy -.->|"substitutes credentials"| node_secret
node_main -->|"launches sandboxed"| node_agent
node_agent -->|"runs under restrictions"| node_hostos
node_main -.->|"interposes terminal"| node_pty
node_main -.->|"sets up status"| node_status
node_status -.->|"checks version"| node_github
node_main -.->|"records launch"| node_audit
node_proxy -.->|"records verdicts"| node_audit
node_user -.->|"verifies log"| node_audit

click node_main "https://github.com/akitaonrails/ai-jail/blob/master/src/main.rs"
click node_cli "https://github.com/akitaonrails/ai-jail/blob/master/src/cli.rs"
click node_config "https://github.com/akitaonrails/ai-jail/blob/master/src/config.rs"
click node_command "https://github.com/akitaonrails/ai-jail/blob/master/src/command.rs"
click node_sandboxmod "https://github.com/akitaonrails/ai-jail/blob/master/src/sandbox/mod.rs"
click node_bwrap "https://github.com/akitaonrails/ai-jail/blob/master/src/sandbox/bwrap.rs"
click node_seatbelt "https://github.com/akitaonrails/ai-jail/blob/master/src/sandbox/seatbelt.rs"
click node_landlock "https://github.com/akitaonrails/ai-jail/blob/master/src/sandbox/landlock.rs"
click node_seccomp "https://github.com/akitaonrails/ai-jail/blob/master/src/sandbox/seccomp.rs"
click node_proxy "https://github.com/akitaonrails/ai-jail/blob/master/src/proxy.rs"
click node_secret "https://github.com/akitaonrails/ai-jail/blob/master/src/secret.rs"
click node_bootstrap "https://github.com/akitaonrails/ai-jail/blob/master/src/bootstrap.rs"
click node_pty "https://github.com/akitaonrails/ai-jail/blob/master/src/pty.rs"
click node_status "https://github.com/akitaonrails/ai-jail/blob/master/src/statusbar.rs"
click node_audit "https://github.com/akitaonrails/ai-jail/blob/master/src/audit.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_cli,node_config,node_user toneBlue
class node_command,node_sandboxmod,node_bootstrap toneAmber
class node_bwrap,node_seatbelt,node_landlock,node_seccomp,node_proxy,node_secret toneMint
class node_pty,node_status,node_audit toneRose
class node_agent,node_hostos,node_remote,node_github toneIndigo
```

## Components

### Invocation

- [Supervisor](https://github.com/akitaonrails/ai-jail/blob/master/src/main.rs): `src/main.rs`
- [CLI Parser](https://github.com/akitaonrails/ai-jail/blob/master/src/cli.rs): `src/cli.rs`
- [Configuration](https://github.com/akitaonrails/ai-jail/blob/master/src/config.rs): `src/config.rs`

### Policy Setup

- [Command Resolution](https://github.com/akitaonrails/ai-jail/blob/master/src/command.rs): `src/command.rs`
- [Sandbox Preparation](https://github.com/akitaonrails/ai-jail/blob/master/src/sandbox/mod.rs): `src/sandbox/mod.rs`
- [Agent Bootstrap](https://github.com/akitaonrails/ai-jail/blob/master/src/bootstrap.rs): `src/bootstrap.rs`

### Sandbox Runtime

- [Linux Bubblewrap](https://github.com/akitaonrails/ai-jail/blob/master/src/sandbox/bwrap.rs): `src/sandbox/bwrap.rs`
- [macOS Seatbelt](https://github.com/akitaonrails/ai-jail/blob/master/src/sandbox/seatbelt.rs): `src/sandbox/seatbelt.rs`
- [Landlock Limits](https://github.com/akitaonrails/ai-jail/blob/master/src/sandbox/landlock.rs): `src/sandbox/landlock.rs`
- [Seccomp Filter](https://github.com/akitaonrails/ai-jail/blob/master/src/sandbox/seccomp.rs): `src/sandbox/seccomp.rs`
- [Filtered Egress](https://github.com/akitaonrails/ai-jail/blob/master/src/proxy.rs): `src/proxy.rs`
- [Secret Substitution](https://github.com/akitaonrails/ai-jail/blob/master/src/secret.rs): `src/secret.rs`

### Supervision

- [PTY Filtering](https://github.com/akitaonrails/ai-jail/blob/master/src/pty.rs): `src/pty.rs`
- [Status Bar](https://github.com/akitaonrails/ai-jail/blob/master/src/statusbar.rs): `src/statusbar.rs`
- [Audit Log](https://github.com/akitaonrails/ai-jail/blob/master/src/audit.rs): `src/audit.rs`

### Other components

- **User**
- **Agent Command**
- **Host OS**
- **Allowed Hosts**
- **GitHub**

## Connections

- User → Supervisor: invokes
- Supervisor → CLI Parser: parses
- Supervisor → Configuration: loads
- Configuration → Supervisor: returns settings
- Supervisor → Command Resolution: resolves command
- Supervisor → Sandbox Preparation: prepares policy
- Sandbox Preparation → Linux Bubblewrap: builds Linux sandbox
- Sandbox Preparation → macOS Seatbelt: builds macOS sandbox
- Linux Bubblewrap → Landlock Limits: applies limits
- Linux Bubblewrap → Seccomp Filter: applies filter
- Supervisor → Agent Bootstrap: generates setup
- Supervisor → Filtered Egress: starts proxy
- Filtered Egress → Allowed Hosts: dials allowed hosts
- Filtered Egress → Secret Substitution: substitutes credentials
- Supervisor → Agent Command: launches sandboxed
- Agent Command → Host OS: runs under restrictions
- Supervisor → PTY Filtering: interposes terminal
- Supervisor → Status Bar: sets up status
- Status Bar → GitHub: checks version
- Supervisor → Audit Log: records launch
- Filtered Egress → Audit Log: records verdicts
- User → Audit Log: verifies log