Skip to content

threefoldtech/grid-agent

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

8 Commits
.github/workflows
.github/workflows
 
 
agent
agent
 
 
grid-agent-gui
grid-agent-gui
 
 
grid-cli
grid-cli
 
 
.gitignore
.gitignore
 
 
Makefile
Makefile
 
 
README.md
README.md
 
 
go.work
go.work
 
 

Repository files navigation

Grid Agent

AI-powered agent framework and tools for interacting with the ThreeFold Grid through natural language.

ThreeFold Grid Agent

Go Version License

Overview

The Grid Agent repository provides a complete suite of tools for intelligent automation and management of ThreeFold Grid infrastructure:

  • 🤖 Agent Framework - Reusable AI agent core with LLM provider abstraction
  • 🖥️ Grid Agent GUI - Modern desktop application built with Wails
  • ⚡ Grid CLI (tfcmd) - Command-line interface for Grid operations

Components

1. 📦 Agent (/agent)

A standalone, reusable AI agent framework for building intelligent conversational assistants.

Key Features:

  • LLM provider abstraction (Google Gemini, extensible to OpenAI, etc.)
  • Extensible tool system for CLI integration
  • Real-time streaming command execution
  • Automatic retry logic and error handling
  • Structured JSON response parsing

Package: github.com/threefoldtech/grid-agent/agent

📖 Read the full Agent documentation →

2. 🖥️ Grid Agent GUI (/grid-agent-gui)

A modern, cross-platform desktop application providing a chat interface to interact with the ThreeFold Grid using natural language.

Key Features:

  • AI-powered chat interface with Google Gemini
  • Beautiful dark/light theme support
  • Secure onboarding flow
  • Real-time command execution with streaming output
  • Multi-network support (mainnet, testnet, devnet)

Technologies: Wails v2, Svelte, TypeScript, Go

📖 Read the full GUI documentation →

3. ⚡ Grid CLI (/grid-cli)

Command-line interface for ThreeFold Grid operations, providing the foundation for agent schema generation.

Key Features:

  • Deploy and manage VMs, Kubernetes clusters, databases
  • Gateway management (FQDN, Name)
  • Contract operations
  • Schema export for AI agent integration

Package: github.com/threefoldtech/grid-agent/grid-cli

📖 Read the full CLI documentation →

Quick Start

You have two options to start using Grid Agent:

  1. Download prebuilt binaries (simplest)
  2. Build and install from source (for development)

1. Download prebuilt binaries

Prebuilt binaries for the latest tagged version are available on GitHub Releases:

Linux

  1. Download the latest tfcmd-linux-amd64 and grid-agent-gui-linux-amd64.

  2. Make the binaries executable and move them into your local bin directory:

    chmod +x tfcmd-linux-amd64
mv tfcmd-linux-amd64 ~/.local/bin/tfcmd

chmod +x grid-agent-gui-linux-amd64
mv grid-agent-gui-linux-amd64 ~/.local/bin/grid-agent-gui

  3. Ensure ~/.local/bin is in your PATH.

macOS

  1. Download the appropriate CLI and GUI artifacts for your architecture (amd64 or arm64).

  2. Install the CLI:

    chmod +x tfcmd-darwin-*
sudo mv tfcmd-darwin-amd64 /usr/local/bin/tfcmd   # Intel (amd64)
# or
sudo mv tfcmd-darwin-arm64 /usr/local/bin/tfcmd   # Apple Silicon (arm64)

  3. For the GUI, download the .app.zip for your architecture and extract it (Finder: double-click, or unzip from the terminal). This will produce grid-agent-gui.app.

    mv grid-agent-gui.app /Applications/ThreeFold\ Grid\ Agent.app

  4. Launch from Spotlight or Finder. If macOS blocks it as an "unidentified developer" or "App is damaged and can't be opened", allow it under System Settings → Privacy & Security.

Windows

  1. Download tfcmd-windows-amd64.exe and grid-agent-gui-windows-amd64.exe.

  2. Optionally rename and add the CLI to your PATH:

    Rename-Item .\tfcmd-windows-amd64.exe tfcmd.exe
# Then add its directory to the PATH environment variable

  3. Run grid-agent-gui-windows-amd64.exe to start the GUI.

2. Build and install from source

Prerequisites

  • Go 1.23 or higher
  • Node.js 18 or higher (for GUI)
  • Wails CLI v2.11.0+ (for GUI development)
  • System Dependencies (Linux only): Run make install-deps

Installation from source

Install all components with a single command:

make install

Or install specific components:

# Install Grid CLI only
make install-grid-cli

# Install Grid Agent GUI only
make install-grid-agent-gui

This will install binaries to:

  • Linux: ~/.local/bin
  • macOS: /usr/local/bin

Note: Make sure the installation directory is in your PATH.

Using the GUI

After installation, launch the Grid Agent GUI:

# From terminal
grid-agent-gui

# Or use your application launcher
# Search for "ThreeFold Grid Agent" in your app menu

On first launch, you'll be guided through:

  1. Entering your mnemonic phrase
  2. Selecting a network (mainnet/testnet/devnet)
  3. Providing a Gemini API key

Get a free Gemini API key at: https://aistudio.google.com/app/apikey

Development

This repository uses Go workspaces to manage multiple modules.

Setup Development Environment

# Clone the repository
git clone https://github.com/threefoldtech/grid-agent.git
cd grid-agent

# Check dependencies
make check-deps

# Install development tools
make install-tools

# Sync workspace
make work-sync

Build from Source

# Build all components
make build

# Build specific components
make build-agent          # Build agent library
make build-grid-cli       # Build tfcmd binary
make build-grid-agent-gui # Build GUI application

Running Tests

# Run all tests
make test

# Run specific component tests
make test-agent
make test-grid-cli
make test-grid-agent-gui

# Generate coverage reports
make coverage

Linting

# Lint all components
make lint

# Lint specific components
make lint-agent
make lint-grid-cli
make lint-grid-agent-gui

GUI Development

Run the GUI in development mode with hot reload:

make dev-gui

# Or directly
cd grid-agent-gui
wails dev

This starts:

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     Grid Agent GUI (Wails)                  │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  Frontend (Svelte + TypeScript)                        │ │
│  │  - Chat Interface                                      │ │
│  │  - Settings Management                                 │ │
│  │  - Real-time Output Display                           │ │
│  └──────────────────────┬─────────────────────────────────┘ │
│                         │ Wails Runtime Bridge              │
│  ┌──────────────────────▼─────────────────────────────────┐ │
│  │  Backend (Go)                                          │ │
│  │  - Agent Integration                                   │ │
│  │  - tfcmd Schema Generation                            │ │
│  │  - Configuration Management                           │ │
│  └──────────────────────┬─────────────────────────────────┘ │
└─────────────────────────┼───────────────────────────────────┘
                          │
            ┌─────────────▼─────────────┐
            │   Agent Framework Core    │
            │  ┌─────────────────────┐  │
            │  │  LLM Provider       │  │
            │  │  (Gemini)           │  │
            │  └──────────┬──────────┘  │
            │             │              │
            │  ┌──────────▼──────────┐  │
            │  │  Tool Registry      │  │
            │  │  - Command Tool     │  │
            │  │  - URL Fetch Tool   │  │
            │  │  - tfcmd Tool       │  │
            │  └──────────┬──────────┘  │
            │             │              │
            │  ┌──────────▼──────────┐  │
            │  │  Workflow Processor │  │
            │  └─────────────────────┘  │
            └─────────────┬─────────────┘
                          │
            ┌─────────────▼─────────────┐
            │   Grid CLI (tfcmd)        │
            │  - VM Management          │
            │  - Kubernetes Deployment  │
            │  - Gateway Configuration  │
            │  - Contract Operations    │
            └───────────────────────────┘
                          │
            ┌─────────────▼─────────────┐
            │   ThreeFold Grid          │
            │   (Blockchain + Nodes)    │
            └───────────────────────────┘

Project Structure

grid-agent/
├── agent/                  # AI agent framework (library)
│   ├── pkg/
│   │   ├── core/          # Agent orchestration
│   │   ├── llm/           # LLM provider implementations
│   │   ├── tools/         # Tool system and built-ins
│   │   └── workflow/      # Workflow processing
│   └── go.mod
│
├── grid-cli/              # ThreeFold Grid CLI
│   ├── cmd/               # CLI commands
│   ├── internal/          # Internal packages
│   ├── docs/              # Command documentation
│   └── go.mod
│
├── grid-agent-gui/        # Desktop GUI application
│   ├── frontend/          # Svelte frontend
│   │   └── src/
│   ├── internal/          # Go backend logic
│   │   ├── config/       # Configuration management
│   │   └── tfcmd/        # CLI integration
│   ├── build/            # Build assets
│   ├── app.go            # Main app logic
│   └── go.mod
│
├── Makefile              # Build automation
├── go.work               # Go workspace
└── README.md             # This file

Makefile Commands

Run make help to see all available commands:

# Building
make build                    # Build all components
make build-grid-cli          # Build tfcmd only
make build-grid-agent-gui    # Build GUI only

# Installation
make install                 # Install all components
make install-grid-cli        # Install tfcmd
make install-grid-agent-gui  # Install GUI with desktop entry

# Development
make install-deps            # Install system dependencies (Linux)
make dev-gui                 # Run GUI in dev mode with hot reload
make tidy                    # Tidy all go.mod files
make work-sync              # Sync Go workspace

# Testing
make test                    # Run all tests
make coverage               # Generate coverage reports

# Linting
make lint                    # Lint all components

# Cleanup
make clean                   # Remove build artifacts

Configuration

Grid Agent GUI

Settings are stored in ~/.config/grid-agent/settings.json:

{
  "mnemonics": "your twelve word mnemonic phrase here",
  "network": "mainnet",
  "geminiApiKey": "your-gemini-api-key",
  "theme": "dark",
  "isConfigured": true
}

Grid CLI

Configuration is stored in .tfgridconfig in your system's config directory.

Contributing

We welcome contributions! Please follow these guidelines:

Getting Started

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/amazing-feature
  3. Make your changes
  4. Run tests: make test
  5. Run linter: make lint
  6. Commit changes: git commit -m 'Add amazing feature'
  7. Push to branch: git push origin feature/amazing-feature
  8. Open a Pull Request

Code Standards

  • Follow Go best practices and conventions
  • Add tests for new features
  • Update documentation for API changes
  • Ensure all tests pass
  • Run make lint before committing
  • Use meaningful commit messages

Development Workflow

# 1. Sync dependencies
make tidy

# 2. Make your changes

# 3. Test
make test

# 4. Lint
make lint

# 5. Build
make build

Troubleshooting

GUI: "tfcmd not found"

Ensure tfcmd is installed and in your PATH:

make install-grid-cli
which tfcmd

GUI: Icon not showing (Linux)

Update icon cache and desktop database:

gtk-update-icon-cache ~/.local/share/icons/hicolor/ -f
update-desktop-database ~/.local/share/applications/

Then log out and log back in.

Build: "wails not found"

Install Wails CLI:

make install-tools
# or
go install github.com/wailsapp/wails/v2/cmd/wails@latest

Module: "package not found"

Sync the workspace:

make work-sync
make tidy

License

Apache License 2.0

Support

For issues and questions:

Credits

Related Projects

7

About

No description, website, or topics provided.

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 1

v0.1.0 Latest
Dec 3, 2025

Packages

No packages published

Languages