forge

package module
v0.0.0-...-a5f9a86 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 27, 2025 License: MIT Imports: 22 Imported by: 0

README

Forge - Lightweight Container Management Tool

A modern Docker container management service that provides both HTTP API and MCP (Model Context Protocol) server for seamless AI agent integration.

Features

  • 🐳 Docker Container Management: Create, run, and manage Docker containers with workspace isolation
  • 🤖 AI Agent Ready: Built-in MCP server support for AI agents and assistants like Claude
  • 🔒 Workspace Isolation: Each workspace gets its own Docker volume for security
  • 📡 Dual Interface: Both HTTP REST API and MCP protocol support
  • 🚀 Lightweight: Minimal overhead with clean, focused functionality
  • 🔧 Developer Friendly: Simple CLI interface with sensible defaults
  • 🌐 Network Isolation: Dedicated Docker network for forge containers

Use Cases

  • AI-powered development environments
  • Isolated code execution for AI assistants
  • Container-based CI/CD workflows
  • Secure multi-tenant development platforms
  • Interactive programming sessions with AI agents

Installation

go install github.com/flarexio/forge/cmd/forge@latest
go install github.com/flarexio/forge/cmd/forge_mcp@latest

Quick Start

HTTP Server Mode

Start the HTTP API server:

forge --port 8080 --path /path/to/workspace

The server will be available at http://localhost:8080

MCP Server Mode (for AI agents)

Start the MCP server for AI agent integration:

forge_mcp --path /path/to/workspace

API Overview

Container Operations
  • Run Once: Execute a command in a container and remove it
  • Run Interactive: Start a persistent container with shell access
  • Execute Commands: Run commands in existing containers
  • Send Input: Send input to container stdin (supports Ctrl+C, Ctrl+Z)
  • Read Logs: Retrieve container logs with optional filters
  • Remove Containers: Clean up containers individually or all at once
Image Management
  • List Images: Browse available Docker images
  • Pull Images: Download images from registries
  • Image Description: Get detailed information about images from Docker Hub
Workspace Management
  • Workspace Isolation: Each workspace ID gets its own Docker volume
  • Volume Mounting: Optional mounting of workspace to container paths
  • Network Isolation: Containers run in dedicated forge network

HTTP API Examples

List Available Images
curl "http://localhost:8080/docker/images?page=1&pageSize=10"
Pull an Image
curl "http://localhost:8080/docker/images/alpine/pull"
Run a One-time Command
curl -X POST "http://localhost:8080/workspaces/my-project/containers/run_once" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "node:18",
    "mountPath": "/workspace",
    "workDir": "/workspace",
    "cmd": ["npm", "install"]
  }'
Start Interactive Container
curl -X POST "http://localhost:8080/workspaces/my-project/containers/run" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "python:3.9",
    "mountPath": "/app",
    "workDir": "/app",
    "cmd": ["python3"]
  }'
Send Commands to Container
curl -X POST "http://localhost:8080/workspaces/my-project/containers/{container-id}/send" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "print(\"Hello World\")"
  }'
Execute Commands
curl -X POST "http://localhost:8080/workspaces/my-project/containers/{container-id}/exec" \
  -H "Content-Type: application/json" \
  -d '{
    "cmd": ["ls", "-la"]
  }'

MCP Integration

Forge provides native MCP (Model Context Protocol) support for AI agents. The MCP server exposes all container management capabilities as tools that AI agents can use:

  • ImageDescription - Get Docker image information from Docker Hub
  • ListImages - Browse available Docker images with pagination
  • PullImage - Download Docker images from registries
  • ListContainers - Show all containers in the current workspace
  • RunContainerOnce - Execute one-time commands in containers and remove them
  • RunContainer - Start persistent interactive containers
  • SendToContainer - Send input to running containers (supports Ctrl+C, Ctrl+Z)
  • LogsContainer - Retrieve container logs with timestamp filtering
  • ExecCommand - Execute commands in existing running containers
  • Wait - Add configurable delays between operations
  • SendAndRead - Send input to containers and read the output
  • RemoveContainer - Remove specific containers by ID
  • RemoveAllContainers - Clean up all containers in the workspace
MCP Tool Parameters

Each tool requires appropriate parameters and context:

  • Context: Most tools require workspace_id in the context
  • Container Operations: Tools like RunContainer and SendToContainer need container configuration
  • Image Operations: Tools like PullImage and ImageDescription work with image names
  • Timing: Tools like Wait and SendAndRead support duration parameters

Configuration

Command Line Options
forge (HTTP Server)
forge [options]

Options:
  --path string   Specifies the working directory (default: ~/.flarex/forge)
  --port int      HTTP server port (default: 8080)
forge_mcp (MCP Server)
forge_mcp [options]

Options:
  --path string   Specifies the working directory (default: ~/.flarex/forge)
Workspace Structure
~/.flarex/forge/
└── workspaces/
    ├── project-1/
    ├── project-2/
    └── my-workspace/

Each workspace directory is automatically mounted as a Docker volume for container access.

Architecture

Components
  • Service Layer: Core business logic for container management
  • Transport Layer: HTTP and MCP protocol handlers
  • Docker Integration: Direct Docker API communication
  • Workspace Management: Isolated workspace volumes
  • Network Management: Dedicated container networking
Security Features
  • Workspace ID Validation: Prevents directory traversal attacks
  • Container Isolation: Each workspace uses separate Docker volumes
  • Network Isolation: Containers run in dedicated Docker network
  • Label-based Access Control: Containers are tagged with workspace labels

Development

Prerequisites
  • Go 1.21+
  • Docker Engine
  • Docker daemon running
Build from Source
git clone https://github.com/flarexio/forge.git
cd forge

# Build HTTP server
go build -o bin/forge cmd/forge/main.go

# Build MCP server
go build -o bin/forge_mcp cmd/forge_mcp/main.go
Run Tests
go test ./...

Docker Requirements

  • Docker Engine 20.10+
  • Docker API version 1.41+
  • Sufficient permissions to create containers, volumes, and networks

Contributing

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrNoWorkspaceID       = errors.New("no workspace ID in context")
	ErrWorkspaceNotFound   = errors.New("workspace not found")
	ErrContainerNotFound   = errors.New("container not found in workspace")
	ErrContainerNotRunning = errors.New("container is not running")
)
View Source 
var (
	ErrInvalidRequest = errors.New("invalid request")
)

Functions

func ExecCommandEndpoint 

func ExecCommandEndpoint(svc Service) endpoint.Endpoint

func ImageDescriptionEndpoint 

func ImageDescriptionEndpoint(svc Service) endpoint.Endpoint

func ListContainersEndpoint 

func ListContainersEndpoint(svc Service) endpoint.Endpoint

func ListImagesEndpoint 

func ListImagesEndpoint(svc Service) endpoint.Endpoint

func LogsContainerEndpoint 

func LogsContainerEndpoint(svc Service) endpoint.Endpoint

func PullImageEndpoint 

func PullImageEndpoint(svc Service) endpoint.Endpoint

func RemoveAllContainersEndpoint 

func RemoveAllContainersEndpoint(svc Service) endpoint.Endpoint

func RemoveContainerEndpoint 

func RemoveContainerEndpoint(svc Service) endpoint.Endpoint

func RunContainerEndpoint 

func RunContainerEndpoint(svc Service) endpoint.Endpoint

func RunContainerOnceEndpoint 

func RunContainerOnceEndpoint(svc Service) endpoint.Endpoint

func SendAndReadEndpoint 

func SendAndReadEndpoint(svc Service) endpoint.Endpoint

func SendToContainerEndpoint 

func SendToContainerEndpoint(svc Service) endpoint.Endpoint

func WaitEndpoint 

func WaitEndpoint(svc Service) endpoint.Endpoint

Types

type Container 

type Container struct {
	ID      string
	Image   string
	Command string
	Status  string
	Names   []string
}

func (*Container) MarshalJSON 

func (c *Container) MarshalJSON() ([]byte, error)

type ContextKey 

type ContextKey string
const (
	WorkspaceID ContextKey = "workspace_id"
)

type ExecCommandRequest 

type ExecCommandRequest struct {
	ContainerID string   `json:"container_id"`
	Cmd         []string `json:"cmd"`
}

type ListImagesRequest 

type ListImagesRequest struct {
	Page     int `json:"page"`
	PageSize int `json:"page_size"`
}

type LogsContainerRequest 

type LogsContainerRequest struct {
	ContainerID string
	Since       time.Time
	Tail        int
}

func (*LogsContainerRequest) UnmarshalJSON 

func (req *LogsContainerRequest) UnmarshalJSON(data []byte) error

type RemoveContainerRequest 

type RemoveContainerRequest struct {
	ContainerID string `json:"container_id"`
}

type RunContainerRequest 

type RunContainerRequest struct {
	Image     string   `json:"image"`
	MountPath string   `json:"mount_path"`
	WorkDir   string   `json:"workdir"`
	Cmd       []string `json:"cmd"`
}

type SendAndReadRequest 

type SendAndReadRequest struct {
	ContainerID string
	Input       string
	Wait        time.Duration
}

func (*SendAndReadRequest) UnmarshalJSON 

func (req *SendAndReadRequest) UnmarshalJSON(data []byte) error

type SendToContainerRequest 

type SendToContainerRequest struct {
	ContainerID string `json:"container_id"`
	Input       string `json:"input"`
}

type Service 

type Service interface {

	// ImageDescription retrieves the description of a Docker image from Docker Hub.
	// i.e. https://hub.docker.com/v2/repositories/<image>
	ImageDescription(ctx context.Context, image string) (description string, err error)

	// ListImages lists all available Docker images on the host.
	// i.e. sudo docker images
	ListImages(ctx context.Context, page int, pageSize int) (images []string, err error)

	// PullImage pulls a Docker image from a registry.
	// i.e. sudo docker pull <image>
	PullImage(ctx context.Context, image string) error

	// ListContainers lists all containers in the current workspace.
	// i.e. sudo docker ps -a --filter "label=workspace=<workspaceID>"
	ListContainers(ctx context.Context) (containers []*Container, err error)

	// RunContainerOnce runs a container to execute a command and then removes the container.
	// i.e. sudo docker run --rm alpine:latest echo hello world
	RunContainerOnce(ctx context.Context, image string, mountPath string, workDir string, cmd ...string) (output string, err error)

	// RunContainer runs a container with interactive shell.
	// i.e. sudo docker run -id alpine:latest /bin/sh
	RunContainer(ctx context.Context, image string, mountPath string, workDir string, cmd ...string) (containerID string, err error)

	// SendToContainer sends input to the container's stdin.
	SendToContainer(ctx context.Context, containerID string, input string) error

	// LogsContainer retrieves the logs of a container.
	// i.e. sudo docker logs --tail <lines> <containerID>
	LogsContainer(ctx context.Context, containerID string, since time.Time, tail ...int) (output string, err error)

	// ExecCommand executes a command in a running container.
	// i.e. sudo docker exec <containerID> <command>
	ExecCommand(ctx context.Context, containerID string, cmd ...string) (output string, err error)

	// Wait waits for the specified duration.
	Wait(ctx context.Context, timeout time.Duration)

	// SendAndRead sends input to the container's stdin and reads the output.
	SendAndRead(ctx context.Context, containerID string, input string, wait time.Duration) (output string, err error)

	// RemoveContainer removes a container.
	// i.e. sudo docker rm -f <containerID>
	RemoveContainer(ctx context.Context, containerID string) error

	// RemoveAllContainers removes all containers in the current workspace.
	RemoveAllContainers(ctx context.Context) error

	// Close closes the service and cleans up any resources.
	Close(ctx context.Context) error
}

func NewService 

func NewService(path string) (Service, error)

type ServiceMiddleware 

type ServiceMiddleware func(Service) Service

func LoggingMiddleware 

func LoggingMiddleware(log *zap.Logger) ServiceMiddleware

type WaitRequest 

type WaitRequest struct {
	Timeout time.Duration `json:"timeout"`
}

Source Files

View all Source files

Directories

Path Synopsis
cmd
forge command
forge_mcp command
transport
http
mcp

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.