introdus runs your dev environment — including AI coding agents like Claude
Code — inside a network-hardened, rootless podman container, so a
supply-chain compromise of your tooling is confined to the container's blast
radius instead of reaching your real machine.
The core guarantee: the workload runs as a non-root dev user with no direct
internet egress. Its only way out is a loopback hostname-allowlist proxy,
backed by a default-deny nft filter it cannot touch. A startup self-check aborts
launch if the filter isn't actually enforcing. See
Egress filtering and
Container hardening.
- Dev machine — the laptop you sit at. Attach VS Code over SSH, drive the agent, receive native notifications.
- Container host — a remote KVM/VPS or the same laptop. Runs rootless podman and the notification service.
- Dev container — your repo clone + the agent, with egress filtering enforced inside.
Run it all on one laptop, or push the container host onto a beefy remote box and keep your laptop thin — the same control path and notifications work either way. See Architecture for the full shape.
Build the binary once and put it on PATH — do this on the container host
(the box that runs podman) — then work per-project:
cargo build --release # -> target/release/introdus (one binary)
./target/release/introdus install # copies it onto ~/.local/bin (PATH)
mkdir ~/myproject && cd ~/myproject
introdus # first run: setup wizard, then launchesThe first introdus in a project runs the setup wizard
(repo + deploy key + agent picks), writes .introdus/config.env, and launches.
Later runs attach straight to that project's tmux session +
control panel.
Subcommands: introdus [launch], up, menu, verify, recreate, reset,
update, rebuild-base, notify-host, notify-listen, send-files,
install. Most are also on the control panel.
| Feature | What it does |
|---|---|
| Egress filtering | Default-deny nft filter + loopback hostname-allowlist proxy + fail-closed startup self-check — the workload can reach only the hosts you allowlist. |
| Container hardening | Rootless podman, --cap-drop=ALL + a minimal add-back set, no-new-privileges, and a read-only per-repo deploy key. |
| Feature | What it does |
|---|---|
| Setup wizard & configuration | First-run wizard writes a hand-editable per-project config; full .env reference. |
| Control panel | A persistent two-pane TUI to drive lifecycle and every host-side utility. |
| Coding agents | Pick which agents install (Claude, Codex, Antigravity, Opencode, Pi, Kilocode) — nothing baked into the image, installs sandboxed. |
| Claude remote control | On by default — pair from claude.ai/code or your phone and drive the agent, no inbound port. |
| Paseo orchestrator | Optional — run agents under a daemon and drive them from a phone/desktop/web client. |
| Attach VS Code | A full VS Code window whose filesystem, terminal, and extensions live inside the container. |
| Send files | A dual-pane TUI (laptop ⇆ container) to copy files into a local or remote container. |
| Notifications | "Task done / awaiting input" as a native desktop popup + sound, tunnelled back from a remote host; optional phone push. |
| Feature | What it does |
|---|---|
| Persistence, lifecycle & updates | Per-project volume survives restarts; recreate / reset / destroy; in-place update. |
| Public webapp tunnel | Opt-in Cloudflare quick tunnel to expose the webapp on a public *.trycloudflare.com URL. |
| Launch hooks | Run your own root/dev setup on every container start — dev server, migrations, services. |
| Host data & extra ports | Read-only host-dir mount + extra 127.0.0.1-bound published ports for local tools. |
| Running on a remote host | Push the container host to a remote Linux box and drive it from your laptop. |
| Architecture | The shape of the system, image/container naming, and the source map. |
On the container host (where podman runs):
- Linux rootless podman (the only supported configuration):
podman4.4+,pasta(apt install passt),tmux, kernel ≥ 5.x with cgroup v2. No host nftables, no systemd-host requirement, no sudo — the egress filter runs inside each container.
On your dev machine (laptop) — only if it's separate from the host:
- An SSH client with key access to the host (passphrase-less, or an agent
reachable from your
systemd --usersession — the tunnel runsBatchMode=yes). - VS Code with the Remote-SSH and Dev Containers extensions.
autossh(recommended) for a self-healing reverse tunnel if you want notifications forwarded from a remote host.
Repo access: a deploy key with commit + pull access to the repo, scoped to that single repo. It lives on the container host, mounted read-only.
Hardened hosts often ship
AllowTcpForwarding no, which blocks both remote notifications and VS Code Remote-SSH. The narrow per-usersshdallowance is in Notifications → host SSH-forwarding requirement.
The threat model, the uid-segregated nft rules, IP-bypass protection, the DNS-tunnelling residual, the capability set, deploy-key handling, and the notification trust boundary are documented across Egress filtering, Container hardening, and the canonical security model.
A tip of the hat to Greg Egan's novel Diaspora. In it, the Introdus is the process by which a flesher — a flesh-and-blood human — is scanned and migrated into software, taking up life inside a polis: a self-contained digital environment, insulated from the hazards of the physical world.
The metaphor fit too well to pass up. This tool does the small, mundane version: it moves your dev environment — your repo and the AI agents you point at it — off your real machine and into a hardened, egress-filtered container, where whatever they get up to stays contained.