ipfs

IPFS UI based on Gio

A native Go/GioUI IPFS Desktop clone - a lightweight alternative to the Electron-based ipfs/ipfs-desktop.

Overview

This project is a prototype IPFS desktop application built with Go and the Gio UI toolkit. It provides a native, lightweight interface for interacting with IPFS, contrasting with the heavier Electron-based approach of the official IPFS Desktop.

New Architecture (April 2025): The app now manages its own local IPFS node (Kubo) as a child process instead of connecting to an external daemon. This provides a self-contained, app-managed IPFS experience.

Status

Last Updated: April 2026
Go Version: 1.23.8
Gio Version: v0.9.0
Build Status: ✅ Builds successfully on Linux
Runtime Status: ✅ Architecture complete, UI screens implemented, RPC integration partial

This is a prototype at approximately 60% release readiness (infrastructure complete, RPC integration partial, UI polish pending). See RELEASE_READINESS.md for detailed assessment.

Requirements

• Go 1.23.8 or later
• Kubo (go-ipfs) binary (bundled or system-installed)
• Linux operating system (only tested platform)

Install Kubo

# Install go-ipfs (Kubo)
wget https://dist.ipfs.io/go-ipfs/v0.29.0/go-ipfs_v0.29.0_linux-amd64.tar.gz
tar -xvzf go-ipfs_v0.29.0_linux-amd64.tar.gz
sudo mv go-ipfs /usr/local/bin/kubo

# Or install to system PATH as 'ipfs' (fallback)
sudo mv go-ipfs /usr/local/bin/ipfs

The app will search for Kubo in the following locations:

1. ./bin/kubo (bundled)
2. /usr/local/bin/kubo
3. /usr/bin/kubo
4. System ipfs command (PATH)

Build Instructions

# Clone the repository
git clone https://github.com/gioapp/ipfs.git
cd ipfs

# Download dependencies
go mod download

# Build the application
go build -o ipfs

# The binary will be created as `ipfs` in the current directory

Run Instructions

# Run the development build
./build/gioipfs

# Or run the release build
./release/gioipfs

The application will:

1. Create necessary directories in ~/.local/share/gioipfs/ and ~/.config/gioipfs/
2. Find the Kubo binary (searches multiple locations)
3. Initialize IPFS repository if it doesn't exist
4. Start the Kubo daemon as a child process
5. Launch the UI window

Note: The app manages the IPFS node internally - you don't need to run ipfs daemon separately.

Project Structure

.
├── app/              # Main application logic and UI pages
│   ├── files.go      # File browser and import workflow
│   ├── explore.go    # IPLD explorer
│   ├── settings.go   # Settings page
│   ├── status.go     # Status/dashboard page
│   ├── logs.go       # Logs/diagnostics screen
│   ├── pins.go       # Pins/content view
│   ├── peers.go      # Peers/network view
│   ├── model.go      # Core data structures
│   └── new.go        # Initialization
├── cmd/              # Application entry points
│   └── gioipfs/      # Main application entry point
├── internal/         # Internal packages
│   ├── config/       # Configuration and path management
│   ├── node/         # NodeManager (child process lifecycle)
│   ├── ipfsapi/      # RPC client abstraction
│   ├── desktop/      # Desktop integration layer
│   ├── logging/      # Structured logging with rotation
│   ├── diagnostics/  # Diagnostics bundle export
│   └── version/      # Version and build metadata
├── pkg/              # Shared packages
│   ├── helper/       # UI helper functions
│   ├── theme/        # Theme system
│   ├── lyt/          # Layout system
│   ├── icontextbtn/  # Icon+text button widget
│   └── itembtn/      # Item button widget
├── Makefile          # Build automation
├── go.mod            # Go module definition
└── README.md         # This file

Architecture

The application uses a layered architecture:

1. UI Layer (Gio) - Displays node status, files, peers, settings, logs
2. Desktop Integration Layer - Platform-specific functionality (tray, protocols, resources)
3. RPC Client Layer - Encapsulates HTTP API calls to local Kubo
4. NodeManager Layer - Manages Kubo daemon as child process
5. Config/Storage Layer - Platform-specific paths and configuration
6. Logging Layer - Structured logging with rotation
7. Diagnostics Layer - Diagnostics bundle export

See ARCHITECTURE.md for detailed architecture documentation.

Project Structure

.
├── app/              # Main application logic and UI pages
│   ├── files.go      # File browser
│   ├── explore.go    # IPLD explorer
│   ├── settings.go   # Settings page
│   ├── status.go     # Status page
│   └── ...
├── pkg/              # Shared packages
│   ├── helper/       # UI helper functions
│   ├── theme/        # Theme system
│   ├── lyt/          # Layout system (replaced external dependency)
│   ├── icontextbtn/  # Icon+text button widget
│   ├── itembtn/      # Item button widget
│   └── ipfs/         # IPFS daemon integration
├── cfg/              # Configuration
├── main.go           # Application entry point
├── go.mod            # Go module definition
└── README.md         # This file

Recent Modernization

This project was modernized in April 2025 from Go 1.14-era dependencies to Go 1.23.8 and Gio v0.9.0. Key changes include:

• Updated Go toolchain to 1.23.8
• Updated Gio/UI stack to v0.9.0
• Fixed all Gio API breakages (paint, clip, unit, widget APIs)
• Replaced unmaintained external dependency with local implementation
• Modernized event loop and window creation

See MIGRATION_LOG.md for detailed migration notes.

Current Features

• ✅ Native Go/Gio UI (no Electron/Chromium)
• ✅ App-managed IPFS node (Kubo as child process)
• ✅ Platform-specific configuration (XDG-compliant on Linux)
• ✅ Node lifecycle management (start/stop with state machine)
• ✅ Log capture and display
• ✅ RPC client abstraction layer
• ✅ First-run onboarding UX
• ✅ Dashboard with node metrics (state, repo path, peer ID, version, API/gateway endpoints)
• ✅ Quick actions (Add file, Add folder placeholders)
• ✅ File import workflow with job tracking (Pending, Importing, Success, Failed)
• ✅ Import results display (CID, filename, timestamp)
• ✅ Pins view screen (pin list display)
• ✅ Peers view screen (peer list display)
• ✅ Settings screen (configuration display: repo path, ports, auto-start)
• ✅ Logs screen with environment info and actions (export, clear)
• ✅ Node control UX with state-aware start/stop button
• ✅ Protections against duplicate operations
• ✅ Clear navigation structure with sidebar
• ✅ Theme system
• ✅ Desktop integration abstraction layer (Linux-first)
• ✅ Resource discovery (dev/release modes)
• ✅ Structured logging with rotation
• ✅ Diagnostics bundle export
• ✅ Version metadata injection via ldflags
• ✅ Build workflow with Makefile
• ✅ Linux autostart integration

Known Limitations

• UI screens implemented but not fully wired to RPC calls (UI-only for now)
• No actual file picker integration (import workflow is UI tracking only)
• No drag-and-drop support
• System tray integration is stub only (no actual tray icon)
• Protocol handlers are stub only (no actual registration)
• Notifications are stub only (no actual notifications)
• No installers or distribution packages
• No bundled Kubo binary (must be installed separately)
• Window size/title not configured (uses defaults)
• Limited error handling for IPFS connection failures
• Linux only (no Windows/macOS support)

See RELEASE_READINESS.md for detailed status.

Documentation

• ARCHITECTURE.md - Detailed architecture documentation
• MIGRATION_NOTES.md - Details of the modernization process
• FEATURE_STATUS.md - Feature parity comparison with ipfs/ipfs-desktop
• UX_NOTES.md - User experience documentation and design decisions
• RELEASE_READINESS.md - Release readiness assessment
• DESKTOP_INTEGRATION.md - Desktop integration documentation
• PACKAGING.md - Packaging and build layout documentation
• RELEASE_CHECKLIST.md - Release checklist

Development

The project follows a simple structure:

• main.go - Entry point, creates window and runs event loop
• app/ - UI pages and application logic
• pkg/ - Reusable components and IPFS integration

Adding New Pages

1. Create a function in app/ that returns the page layout
2. Add the page to the getPages() function in app/page.go
3. Add the page to the navigation menu in app/new.go

Contributing

This is a prototype project. Contributions are welcome, especially for:

• Testing NodeManager with actual Kubo binary
• Implementing UI for node state display and controls
• Adding logs/diagnostics screen
• Completing RPC client implementations
• Adding missing features from ipfs/ipfs-desktop
• Testing and fixing runtime issues
• Adding system integration (tray, protocol handlers)
• Creating distribution packages
• Bundling Kubo binary with app

License

See LICENSE file for details.

Acknowledgments

• Gio - The immediate mode GUI toolkit for Go
• IPFS - The InterPlanetary File System
• ipfs/ipfs-desktop - Reference implementation