Skip to content

Colima Runtime Documentation Update #1492

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Sep 10, 2025
Merged

Colima Runtime Documentation Update #1492

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 13 additions & 3 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ ToolHive is a lightweight, secure manager for MCP (Model Context Protocol: https
- **Kubernetes Operator (`thv-operator`)**: Manages MCP servers in Kubernetes clusters
- **Proxy Runner (`thv-proxyrunner`)**: Handles proxy functionality for MCP server communication

The application acts as a thin client for Docker/Podman Unix socket API, providing container-based isolation for running MCP servers securely. It also builds on top of the MCP Specification: https://modelcontextprotocol.io/specification.
The application acts as a thin client for Docker/Podman/Colima Unix socket API, providing container-based isolation for running MCP servers securely. It also builds on top of the MCP Specification: https://modelcontextprotocol.io/specification.

## Build and Development Commands

Expand Down Expand Up @@ -90,7 +90,7 @@ The test framework uses Ginkgo and Gomega for BDD-style testing.

### Key Design Patterns

- **Factory Pattern**: Used extensively for creating runtime-specific implementations (Docker vs Kubernetes)
- **Factory Pattern**: Used extensively for creating runtime-specific implementations (Docker/Colima/Podman vs Kubernetes)
- **Interface Segregation**: Clean abstractions for container runtimes, transports, and storage
- **Middleware Pattern**: HTTP middleware for auth, authz, telemetry
- **Observer Pattern**: Event system for audit logging
Expand Down Expand Up @@ -131,6 +131,16 @@ The project uses `go.uber.org/mock` for generating mocks. Mock files are located
- Supports environment variable overrides
- Client configuration stored in `~/.toolhive/` or equivalent

### Container Runtime Configuration

ToolHive automatically detects available container runtimes in the following order: Podman, Colima, Docker. You can override the default socket paths using environment variables:

- `TOOLHIVE_PODMAN_SOCKET`: Custom Podman socket path
- `TOOLHIVE_COLIMA_SOCKET`: Custom Colima socket path (default: `~/.colima/default/docker.sock`)
- `TOOLHIVE_DOCKER_SOCKET`: Custom Docker socket path

**Colima Support**: Colima is fully supported as a Docker-compatible runtime. ToolHive will automatically detect Colima installations on macOS and Linux systems.

## Development Guidelines

### Code Organization
Expand Down Expand Up @@ -176,7 +186,7 @@ When working on the Kubernetes operator:

### Working with Containers

The container abstraction supports both Docker and Kubernetes runtimes. When adding container functionality:
The container abstraction supports Docker, Colima, Podman, and Kubernetes runtimes. When adding container functionality:
- Implement the interface in `pkg/container/runtime/types.go`
- Add runtime-specific implementations in appropriate subdirectories
- Use factory pattern for runtime selection
Expand Down
2 changes: 1 addition & 1 deletion cmd/thv/app/commands.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ var rootCmd = &cobra.Command{
Long: `ToolHive (thv) is a lightweight, secure, and fast manager for MCP (Model Context Protocol) servers.
It is written in Go and has extensive test coverage—including input validation—to ensure reliability and security.

Under the hood, ToolHive acts as a very thin client for the Docker/Podman Unix socket API.
Under the hood, ToolHive acts as a very thin client for the Docker/Podman/Colima Unix socket API.
This design choice allows it to remain both efficient and lightweight while still providing powerful,
container-based isolation for running MCP servers.`,
Run: func(cmd *cobra.Command, _ []string) {
Expand Down
2 changes: 1 addition & 1 deletion docs/cli/thv.md
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

3 changes: 2 additions & 1 deletion docs/proposals/thvignore.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -169,6 +169,7 @@ func convertMounts(mounts []runtime.Mount) []mount.Mount {
| ----- | ----- | ----- |
| Docker | ✅ `mount.TypeBind` | ✅ `mount.TypeTmpfs` |
| Podman | ✅ `--mount type=bind` | ✅ `--mount type=tmpfs` |
| Colima | ✅ `mount.TypeBind` | ✅ `mount.TypeTmpfs` |

---

Expand Down Expand Up @@ -341,6 +342,6 @@ docker run \
| Real-time file access | ✅ via full bind mount |
| Hidden files (e.g. `.ssh`, `.env`) | ✅ overlaid with tmpfs |
| Config flexibility | ✅ per-folder \+ global `.thvignore` |
| Runtime compatibility | ✅ Docker, Podman |
| Runtime compatibility | ✅ Docker, Podman, Colima |
| Integration | ✅ Works with existing permission profiles |