Tauri Podman Terminal

A desktop application built with Tauri and React that provides a terminal interface for managing Podman containers.

Features

• ✅ Check and initialize Podman installation automatically
• 🐳 Create and manage containers with a visual interface
• 💻 Full terminal emulation with PTY (Pseudo-Terminal) support
• ⚡ Real-time command execution and output streaming
• 🎨 Built-in terminal emulator using xterm.js
• 🔧 Support for interactive programs (vim, htop, Claude Code, etc.)
• 📋 Container logs viewer with syntax highlighting
• ⌨️ Keyboard shortcuts for common actions
• 🌍 Cross-platform support (macOS, Linux, Windows)

Prerequisites

macOS

1. Install Podman using Homebrew:

   brew install podman

2. On Apple Silicon Macs, you may be prompted to install Rosetta 2 for compatibility with some container images.

3. The application will automatically initialize the Podman machine on first run.

Linux

1. Install Podman using your distribution's package manager:

   # Ubuntu/Debian
   sudo apt-get update
   sudo apt-get install podman
   
   # Fedora/RHEL
   sudo dnf install podman
   
   # Arch Linux
   sudo pacman -S podman

Windows

1. Download and install Podman from the official website

Development Setup

1. Install dependencies:

   bun install

2. Run in development mode:

   bun run tauri dev

3. Build for production:

   bun run tauri build

Usage

1. First Launch: The application will check for Podman installation and initialize the Podman machine if needed.

2. Creating Containers:

   • Enter a container name in the sidebar
   • Select a base image from the dropdown:
     • Node.js Images (Recommended for Claude Code):
       • Node.js 22 LTS (Latest stable with npm 10+)
       • Node.js 20 LTS (Current LTS)
       • Node.js 20 Alpine (Lightweight)
     • Multi-Language Dev Containers:
       • Universal Dev Container (Node, Python, Go, Rust, etc.)
       • Gitpod Full (Complete development environment)
     • Base OS Images:
       • Ubuntu 24.04 LTS, Ubuntu 22.04 LTS
       • Debian 12 (Bookworm)
       • Alpine Latest (Minimal)
     • Other Languages: Python 3.12, Rust, Go 1.22
   • Click "Create Container" to create with optional dev tools

3. Managing Containers:

   • Select a container to make it active
   • Use the command bar at the bottom to execute commands
   • Stop or remove containers using the action buttons

4. Terminal Interface:

   • The integrated terminal shows real-time output from container commands
   • Supports clickable links and proper terminal formatting
   • Toggle between PTY mode (for interactive programs) and command mode (for one-off commands)

Terminal Modes

PTY Mode (Full Terminal)

Enable PTY mode by checking "Full Terminal Mode (PTY)" at the bottom of the terminal. This mode:

• Provides a full interactive terminal session inside the container
• Supports terminal programs like vim, nano, htop, Claude Code
• Handles special keys (arrow keys, Ctrl+C, etc.) properly
• Maintains terminal state between commands
• Required for any interactive CLI applications

Command Mode (Default)

When PTY mode is disabled:

• Execute individual commands using the command bar
• Best for quick one-off commands
• Each command runs in isolation
• Output is displayed in the terminal but no input is accepted

Working with Claude Code

Claude Code requires PTY mode for the best experience:

1. Create a container with a Node.js image (recommended: Node.js 22 LTS)
2. Select the container and enable PTY mode
3. Install Claude Code:

   npm install -g claude-code

4. Initialize Claude Code:

   claude init

5. Start using Claude Code normally with full terminal support

Keyboard Shortcuts

Container Management

• Cmd/Ctrl + R - Refresh containers list
• Cmd/Ctrl + 1-9 - Quick select container by index
• Cmd/Ctrl + K - Focus container name input

Terminal Control

• Cmd/Ctrl + P - Toggle PTY mode
• Cmd/Ctrl + L - Clear terminal
• ESC - Exit log view

Help

• Cmd/Ctrl + ? - Show keyboard shortcuts help

Architecture

For a comprehensive technical deep dive into how this application works, including:

• How Podman integration is implemented
• Terminal emulation with xterm.js
• PTY (Pseudo-Terminal) implementation details
• Event system and IPC communication
• Container lifecycle management
• Data flow diagrams

Please see ARCHITECTURE.md

Quick Overview

• Frontend: React + TypeScript with xterm.js for terminal emulation
• Backend: Rust-based Tauri framework for native functionality
• Container Management: Uses Podman CLI commands (future: Podman socket API)
• Communication: Tauri's command and event system for IPC

Troubleshooting

PTY Mode Issues

• Double character output: Make sure you're running the latest version. This was fixed in recent updates.
• Terminal not responding: Try disabling and re-enabling PTY mode, or restart the container.
• Special keys not working: Ensure PTY mode is enabled for proper key handling.

Container Issues

• Container won't start: Check Podman machine status with podman machine list in your system terminal
• Permission denied errors: Ensure the volume mount permissions are correct
• Can't connect to container: Verify the container is running using the refresh button

Platform-Specific Issues

• macOS Apple Silicon: Some container images may require architecture-specific versions. Use multi-arch images or specify --platform linux/amd64 if needed.
• Windows: Ensure Podman Desktop is installed and WSL2 is properly configured
• Linux: Check that your user is in the appropriate groups for Podman rootless mode

Known Limitations

• Initial Podman machine setup may take several minutes on first run
• Alpine Linux containers have limited compatibility with some tools (e.g., Claude Code) due to BusyBox utilities. Use Ubuntu or Debian-based images for full compatibility.
• Container logs are not yet viewable in the UI (use podman logs <container> in command mode as a workaround)

Documentation

• ARCHITECTURE.md - Technical deep dive into the implementation
• CLAUDE.md - Development guidelines for Claude Code
• Code Comments - Inline documentation references the architecture docs

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

When contributing, please:

1. Read the ARCHITECTURE.md to understand the codebase
2. Follow the existing code style and patterns
3. Add tests for new functionality
4. Update documentation as needed

License

This project is open source and available under the MIT License.