Podman Runtime

The Podman runtime provides a container-based development environment for workspaces. It creates an isolated environment with all necessary tools pre-installed and configured.

Container Image¶

Base Image: registry.fedoraproject.org/fedora:latest

The Podman runtime builds a custom container image based on Fedora Linux, providing a stable and up-to-date foundation for development work.

Installed Packages¶

The runtime includes a comprehensive development toolchain:

Core Utilities:
which - Command location utility
procps-ng - Process management utilities
wget2 - Advanced file downloader
Development Tools:
@development-tools - Complete development toolchain (gcc, make, etc.)
jq - JSON processor
gh - GitHub CLI
Language Support:
golang - Go programming language
golangci-lint - Go linter
python3 - Python 3 interpreter
python3-pip - Python package manager

User and Permissions¶

The container runs as a non-root user named agent with the following configuration:

User: agent
UID/GID: Matches the host user's UID and GID for seamless file permissions
Home Directory: /home/agent

Sudo Permissions:

The agent user has limited sudo access with no password required (NOPASSWD) for:

Package Management:
/usr/bin/dnf - Install, update, and manage packages
Process Management:
/bin/nice - Run programs with modified scheduling priority
/bin/kill, /usr/bin/kill - Send signals to processes
/usr/bin/killall - Kill processes by name

All other sudo commands are explicitly denied for security.

AI Agent¶

Claude Code is installed as the default AI agent using the official installation script from claude.ai/install.sh. This provides:

Full Claude Code CLI capabilities
Integrated development assistance
Access to Claude's latest features

The agent runs within the container environment and has access to the mounted workspace sources and dependencies.

Working Directory¶

The container's working directory is set to /workspace/sources, which is where your project source code is mounted. This ensures that the agent and all tools operate within your project context.

Example Usage¶

# Register a workspace with the Podman runtime
kortex-cli init /path/to/project --runtime podman --agent claude

User Experience:

When you register a workspace with the Podman runtime, you'll see progress feedback for each operation:

⠋ Creating temporary build directory
✓ Temporary build directory created
⠋ Generating Containerfile
✓ Containerfile generated
⠋ Building container image: kortex-cli-myproject
✓ Container image built
⠋ Creating container: myproject
✓ Container created

The init command will: 1. Create a temporary build directory - with progress spinner 2. Generate a Containerfile with the configuration above - with progress spinner 3. Build a custom image (tagged as kortex-cli-<workspace-name>) - with progress spinner 4. Create a container with your source code mounted - with progress spinner

After registration, you can start the workspace:

# Start the workspace
kortex-cli start <workspace-id>

Note: When using --output json, all progress spinners are hidden to avoid polluting the JSON output.

Customizing Podman Runtime Configuration¶

The Podman runtime is fully configurable through JSON files. When you first use the Podman runtime, default configuration files are automatically created in your storage directory.

Configuration Location:

$HOME/.kortex-cli/runtimes/podman/config/
├── image.json    # Base image configuration
└── claude.json   # Agent-specific configuration

Or if using a custom storage directory:

<storage-dir>/runtimes/podman/config/

Base Image Configuration (`image.json`)¶

Controls the container's base image, packages, and sudo permissions.

Structure:

{
  "version": "latest",
  "packages": [
    "which",
    "procps-ng",
    "wget2",
    "@development-tools",
    "jq",
    "gh",
    "golang",
    "golangci-lint",
    "python3",
    "python3-pip"
  ],
  "sudo": [
    "/usr/bin/dnf",
    "/bin/nice",
    "/bin/kill",
    "/usr/bin/kill",
    "/usr/bin/killall"
  ],
  "run_commands": []
}

Fields:

version (required) - Fedora version tag
Examples: "latest", "40", "41"
The base registry registry.fedoraproject.org/fedora is hardcoded and cannot be changed
packages (optional) - DNF packages to install
Array of package names
Can include package groups with @ prefix (e.g., "@development-tools")
Empty array is valid if no packages needed
sudo (optional) - Binaries the agent user can run with sudo
Must be absolute paths (e.g., "/usr/bin/dnf")
Creates a single ALLOWED command alias in sudoers
Empty array disables all sudo access
run_commands (optional) - Custom shell commands to run during image build
Executed as RUN instructions in the Containerfile
Run before agent-specific commands
Useful for additional setup steps

Agent Configuration (`claude.json`)¶

Controls agent-specific packages and installation steps.

Structure:

{
  "packages": [],
  "run_commands": [
    "curl -fsSL --proto-redir '-all,https' --tlsv1.3 https://claude.ai/install.sh | bash",
    "mkdir -p /home/agent/.config"
  ],
  "terminal_command": [
    "claude"
  ]
}

Fields:

packages (optional) - Additional packages specific to this agent
Merged with packages from image.json
Useful for agent-specific dependencies
run_commands (optional) - Commands to set up the agent
Executed after image configuration commands
Typically used for agent installation
terminal_command (required) - Command to launch the agent
Must have at least one element
Can include flags: ["claude", "--verbose"]

Applying Configuration Changes¶

Configuration changes take effect when you register a new workspace with init. The Containerfile is generated and the image is built during workspace registration, using the configuration files that exist at that time.

To apply new configuration:

Edit the configuration files:

# Edit base image configuration
nano ~/.kortex-cli/runtimes/podman/config/image.json

# Edit agent configuration
nano ~/.kortex-cli/runtimes/podman/config/claude.json

Register a new workspace (this creates the Containerfile and builds the image):
```
kortex-cli init /path/to/project --runtime podman --agent claude
```
Start the workspace:
```
kortex-cli start <workspace-id>
```

Notes:

The first init command using Podman creates default config files automatically
Config files are never overwritten once created - your customizations are preserved
The Containerfile and image are built during init, not start
Each workspace's image is built once using the configuration at registration time
To rebuild a workspace with new config, remove and re-register it
Validation errors in config files will cause workspace registration to fail with a descriptive message
The generated Containerfile is automatically copied to /home/agent/Containerfile inside the container for reference