marcioreisjr/linux-ai-agents repository overview

⁠Running AI Agents in Containers

This project provides a containerized environment for running AI agents (such as Claude Code, Gemini, etc.) with limited access to the host system.

⁠Why Use Containers for AI Agents?

There are growing security concerns surrounding AI agents, particularly regarding:

• Prompt injection attacks that could manipulate agent behavior
• Malicious code execution via compromised inputs or novel attack vectors
• Unauthorized access to sensitive host system resources

By running agents in containers, you create an isolation layer that:

• Limits potential damage if an agent is compromised
• Provides controlled access to host resources via volume mounts
• Enables easy cleanup and reset of the agent environment

Trade-offs:

• Agents have limited access to system tools by default
• Additional tools must be explicitly installed, increasing container size
• Some performance overhead from containerization

⁠Prerequisites

• Docker installed on your system
• Basic familiarity with Docker commands
• Terminal/command line access

⁠Quick Start

⁠1. Build the Docker Image

docker build -t linux-ai-agents .

⁠2. Create and Start a Persistent Container

# Create the container with volume mount
docker create -it --name linux-ai-agents \
    -v ./:/src \
    linux-ai-agents

# Start the container
docker start -ai linux-ai-agents

Volume Mount: The /src directory in the container enables file sharing between your host and the container. It maps to the directory where you ran the docker create command.

User Context: The container runs as a non-root user (builder) with sudo privileges for security. All commands execute under this user account.

Alternative: Use a VS Code Dev Containers extension for a more integrated development experience.

⁠Usage

Once inside the container:

# Your current directory is accessible at /src
cd /src

# Run your AI agent commands here
# The agent can only access files within the container

⁠Container Management

# Stop the container
docker stop linux-ai-agents

# Restart the container
docker start -ai linux-ai-agents

# Remove the container (if needed)
docker rm linux-ai-agents

# Rebuild the image after changes
docker build -t linux-ai-agents .

⁠Security Considerations

• Review and audit any code before running it within the container
• Limit volume mounts to only necessary directories
• Regularly update the base image and dependencies
• Monitor container activity for unusual behavior
• Consider using read-only volume mounts for sensitive data

⁠Troubleshooting

Container won't start:

• Check if the image was built successfully: docker images | grep linux-ai-agents
• Verify Docker is running: docker ps

Permission issues:

• Ensure volume mount paths are correct and accessible
• Check file permissions on the host system

Missing tools:

• Install additional tools in the Dockerfile and rebuild the image