{"owner":"psviderski","repo":"uncloud","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# AGENTS.md - Uncloud Project Guide\n\nThis document provides comprehensive information about the Uncloud project for AI assistants to understand the codebase,\narchitecture, and development practices.\n\n## Project Overview\n\n**Uncloud** is a lightweight clustering and container orchestration tool that enables deployment and management of web\napplications across cloud VMs and bare metal servers. It creates a secure WireGuard mesh network between Docker hosts\nand provides automatic service discovery, load balancing, HTTPS ingress, and simple CLI commands for application\nmanagement.\n\n### Key Characteristics\n\n- **Language**: Go\n- **Architecture**: Decentralized, no control plane\n- **Target**: Self-hosted infrastructure without Kubernetes complexity\n- **License**: View LICENSE file for details\n- **Status**: Active development, not yet ready for production\n\n## Core Features\n\n### 🏗️ Infrastructure\n\n- **Multi-machine deployment**: Combine cloud VMs, dedicated servers, and bare metal\n- **Zero-config networking**: Automatic WireGuard mesh with NAT traversal\n- **Decentralized design**: No central control plane, all machines are equal\n- **Service discovery**: Built-in DNS server resolves service names to container IPs\n\n### 🚀 Application Management\n\n- **Docker Compose compatibility**: Uses familiar Docker Compose format\n- **Zero-downtime deployments**: Rolling updates without service interruption\n- **Automatic HTTPS**: Caddy reverse proxy with Let's Encrypt integration\n- **Managed DNS**: Free `*.xxxxxx.uncld.dev` subdomains via Uncloud DNS service\n- **Cross-machine scaling**: Run containers across multiple machines\n\n### 🔧 Developer Experience\n\n- **Docker-like CLI**: Familiar commands (`uc` binary)\n- **Imperative operations**: Direct commands vs. declarative state reconciliation\n- **Remote management**: Control entire infrastructure via SSH to any machine\n- **Minimal overhead**: ~150MB RAM footprint per machine\n\n## Architecture\n\n### Core Components\n\n1. **CLI (`uc`)** - Main user interface for cluster management\n2. **Daemon (`uncloudd`)** - Machine daemon running on each node\n3. **Corrosion** - Distributed SQLite database for cluster state (Fly.io project)\n4. **Caddy** - Reverse proxy for HTTPS termination and routing\n5. **WireGuard** - Secure mesh networking between machines\n\n### Network Architecture\n\n- Each machine gets unique subnet (e.g., `10.210.0.0/24`, `10.210.1.0/24`)\n- Containers get cluster-unique IPs for direct communication\n- Automatic peer discovery and key management\n- NAT traversal for machines behind firewalls\n\n### State Management\n\n- **CRDT-based distributed storage** using Corrosion\n- **Eventually consistent** state across all machines\n- **Gossip protocol** (Serf) for state propagation\n- **No quorum requirements** - partial network splits remain functional\n\n## Project Structure\n\n### Key Directories\n\n- **`cmd/`**: Contains main applications\n\n    - `uc/`: CLI tool with subcommands for machine, service, volume management\n    - `uncloudd/`: Daemon that runs on each machine\n    - `ucind/`: Development cluster management for testing\n\n- **`internal/`**: Internal implementation packages\n\n    - `cli/`: Command-line interface logic\n    - `machine/`: Machine lifecycle and state management\n    - `daemon/`: Daemon implementation and gRPC services\n    - `dns/`: Internal DNS server for service discovery\n\n- **`pkg/`**: Public API packages for external use\n\n    - `api/`: Core API types and definitions\n    - `client/`: Client libraries for interacting with Uncloud\n\n- **`experiment/`**: Experimental features and prototypes\n- **`scripts/`**: Installation and utility scripts\n- **`test/`**: Test suites and test infrastructure\n- **`website/`**: Documentation website (Docusaurus)\n\n    - `landing/`: Landing page\n    - `docs/`: User documentation\n\n- **`misc/`**: Design documents and guides\n\n## Key Technologies\n\n### Core Dependencies\n\n```go\n// Networking and orchestration\ngithub.com/docker/docker // Docker API client\ngithub.com/docker/compose/v2 // Docker Compose integration\ngolang.zx2c4.com/wireguard // WireGuard implementation\ngithub.com/hashicorp/serf // Gossip protocol\n\n// State management\ngithub.com/ipfs/go-ds-crdt // CRDT distributed storage\ngithub.com/dgraph-io/badger/v3 // Embedded database\n\n// Web proxy\ngithub.com/caddyserver/caddy/v2 // HTTP server and reverse proxy\n\n// CLI and UX\ngithub.com/spf13/cobra // CLI framework\ngithub.com/charmbracelet/huh // Interactive forms\n\n// gRPC and networking\ngoogle.golang.org/grpc                     // gRPC framework\ngithub.com/siderolabs/grpc-proxy // gRPC proxy for forwarding\n```\n\n## Development Workflow\n\n### Build and Development\n\n```bash\n# Build binaries\ngo build -o uc ./cmd/uc\ngo build -o uncloudd ./cmd/uncloudd\n```\n\n### Key Make Targets\n\n- `proto`: Generate protobuf code\n- `ucind-cluster`: Create development cluster\n- `update-dev`: Deploy to development machines\n- `demo-reset`: Reset demo environment\n- `fmt`: Format code\n- `test`: Run all tests\n- `lint`: Lint the code using golangci-lint\n- `lint-and-fix`: Lint the code and fix issues whenever possible\n\n## CLI Commands Structure\n\nThe `uc` CLI provides these main command groups:\n\n### Machine Management\n\n```bash\nuc machine init <user@host>     # Initialize new cluster\nuc machine add <user@host>      # Add machine to cluster\nuc machine ls                   # List machines\nuc machine rm <name>            # Remove machine\n```\n\n### Service Management\n\n```bash\nuc run <image>                  # Run container from image\nuc deploy                       # Deploy from compose.yaml\nuc scale <service> <count>      # Scale service replicas\nuc ls                           # List services\nuc rm <service>                 # Remove service\n```\n\n### Context and Connectivity\n\n```bash\nuc context ls                   # List available contexts\nuc context use <name>           # Switch context\n```\n\n### Global Flags\n\n- `--connect`: Connect to remote machine directly, without a config file\n- `--uncloud-config`: Override config file path\n\n## Development Guidelines\n\n### Code Organization\n\n- **Package naming**: Use clear, descriptive names\n- **Error handling**: Wrap errors with context using `fmt.Errorf`\n- **Logging**: Use structured logging with levels\n- **gRPC**: Services defined in `internal/machine/api/pb/`\n\n### Testing\n\n- Test files and locations\n    - Unit tests alongside source files (`*_test.go`)\n    - Integration tests in `test/e2e/`\n    - Test fixtures in `test/fixtures/`\n- Use table driven tests whenever possible\n- Use the `testify` library for assertions (e.g., `require.Equal`, `assert.Nil`)\n\n### Dependencies\n\n- Prefer standard library when possible\n- Pin versions in `go.mod`\n- Document rationale for external dependencies\n\n### Configuration\n\n- Support environment variables for key settings\n- Validate configuration early\n- Provide sensible defaults\n\n## Troubleshooting and Debugging\n\n### Common Issues\n\n- **Networking**: Check WireGuard status, iptables rules\n- **DNS**: Verify service discovery resolution\n- **Containers**: Use standard Docker debugging tools\n- **State sync**: Check Corrosion logs for replication issues\n\n### Debugging Tools\n\n- Standard Linux networking tools (`ping`, `traceroute`, `wireshark`)\n- Docker commands (`docker ps`, `docker logs`)\n- SSH access to machines for direct inspection\n- gRPC debugging tools\n\n### Logs and Monitoring\n\n- Systemd services (getting logs via `journalctl -u SERVICE_NAME`)\n    - `uncloud` -- Uncloud daemon\n    - `uncloud-corrosion` -- Corrosion process\n- Machine daemon logs\n- Container logs via Docker\n\n## File Patterns and Conventions\n\n### Important Files to Understand\n\n- `cmd/uc/main.go`: CLI entry point and command structure\n- `internal/cli/cli.go`: CLI implementation and configuration\n- `internal/machine/machine.go`: Core machine management\n- `pkg/api/`: Public API definitions\n- `misc/design.md`: Architecture and design philosophy\n- `README.md`: Repository README\n\n### Configuration Files\n\n- `go.mod/go.sum`: Go dependency management\n- `Makefile`: Build and development tasks\n- `Dockerfile`: Container build instructions forUncloud-in-Docker (used for testing)\n\nThis document should help AI assistants understand the project structure, make informed suggestions, and contribute\neffectively to the Uncloud codebase.\n\n## Documentation\n\nInstructions when generating documentation:\n\n- Use conversational language – write as if you were speaking to a friend.\n- Keep sentences simple, optimize for clarity and understanding.\n- Do not use em dashes (—) or semicolons (;) in sentences. Instead, break complex sentences into simpler ones.\n- Place the subject before the action whenever possible. Example: prefer \"The function loads data\" over \"Data is loaded\n  by the function.\"\n"},"files":{"AGENTS.md":"# AGENTS.md - Uncloud Project Guide\n\nThis document provides comprehensive information about the Uncloud project for AI assistants to understand the codebase,\narchitecture, and development practices.\n\n## Project Overview\n\n**Uncloud** is a lightweight clustering and container orchestration tool that enables deployment and management of web\napplications across cloud VMs and bare metal servers. It creates a secure WireGuard mesh network between Docker hosts\nand provides automatic service discovery, load balancing, HTTPS ingress, and simple CLI commands for application\nmanagement.\n\n### Key Characteristics\n\n- **Language**: Go\n- **Architecture**: Decentralized, no control plane\n- **Target**: Self-hosted infrastructure without Kubernetes complexity\n- **License**: View LICENSE file for details\n- **Status**: Active development, not yet ready for production\n\n## Core Features\n\n### 🏗️ Infrastructure\n\n- **Multi-machine deployment**: Combine cloud VMs, dedicated servers, and bare metal\n- **Zero-config networking**: Automatic WireGuard mesh with NAT traversal\n- **Decentralized design**: No central control plane, all machines are equal\n- **Service discovery**: Built-in DNS server resolves service names to container IPs\n\n### 🚀 Application Management\n\n- **Docker Compose compatibility**: Uses familiar Docker Compose format\n- **Zero-downtime deployments**: Rolling updates without service interruption\n- **Automatic HTTPS**: Caddy reverse proxy with Let's Encrypt integration\n- **Managed DNS**: Free `*.xxxxxx.uncld.dev` subdomains via Uncloud DNS service\n- **Cross-machine scaling**: Run containers across multiple machines\n\n### 🔧 Developer Experience\n\n- **Docker-like CLI**: Familiar commands (`uc` binary)\n- **Imperative operations**: Direct commands vs. declarative state reconciliation\n- **Remote management**: Control entire infrastructure via SSH to any machine\n- **Minimal overhead**: ~150MB RAM footprint per machine\n\n## Architecture\n\n### Core Components\n\n1. **CLI (`uc`)** - Main user interface for cluster management\n2. **Daemon (`uncloudd`)** - Machine daemon running on each node\n3. **Corrosion** - Distributed SQLite database for cluster state (Fly.io project)\n4. **Caddy** - Reverse proxy for HTTPS termination and routing\n5. **WireGuard** - Secure mesh networking between machines\n\n### Network Architecture\n\n- Each machine gets unique subnet (e.g., `10.210.0.0/24`, `10.210.1.0/24`)\n- Containers get cluster-unique IPs for direct communication\n- Automatic peer discovery and key management\n- NAT traversal for machines behind firewalls\n\n### State Management\n\n- **CRDT-based distributed storage** using Corrosion\n- **Eventually consistent** state across all machines\n- **Gossip protocol** (Serf) for state propagation\n- **No quorum requirements** - partial network splits remain functional\n\n## Project Structure\n\n### Key Directories\n\n- **`cmd/`**: Contains main applications\n\n    - `uc/`: CLI tool with subcommands for machine, service, volume management\n    - `uncloudd/`: Daemon that runs on each machine\n    - `ucind/`: Development cluster management for testing\n\n- **`internal/`**: Internal implementation packages\n\n    - `cli/`: Command-line interface logic\n    - `machine/`: Machine lifecycle and state management\n    - `daemon/`: Daemon implementation and gRPC services\n    - `dns/`: Internal DNS server for service discovery\n\n- **`pkg/`**: Public API packages for external use\n\n    - `api/`: Core API types and definitions\n    - `client/`: Client libraries for interacting with Uncloud\n\n- **`experiment/`**: Experimental features and prototypes\n- **`scripts/`**: Installation and utility scripts\n- **`test/`**: Test suites and test infrastructure\n- **`website/`**: Documentation website (Docusaurus)\n\n    - `landing/`: Landing page\n    - `docs/`: User documentation\n\n- **`misc/`**: Design documents and guides\n\n## Key Technologies\n\n### Core Dependencies\n\n```go\n// Networking and orchestration\ngithub.com/docker/docker // Docker API client\ngithub.com/docker/compose/v2 // Docker Compose integration\ngolang.zx2c4.com/wireguard // WireGuard implementation\ngithub.com/hashicorp/serf // Gossip protocol\n\n// State management\ngithub.com/ipfs/go-ds-crdt // CRDT distributed storage\ngithub.com/dgraph-io/badger/v3 // Embedded database\n\n// Web proxy\ngithub.com/caddyserver/caddy/v2 // HTTP server and reverse proxy\n\n// CLI and UX\ngithub.com/spf13/cobra // CLI framework\ngithub.com/charmbracelet/huh // Interactive forms\n\n// gRPC and networking\ngoogle.golang.org/grpc                     // gRPC framework\ngithub.com/siderolabs/grpc-proxy // gRPC proxy for forwarding\n```\n\n## Development Workflow\n\n### Build and Development\n\n```bash\n# Build binaries\ngo build -o uc ./cmd/uc\ngo build -o uncloudd ./cmd/uncloudd\n```\n\n### Key Make Targets\n\n- `proto`: Generate protobuf code\n- `ucind-cluster`: Create development cluster\n- `update-dev`: Deploy to development machines\n- `demo-reset`: Reset demo environment\n- `fmt`: Format code\n- `test`: Run all tests\n- `lint`: Lint the code using golangci-lint\n- `lint-and-fix`: Lint the code and fix issues whenever possible\n\n## CLI Commands Structure\n\nThe `uc` CLI provides these main command groups:\n\n### Machine Management\n\n```bash\nuc machine init <user@host>     # Initialize new cluster\nuc machine add <user@host>      # Add machine to cluster\nuc machine ls                   # List machines\nuc machine rm <name>            # Remove machine\n```\n\n### Service Management\n\n```bash\nuc run <image>                  # Run container from image\nuc deploy                       # Deploy from compose.yaml\nuc scale <service> <count>      # Scale service replicas\nuc ls                           # List services\nuc rm <service>                 # Remove service\n```\n\n### Context and Connectivity\n\n```bash\nuc context ls                   # List available contexts\nuc context use <name>           # Switch context\n```\n\n### Global Flags\n\n- `--connect`: Connect to remote machine directly, without a config file\n- `--uncloud-config`: Override config file path\n\n## Development Guidelines\n\n### Code Organization\n\n- **Package naming**: Use clear, descriptive names\n- **Error handling**: Wrap errors with context using `fmt.Errorf`\n- **Logging**: Use structured logging with levels\n- **gRPC**: Services defined in `internal/machine/api/pb/`\n\n### Testing\n\n- Test files and locations\n    - Unit tests alongside source files (`*_test.go`)\n    - Integration tests in `test/e2e/`\n    - Test fixtures in `test/fixtures/`\n- Use table driven tests whenever possible\n- Use the `testify` library for assertions (e.g., `require.Equal`, `assert.Nil`)\n\n### Dependencies\n\n- Prefer standard library when possible\n- Pin versions in `go.mod`\n- Document rationale for external dependencies\n\n### Configuration\n\n- Support environment variables for key settings\n- Validate configuration early\n- Provide sensible defaults\n\n## Troubleshooting and Debugging\n\n### Common Issues\n\n- **Networking**: Check WireGuard status, iptables rules\n- **DNS**: Verify service discovery resolution\n- **Containers**: Use standard Docker debugging tools\n- **State sync**: Check Corrosion logs for replication issues\n\n### Debugging Tools\n\n- Standard Linux networking tools (`ping`, `traceroute`, `wireshark`)\n- Docker commands (`docker ps`, `docker logs`)\n- SSH access to machines for direct inspection\n- gRPC debugging tools\n\n### Logs and Monitoring\n\n- Systemd services (getting logs via `journalctl -u SERVICE_NAME`)\n    - `uncloud` -- Uncloud daemon\n    - `uncloud-corrosion` -- Corrosion process\n- Machine daemon logs\n- Container logs via Docker\n\n## File Patterns and Conventions\n\n### Important Files to Understand\n\n- `cmd/uc/main.go`: CLI entry point and command structure\n- `internal/cli/cli.go`: CLI implementation and configuration\n- `internal/machine/machine.go`: Core machine management\n- `pkg/api/`: Public API definitions\n- `misc/design.md`: Architecture and design philosophy\n- `README.md`: Repository README\n\n### Configuration Files\n\n- `go.mod/go.sum`: Go dependency management\n- `Makefile`: Build and development tasks\n- `Dockerfile`: Container build instructions forUncloud-in-Docker (used for testing)\n\nThis document should help AI assistants understand the project structure, make informed suggestions, and contribute\neffectively to the Uncloud codebase.\n\n## Documentation\n\nInstructions when generating documentation:\n\n- Use conversational language – write as if you were speaking to a friend.\n- Keep sentences simple, optimize for clarity and understanding.\n- Do not use em dashes (—) or semicolons (;) in sentences. Instead, break complex sentences into simpler ones.\n- Place the subject before the action whenever possible. Example: prefer \"The function loads data\" over \"Data is loaded\n  by the function.\"\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# AGENTS.md - Uncloud Project Guide\n\nThis document provides comprehensive information about the Uncloud project for AI assistants to understand the codebase,\narchitecture, and development practices.\n\n## Project Overview\n\n**Uncloud** is a lightweight clustering and container orchestration tool that enables deployment and management of web\napplications across cloud VMs and bare metal servers. It creates a secure WireGuard mesh network between Docker hosts\nand provides automatic service discovery, load balancing, HTTPS ingress, and simple CLI commands for application\nmanagement.\n\n### Key Characteristics\n\n- **Language**: Go\n- **Architecture**: Decentralized, no control plane\n- **Target**: Self-hosted infrastructure without Kubernetes complexity\n- **License**: View LICENSE file for details\n- **Status**: Active development, not yet ready for production\n\n## Core Features\n\n### 🏗️ Infrastructure\n\n- **Multi-machine deployment**: Combine cloud VMs, dedicated servers, and bare metal\n- **Zero-config networking**: Automatic WireGuard mesh with NAT traversal\n- **Decentralized design**: No central control plane, all machines are equal\n- **Service discovery**: Built-in DNS server resolves service names to container IPs\n\n### 🚀 Application Management\n\n- **Docker Compose compatibility**: Uses familiar Docker Compose format\n- **Zero-downtime deployments**: Rolling updates without service interruption\n- **Automatic HTTPS**: Caddy reverse proxy with Let's Encrypt integration\n- **Managed DNS**: Free `*.xxxxxx.uncld.dev` subdomains via Uncloud DNS service\n- **Cross-machine scaling**: Run containers across multiple machines\n\n### 🔧 Developer Experience\n\n- **Docker-like CLI**: Familiar commands (`uc` binary)\n- **Imperative operations**: Direct commands vs. declarative state reconciliation\n- **Remote management**: Control entire infrastructure via SSH to any machine\n- **Minimal overhead**: ~150MB RAM footprint per machine\n\n## Architecture\n\n### Core Components\n\n1. **CLI (`uc`)** - Main user interface for cluster management\n2. **Daemon (`uncloudd`)** - Machine daemon running on each node\n3. **Corrosion** - Distributed SQLite database for cluster state (Fly.io project)\n4. **Caddy** - Reverse proxy for HTTPS termination and routing\n5. **WireGuard** - Secure mesh networking between machines\n\n### Network Architecture\n\n- Each machine gets unique subnet (e.g., `10.210.0.0/24`, `10.210.1.0/24`)\n- Containers get cluster-unique IPs for direct communication\n- Automatic peer discovery and key management\n- NAT traversal for machines behind firewalls\n\n### State Management\n\n- **CRDT-based distributed storage** using Corrosion\n- **Eventually consistent** state across all machines\n- **Gossip protocol** (Serf) for state propagation\n- **No quorum requirements** - partial network splits remain functional\n\n## Project Structure\n\n### Key Directories\n\n- **`cmd/`**: Contains main applications\n\n    - `uc/`: CLI tool with subcommands for machine, service, volume management\n    - `uncloudd/`: Daemon that runs on each machine\n    - `ucind/`: Development cluster management for testing\n\n- **`internal/`**: Internal implementation packages\n\n    - `cli/`: Command-line interface logic\n    - `machine/`: Machine lifecycle and state management\n    - `daemon/`: Daemon implementation and gRPC services\n    - `dns/`: Internal DNS server for service discovery\n\n- **`pkg/`**: Public API packages for external use\n\n    - `api/`: Core API types and definitions\n    - `client/`: Client libraries for interacting with Uncloud\n\n- **`experiment/`**: Experimental features and prototypes\n- **`scripts/`**: Installation and utility scripts\n- **`test/`**: Test suites and test infrastructure\n- **`website/`**: Documentation website (Docusaurus)\n\n    - `landing/`: Landing page\n    - `docs/`: User documentation\n\n- **`misc/`**: Design documents and guides\n\n## Key Technologies\n\n### Core Dependencies\n\n```go\n// Networking and orchestration\ngithub.com/docker/docker // Docker API client\ngithub.com/docker/compose/v2 // Docker Compose integration\ngolang.zx2c4.com/wireguard // WireGuard implementation\ngithub.com/hashicorp/serf // Gossip protocol\n\n// State management\ngithub.com/ipfs/go-ds-crdt // CRDT distributed storage\ngithub.com/dgraph-io/badger/v3 // Embedded database\n\n// Web proxy\ngithub.com/caddyserver/caddy/v2 // HTTP server and reverse proxy\n\n// CLI and UX\ngithub.com/spf13/cobra // CLI framework\ngithub.com/charmbracelet/huh // Interactive forms\n\n// gRPC and networking\ngoogle.golang.org/grpc                     // gRPC framework\ngithub.com/siderolabs/grpc-proxy // gRPC proxy for forwarding\n```\n\n## Development Workflow\n\n### Build and Development\n\n```bash\n# Build binaries\ngo build -o uc ./cmd/uc\ngo build -o uncloudd ./cmd/uncloudd\n```\n\n### Key Make Targets\n\n- `proto`: Generate protobuf code\n- `ucind-cluster`: Create development cluster\n- `update-dev`: Deploy to development machines\n- `demo-reset`: Reset demo environment\n- `fmt`: Format code\n- `test`: Run all tests\n- `lint`: Lint the code using golangci-lint\n- `lint-and-fix`: Lint the code and fix issues whenever possible\n\n## CLI Commands Structure\n\nThe `uc` CLI provides these main command groups:\n\n### Machine Management\n\n```bash\nuc machine init <user@host>     # Initialize new cluster\nuc machine add <user@host>      # Add machine to cluster\nuc machine ls                   # List machines\nuc machine rm <name>            # Remove machine\n```\n\n### Service Management\n\n```bash\nuc run <image>                  # Run container from image\nuc deploy                       # Deploy from compose.yaml\nuc scale <service> <count>      # Scale service replicas\nuc ls                           # List services\nuc rm <service>                 # Remove service\n```\n\n### Context and Connectivity\n\n```bash\nuc context ls                   # List available contexts\nuc context use <name>           # Switch context\n```\n\n### Global Flags\n\n- `--connect`: Connect to remote machine directly, without a config file\n- `--uncloud-config`: Override config file path\n\n## Development Guidelines\n\n### Code Organization\n\n- **Package naming**: Use clear, descriptive names\n- **Error handling**: Wrap errors with context using `fmt.Errorf`\n- **Logging**: Use structured logging with levels\n- **gRPC**: Services defined in `internal/machine/api/pb/`\n\n### Testing\n\n- Test files and locations\n    - Unit tests alongside source files (`*_test.go`)\n    - Integration tests in `test/e2e/`\n    - Test fixtures in `test/fixtures/`\n- Use table driven tests whenever possible\n- Use the `testify` library for assertions (e.g., `require.Equal`, `assert.Nil`)\n\n### Dependencies\n\n- Prefer standard library when possible\n- Pin versions in `go.mod`\n- Document rationale for external dependencies\n\n### Configuration\n\n- Support environment variables for key settings\n- Validate configuration early\n- Provide sensible defaults\n\n## Troubleshooting and Debugging\n\n### Common Issues\n\n- **Networking**: Check WireGuard status, iptables rules\n- **DNS**: Verify service discovery resolution\n- **Containers**: Use standard Docker debugging tools\n- **State sync**: Check Corrosion logs for replication issues\n\n### Debugging Tools\n\n- Standard Linux networking tools (`ping`, `traceroute`, `wireshark`)\n- Docker commands (`docker ps`, `docker logs`)\n- SSH access to machines for direct inspection\n- gRPC debugging tools\n\n### Logs and Monitoring\n\n- Systemd services (getting logs via `journalctl -u SERVICE_NAME`)\n    - `uncloud` -- Uncloud daemon\n    - `uncloud-corrosion` -- Corrosion process\n- Machine daemon logs\n- Container logs via Docker\n\n## File Patterns and Conventions\n\n### Important Files to Understand\n\n- `cmd/uc/main.go`: CLI entry point and command structure\n- `internal/cli/cli.go`: CLI implementation and configuration\n- `internal/machine/machine.go`: Core machine management\n- `pkg/api/`: Public API definitions\n- `misc/design.md`: Architecture and design philosophy\n- `README.md`: Repository README\n\n### Configuration Files\n\n- `go.mod/go.sum`: Go dependency management\n- `Makefile`: Build and development tasks\n- `Dockerfile`: Container build instructions forUncloud-in-Docker (used for testing)\n\nThis document should help AI assistants understand the project structure, make informed suggestions, and contribute\neffectively to the Uncloud codebase.\n\n## Documentation\n\nInstructions when generating documentation:\n\n- Use conversational language – write as if you were speaking to a friend.\n- Keep sentences simple, optimize for clarity and understanding.\n- Do not use em dashes (—) or semicolons (;) in sentences. Instead, break complex sentences into simpler ones.\n- Place the subject before the action whenever possible. Example: prefer \"The function loads data\" over \"Data is loaded\n  by the function.\"\n","category":"root","tokens":2180}]}