AI Coding Assistant Container

A script to launch a containerized development environment with Mistral Vibe or Claude Code AI coding assistants. The container comes pre-configured with Python, Node.js, development tools, and isolated workspace mounting.

Requirements

Container Runtime

• Podman (recommended, rootless) - Version 4.0+
  • Ubuntu/Debian: sudo apt-get install podman
  • Fedora: sudo dnf install podman
  • Arch: sudo pacman -S podman
• Docker (alternative) - Version 20.10+
  • Use --docker flag if you prefer Docker

System Resources

• Minimum: 8GB RAM, 4 CPUs
• Recommended: 16GB+ RAM, 8+ CPUs
• Disk space: 10GB+ for the image and workspace

API Keys

• Mistral Vibe: Mistral API key + VIBE CLI key
• Claude Code: Anthropic API key

---

Quick Start

Mistral Vibe

# Make script executable
chmod +x start-ai-container.sh

# Start and enter Mistral Vibe container
./start-ai-container.sh --mistral

# Use Docker instead of Podman
./start-ai-container.sh --mistral --docker

# With custom resources
./start-ai-container.sh --mistral -m 16g -c 8

Claude Code

# Make script executable
chmod +x start-ai-container.sh

# Start and enter Claude Code container
./start-ai-container.sh

# Use Docker instead of Podman
./start-ai-container.sh --docker

# With custom resources
./start-ai-container.sh -m 16g -c 8

---

Tutorials

Mistral Vibe Setup

1. Install a container runtime (if not installed):

   • Podman: sudo apt-get update && sudo apt-get install podman
   • Or Docker: Install Docker for your platform

2. Get your keys:

   • Visit https://console.mistral.ai/
   • Navigate to API Keys section and create/copy your Mistral API key
   • Get your VIBE CLI key from the Vibe CLI settings

3. Start the container and enter it:

   ./start-ai-container.sh --mistral
   

   The script automatically attaches you to the container shell.

4. Run Mistral Vibe inside the container:

   vibe
   

Claude Code Setup

1. Install a container runtime (if not installed):

   • Podman: sudo apt-get update && sudo apt-get install podman
   • Or Docker: Install Docker for your platform

2. Get your Anthropic API key:

   • Visit https://console.anthropic.com/
   • Navigate to API section
   • Create a new key and copy it

3. Start the container and enter it:

   ./start-ai-container.sh
   

   The script automatically attaches you to the container shell.

4. Run Claude Code inside the container:

   claude
   

---

Pre-Installed Tools

Category	Tools
Languages	Python 3.11, Node.js LTS, PHP, Rust
Package Managers	pip, uv, npm, composer
Version Managers	pyenv, nvm
Build Tools	cmake, make, autoconf, gcc, build-essential
Utilities	git, curl, wget, sqlite3
AI Assistants	Claude Code or Mistral Vibe

Pre-Configured Toolchains

The container image comes with several toolchains pre-installed and configured:

• nvm (Node Version Manager): Manage multiple Node.js versions
• pyenv (Python Environment Manager): Manage multiple Python versions with virtualenv support
• rustup (Rust toolchain installer): Rust compiler and cargo package manager
• uv (Ultra-fast Python package installer): Modern alternative to pip
• graphify (Graphifyy): Graph-based dependency management tool
• Composer: PHP dependency manager

Pre-Installed System Packages

Build and development packages included in the container:

• Compilers: gcc, g++, ccache, build-essential
• Build Systems: cmake, make, autoconf, automake, libtool, pkg-config
• Python Development: python3, python3-pip, python3-venv, python3-dev headers
• Development Libraries: libssl-dev, libsqlite3-dev, libreadline-dev, libbz2-dev, libffi-dev, liblzma-dev, zlib1g-dev
• PHP: php, php-sqlite3, php-pcov, php-mbstring, php-xml, php-gd, php-gmp
• Utilities: git, curl, wget, ca-certificates, bash

---

Command Reference

Basic Commands

Command	Description
./start-ai-container.sh	Start Claude container with defaults
./start-ai-container.sh --mistral	Start Mistral container
./start-ai-container.sh --docker	Use Docker instead of Podman
./start-ai-container.sh --rebuild	Rebuild image before starting
./start-ai-container.sh --stop	Stop running container
./start-ai-container.sh --restart	Restart existing container

Resource Options

Option	Description	Default
-m, --memory MEM	Memory limit	8g
-c, --cpus CPUS	CPU limit	4
-n, --name NAME	Container name	claude-code-workspace / mistral-code-workspace
-i, --image NAME	Image name	claude-code-podman / mistral-code-podman
-w, --workspace DIR	Workspace directory	./workspace

Utility Options

Option	Description
-h, --help	Show help message
-d, --debug	Enable debug output
--dry-run	Show configuration without starting
--show-docker	Print Dockerfile content

Examples

# Start Mistral with 16GB RAM and 8 CPUs
./start-ai-container.sh --mistral -m 16g -c 8

# Start Claude with custom workspace
./start-ai-container.sh -w ~/my-projects

# Start with custom container name
./start-ai-container.sh -n my-ai-workspace

# Rebuild and restart container
./start-ai-container.sh --rebuild --restart

# Stop running container
./start-ai-container.sh --stop

# View configuration without starting
./start-ai-container.sh --mistral --dry-run

# Show the generated Dockerfile
./start-ai-container.sh --mistral --show-docker

---

Container Management

All container management is handled by the start-ai-container.sh script.

Enter Running Container

Use the script to attach to an existing container:

./start-ai-container.sh

Or with Mistral:

./start-ai-container.sh --mistral

Stop Container

./start-ai-container.sh --stop

Restart Container

./start-ai-container.sh --restart

---

Workspace

• Default workspace: ./workspace (relative to script location)
• Mounted at: /workspace inside container
• Persists across container restarts
• Change with -w or --workspace option

# Use a different workspace directory
./start-ai-container.sh -w ~/projects/my-ai-projects

---

Security Features

• ✅ No root privileges (runs as current user)
• ✅ SELinux/AppArmor isolation
• ✅ Capability restrictions (only necessary caps)
• ✅ PID limit (200 processes max)
• ✅ User namespace isolation
• ✅ Read-only filesystem where possible
• ✅ Resource limits (memory, CPU)

---

Troubleshooting

Podman not installed

Error: Podman is not installed.

Fix: Install Podman as shown in Requirements section.

Docker not installed but --docker specified

Error: Docker is not installed but --docker was specified.

Fix: Install Docker or use Podman (remove --docker flag).

API key not set

Warning: MISTRAL_API_KEY / ANTHROPIC_API_KEY not set.

Fix: Set the environment variable before running:

export MISTRAL_API_KEY="your-key-here"
# or
export ANTHROPIC_API_KEY="your-key-here"

Or enter it when prompted during container startup.

Port conflicts

Ensure no other containers are using the same name or ports.

Build failures

# Rebuild with debug output
./start-ai-container.sh --rebuild --debug

---

Environment Variables

Variable	Purpose	Required
MISTRAL_API_KEY	Mistral Vibe authentication	Yes (if using Mistral)
ANTHROPIC_API_KEY	Claude Code authentication	Yes (if using Claude)

Set them before running the script:

export MISTRAL_API_KEY="your-mistral-key"
./start-ai-container.sh --mistral

# Or for Claude
export ANTHROPIC_API_KEY="your-anthropic-key"
./start-ai-container.sh

---

Customization

Persistent Configuration

API keys and configuration are persisted automatically:

• Mistral: Configuration stored at /home/mistral/.vibe
• Claude: Configuration stored at /home/claude/.claude
• Python environments: Persisted for reuse

These persist across container rebuilds.

Rebuild Container

To update the container image (e.g., after script updates):

./start-ai-container.sh --rebuild

Change Default User

The container runs as a non-root user:

• Claude: claude user
• Mistral: mistral user

---

Notes

• The script starts the container and automatically attaches you to its shell
• Use Ctrl+D or exit to leave the container shell (container keeps running)
• Use --stop to stop and remove the container
• Workspace data persists in the host directory
• Python environments are persisted for reuse across container sessions