linpodx

Containers, AI sandboxes, GUI apps. Native on Linux.

Linux-native container management with a Rust CLI, desktop GUI,
AI-agent sandboxing, and lightweight multi-distro environments.

# Latest stable release (default)
curl -fsSL https://raw.githubusercontent.com/kernalix7/linpodx/main/install.sh | bash

# Latest main HEAD (development; may be unstable)
curl -fsSL https://raw.githubusercontent.com/kernalix7/linpodx/main/install.sh | bash -s -- --main

# Uninstall (keeps local linpodx data; pass --purge to wipe data/config)
curl -fsSL https://raw.githubusercontent.com/kernalix7/linpodx/main/uninstall.sh | bash -s -- --confirm

Works on

_{English · 한국어 · Changelog · Architecture · Contributing · Security}

Status: Pre-alpha

linpodx is preparing its first v0.1.0 release. Phase 0..17 implementation is in-tree: local daemon, CLI, iced GUI, AI-agent sandbox, audit log, snapshots, host-stdio bridge, GUI passthrough, multi-distro templates, remote daemon, plugin hooks, cluster scaffolding, and snapshot encryption hardening. The current release gate is conservative: 829 unit tests pass, 54 host/runtime-dependent integration tests are ignored by default, and the project still expects sharp edges outside development workstations.

No Docker Desktop VM. linpodx talks to rootless Podman on Linux, keeps the daemon local by default, and exposes the same container state through CLI, GUI, and event subscriptions.

Why linpodx

Tool	Gap linpodx targets
Docker Desktop	Heavy Linux story, license friction, weak desktop passthrough, no AI-agent sandbox model
Rancher Desktop	Kubernetes-first; too much machinery for daily local container work
Podman Desktop	Strong general container UI, but not built around sandbox approvals, snapshots, or multi-distro shells
distrobox / toolbx	Great lightweight environments, but CLI-first and light on policy/audit controls
Full VMs	Strong isolation, but slower boot and heavier CPU/RAM/storage footprint

linpodx bundles a desktop container manager, a safe AI-agent execution sandbox, and GUI-integrated Linux environments into one Linux-native toolchain.

Use cases

Desktop container management — daily container, image, volume, and network work through a CLI and GUI backed by the same daemon.
AI-agent sandbox execution — run risky agentic shell workflows in containers with approval gates, audit trails, resource limits, snapshots, and rollback.
Lightweight distro shells — keep Ubuntu, Fedora, Arch, Debian, Alpine, and NixOS environments side-by-side without full VMs.
GUI-integrated containers — forward Wayland/X11, audio, GPU, clipboard, DBus, theme, and HiDPI state into selected containers.
Local-first remote access — stay Unix-socket local by default, then opt into WebSocket, bearer tokens, mTLS, and cert pinning when needed.

Quick install

One-liner, any supported Linux distro:

curl -fsSL https://raw.githubusercontent.com/kernalix7/linpodx/main/install.sh | bash

Install from a local checkout or offline source tree:

git clone https://github.com/kernalix7/linpodx.git
cd linpodx
./install.sh --source .

Optional L4 egress helper capabilities:

./install.sh --source . --setcap-helper

Uninstall:

curl -fsSL https://raw.githubusercontent.com/kernalix7/linpodx/main/uninstall.sh | bash -s -- --confirm

Use --purge to remove local linpodx data/config as well. Podman containers, images, volumes, Rust, Podman, and system packages are left alone.

Choose a version

The installer follows the winpodx release posture: default to the latest published release, make main and arbitrary refs explicit.

# Latest stable release (default)
curl -fsSL https://raw.githubusercontent.com/kernalix7/linpodx/main/install.sh | bash

# Latest main HEAD
curl -fsSL https://raw.githubusercontent.com/kernalix7/linpodx/main/install.sh | bash -s -- --main

# Specific tag, branch, or commit
curl -fsSL https://raw.githubusercontent.com/kernalix7/linpodx/main/install.sh | bash -s -- --ref v0.1.0

# Env-var equivalents, useful under curl | bash
LINPODX_REF=main   curl -fsSL https://raw.githubusercontent.com/kernalix7/linpodx/main/install.sh | bash
LINPODX_REF=v0.1.0 curl -fsSL https://raw.githubusercontent.com/kernalix7/linpodx/main/install.sh | bash

Offline / source install

# Copy from a local clone instead of git clone
./install.sh --source /media/usb/linpodx

# Skip distro dependency installation; fail early if tools are missing
./install.sh --skip-deps

# Build CLI + daemon only
./install.sh --source . --no-gui

# Skip the privileged L4 egress helper
./install.sh --source . --no-helper

Environment variables mirror the flags: LINPODX_SOURCE, LINPODX_REF, LINPODX_SKIP_DEPS, LINPODX_NO_GUI, LINPODX_NO_HELPER, LINPODX_INSTALL_DIR, and LINPODX_BIN_DIR.

Prerequisites

Linux x86_64 or aarch64, with Wayland or X11 for the desktop GUI.
Podman 4.6.0 or newer, rootless preferred.
Rust 1.85+ for source builds. rust-toolchain.toml pins the workspace baseline.
rustfmt and clippy for development.
Optional: nftables, util-linux / nsenter, and setcap for the privileged L4 egress helper.

The helper is intentionally opt-in because it needs CAP_NET_ADMIN and CAP_SYS_ADMIN:

sudo setcap cap_net_admin,cap_sys_admin+ep ~/.local/bin/linpodx-netfilter-helper
sudo install -d -m 0755 /run/linpodx
linpodx-netfilter-helper --daemon-uid "$(id -u)" &

Without the helper, DNS allowlist filtering still works and network egress apply reports helper_applied: false.

Launch

linpodx-daemon                 # Start the local Unix-socket daemon
linpodx ps --all               # Query containers from the CLI
linpodx-gui                    # Open the desktop dashboard

The daemon binds $XDG_RUNTIME_DIR/linpodx.sock by default, falling back to /tmp/linpodx-$UID.sock.

Key features

Desktop container manager

Container lifecycle: create, start, stop, restart, pause, remove
Image, volume, and network management through one CLI/API surface
Live event stream for daemon state changes
iced desktop GUI with containers, images, volumes, networks, audit, snapshots, sessions, plugins, and cluster views
JSON/table output for shell-friendly workflows

AI-agent sandbox

YAML sandbox profiles with capability drops, read-only rootfs, mount allowlists, and network modes
Approval gates for sensitive actions such as host mounts, capability adds, and bridge tool calls
Tamper-evident audit log with hash chaining
Session timeline that merges container lifetime, audit events, and bridge events
Snapshot before/after workflows for rollback-friendly experiments

GUI passthrough

Wayland and X11 socket forwarding
PipeWire / PulseAudio audio passthrough
GPU access through DRI-oriented device grants
DBus session bus, clipboard, HiDPI, and theme environment propagation
Per-profile and per-container passthrough configuration

Multi-distro environments

Ubuntu, Fedora, Arch, Debian, Alpine, and NixOS templates
Optional systemd inside supported container profiles
VM mode with persistent home volume, auto-restart, and host UID/GID mapping
Template inspection, build, create, enter, and remove commands
Lighter than a full VM for day-to-day Linux environment testing

Snapshots & storage

Podman commit snapshots with list, rollback, remove, prune, and async job APIs
Branch and diff helpers for comparing snapshot state
Overlayfs and BTRFS backend scaffolding
Snapshot encryption and key-rotation plumbing
Metrics and audit hooks for long-running jobs

Remote, plugins, and cluster

Local Unix socket by default, optional WebSocket remote daemon
mTLS, token auth, and client certificate pinning for remote access
Wasmtime plugin registry with signed-plugin verification
Cluster gossip, membership, and Raft state-machine scaffolding
Kubernetes read/write adapter surface for workstation automation

See CHANGELOG.md for the full v0.1.0 feature list.

Common workflows

Container lifecycle:

linpodx-daemon &
linpodx run --name demo docker.io/library/alpine:latest sleep 30
linpodx ps --all
linpodx logs demo
linpodx rm -f demo

Sandbox profile:

mkdir -p ~/.config/linpodx/profiles
cp examples/profiles/read-only-net-disabled.yaml ~/.config/linpodx/profiles/
linpodx sandbox reload
linpodx run --sandbox read-only-net-disabled --name probe alpine sleep 5
linpodx sandbox audit --profile read-only-net-disabled

Snapshots:

linpodx run --name work alpine sleep 600
linpodx snapshot create --label before-experiment work
linpodx snapshot list
linpodx snapshot rollback --new-name work-restored 1

Multi-distro shell:

linpodx distro list
linpodx distro build --kind ubuntu --include git,curl,python3
linpodx distro create --kind ubuntu --vm-mode my-ubuntu
linpodx distro enter my-ubuntu

Remote daemon:

linpodx-daemon --socket /tmp/lp.sock --remote-listen 127.0.0.1:8443 --remote-token dev
linpodx --remote ws://127.0.0.1:8443/ipc --token dev ps --all

Remote daemon

Run a daemon with a WebSocket listener when another process or host needs access to the same JSON-RPC surface:

linpodx-daemon \
  --socket /tmp/lp.sock \
  --remote-listen 127.0.0.1:8443 \
  --remote-token hunter2

linpodx --remote ws://127.0.0.1:8443/ipc --token hunter2 version
linpodx --remote 127.0.0.1:8443 --token hunter2 ps

Environment variables work too:

export LINPODX_REMOTE=ws://daemon.internal:8443/ipc
export LINPODX_REMOTE_TOKEN=hunter2
linpodx ps

Keep plain ws:// behind loopback, a firewall, or an SSH tunnel. For untrusted networks, use TLS and client certificates.

mTLS and client pinning

Generate local test certificates:

linpodx daemon cert generate --out ./certs

Start a remote daemon with TLS and client-certificate verification:

linpodx-daemon \
  --socket /tmp/lp.sock \
  --remote-listen 127.0.0.1:8443 \
  --remote-token hunter2 \
  --tls-cert ./certs/server.pem \
  --tls-key ./certs/server-key.pem \
  --client-ca ./certs/ca.pem \
  --pin-clients

Then connect with the client certificate:

linpodx \
  --remote wss://127.0.0.1:8443/ipc \
  --token hunter2 \
  --client-cert ./certs/client.pem \
  --client-key ./certs/client-key.pem \
  --client-ca ./certs/ca.pem \
  ps --all

Pinned clients are managed through linpodx daemon pin-client {add,list,remove,tofu}. TOFU enrollment can be enabled for controlled first-contact windows, then disabled once the expected clients are pinned.

Web UI

The daemon can serve a browser UI on the same listener as the remote /ipc endpoint:

linpodx-daemon \
  --socket /tmp/lp.sock \
  --remote-listen 127.0.0.1:8443 \
  --remote-token hunter2

Open http://127.0.0.1:8443/ui/ and provide the bearer token. The Web UI shares the remote listener's security posture, so use mTLS for untrusted networks.

The Leptos/WASM UI is opt-in at build time:

rustup target add wasm32-unknown-unknown
cargo install wasm-bindgen-cli
LINPODX_WASM=1 cargo build -p linpodx-daemon --release

Without LINPODX_WASM=1, the daemon serves the lightweight built-in fallback UI. For air-gapped terminal modals, vendor xterm.js assets at build time:

LINPODX_VENDOR_XTERM=1 cargo build --release -p linpodx-daemon

Security profiles

Compile a sandbox profile's seccomp and AppArmor artifacts:

linpodx sandbox profile compile read-only-net-disabled --secprofile-out /tmp/secprofiles

When the profile has syscall_allowlist or apparmor_extra, the daemon applies the generated files through Podman's --security-opt flags. Hosts without apparmor_parser keep the seccomp half and skip AppArmor.

SELinux profile synthesis is available on hosts with checkmodule, semodule_package, semodule, and SELinux in enforcing/permissive mode. Set selinux_type: <type_name> in a sandbox profile to synthesize, package, install, and apply a per-profile label. Hosts without SELinux tooling fall back gracefully.

Interactive exec

Interactive PTY mode is available over the WebSocket remote listener:

linpodx --remote 127.0.0.1:8443 --token hunter2 \
  exec -it <container_id> -- bash

The daemon allocates a PTY pair, the CLI switches the local terminal into raw mode, and /pty/<bridge_id> carries the interactive stream. Each bridge is single-use and closes when the process exits or the WebSocket disconnects.

Kubernetes adapter

linpodx can call the standard Kubernetes discovery chain (KUBECONFIG, ~/.kube/config, or in-cluster service account) through the daemon:

linpodx k8s pod create ./pod.yaml -n my-ns
cat pod.yaml | linpodx k8s pod create - -n my-ns
linpodx k8s pod delete hello -n my-ns
linpodx k8s ns create my-ns
linpodx k8s scale web --replicas 3 -n prod

Cluster-mutating operations are recorded in the local audit log.

Benchmarks

Criterion benches live under the relevant crates and have a baseline in bench-results/:

cargo bench -p linpodx-runtime --bench snapshot --bench container --bench cgroup \
  -p linpodx-mcp --bench policy \
  -p linpodx-plugin --bench invoke -- --quick

The bench workflow compares quick-mode means against the checked-in baseline and flags large regressions without failing the build.

Roadmap

Version	Focus
`v0.1.x`	Stabilize the local daemon, installer, GUI dashboard, and core sandbox flows
`v0.2.x`	Packaging, systemd user units, Web UI polish, and remote daemon hardening
`v0.3.x`	More distro workflows, richer GUI actions, and plugin author ergonomics
`v0.4.x`	Multi-host/cluster usability and stronger operational recovery

Non-goals

Replacing Kubernetes, Rancher, k3s, or k0s.
First-class Windows/macOS hosts; linpodx is Linux-native.
Hiding Podman. The runtime remains visible, debuggable, and compatible with normal Podman workflows.
Removing user judgment from sensitive operations. Approval gates and audit logs are part of the product, not a temporary limitation.

Architecture

linpodx CLI / GUI / Web UI
          |
          | JSON-RPC 2.0 over Unix socket or WebSocket
          v
linpodx-daemon
  |-- Podman runtime adapter
  |-- sandbox policy manager
  |-- audit/event/session/snapshot managers
  |-- plugin registry
  |-- remote daemon transport
  `-- cluster / distro / passthrough adapters
          |
          v
Rootless Podman + Linux desktop integrations

Crate	Purpose
`linpodx-cli`	`linpodx` command-line client
`linpodx-daemon`	Unix-socket API server, dispatcher, event bus, remote transport
`linpodx-gui`	iced desktop dashboard
`linpodx-runtime`	Podman wrapper, images, volumes, networks, snapshots, passthrough
`linpodx-sandbox`	profiles, approvals, audit, sessions, snapshot triggers
`linpodx-common`	shared IPC, state, errors, database migrations
`linpodx-distro`	distro templates and VM-mode helpers
`linpodx-plugin`	Wasmtime plugin loading, manifests, signing, registry
`linpodx-cluster`	gossip, Raft, Kubernetes adapter
`linpodx-webui`	browser UI bundle for the remote daemon

Documentation

Document	What's inside
CHANGELOG.md	v0.1.0 release notes and pre-release phase history
docs/README.ko.md	Korean overview
docs/INSTALL.md	Installer, uninstall, offline/source install, prerequisites
docs/RELEASE.md	Versioning, tag discipline, release checklist
docs/architecture.md	System architecture, data flow, trust boundaries
docs/scenarios/ai-agent-sandbox.md	Sandbox workflow
docs/scenarios/gui-app.md	GUI passthrough scenario
docs/scenarios/multi-distro-shell.md	Multi-distro shell scenario
docs/scenarios/plugin-author.md	Plugin author workflow
docs/scenarios/remote-daemon.md	Remote daemon workflow
CONTRIBUTING.md	Development setup and workflow
SECURITY.md	Security disclosure process

Supported distros

Distro	Package manager	Status
openSUSE Tumbleweed / Leap / Slowroll	zypper	Supported
Fedora / RHEL family / AlmaLinux / Rocky	dnf	Supported
Debian / Ubuntu / Linux Mint / Pop!_OS	apt	Supported
Arch / Manjaro / EndeavourOS	pacman	Supported

Podman 4.6.0 or newer is required. Rust 1.85+ is required for source builds.

Testing

cargo +1.85 fmt --all -- --check
cargo +1.85 clippy --workspace --all-targets --all-features -- -D warnings
cargo +1.85 build --workspace
cargo +1.85 test --workspace
cargo +1.85 doc --workspace --no-deps

Ignored integration tests touch host runtimes, networking helpers, Podman lifecycle, or external services:

cargo +1.85 test --workspace -- --ignored --test-threads=1

Development

git clone https://github.com/kernalix7/linpodx.git
cd linpodx
rustup toolchain install 1.85 --component clippy --component rustfmt
cargo +1.85 build --workspace

Run from a checkout without installing:

cargo +1.85 run -p linpodx-daemon
cargo +1.85 run -p linpodx-cli -- ps --all
cargo +1.85 run -p linpodx-gui

Security

linpodx defaults to rootless Podman and local Unix-socket IPC. Optional features such as the netfilter helper, remote daemon listener, mTLS, certificate pinning, host mounts, and plugin loading expand the trust boundary; enable them deliberately and review SECURITY.md for reporting guidance.

License

MIT - Kim DaeHyun (kernalix7@kodenet.io)

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
.cargo		.cargo
.github		.github
bench-results		bench-results
bench-tools		bench-tools
crates		crates
docs		docs
examples		examples
tests		tests
.gitattributes		.gitattributes
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
deny.toml		deny.toml
install.sh		install.sh
rust-toolchain.toml		rust-toolchain.toml
uninstall.sh		uninstall.sh

Folders and files

Latest commit

History

Repository files navigation

linpodx

Containers, AI sandboxes, GUI apps. Native on Linux.

Works on

Status: Pre-alpha

Why linpodx

Use cases

Quick install

Choose a version

Offline / source install

Prerequisites

Launch

Key features

Common workflows

Remote daemon

mTLS and client pinning

Web UI

Security profiles

Interactive exec

Kubernetes adapter

Benchmarks

Roadmap

Non-goals

Architecture

Documentation

Supported distros

Testing

Development

Security

License

About

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages