Actonos Setup Agent Skill

ActonOS Setup Skill

Use this skill when setting up the ActonOS development environment from scratch or verifying an existing setup.

Prerequisites Checklist

Before starting development, verify the following tools are installed:

| Tool | Min Version | Verification Command | Install Guide |

|:---|:---|:---|:---|

| Go | 1.26+ | go version | https://go.dev/dl/ |

| Node.js | 22 LTS+ | node --version | https://nodejs.org/ |

| npm | 10+ | npm --version | Bundled with Node.js |

| Make | 4.0+ | make --version | apt install make or choco install make |

| Git | 2.40+ | git --version | https://git-scm.com/ |

Optional Tools

| Tool | Purpose | Installation |

|:---|:---|:---|

| Docker 24+ | Container builds | https://docs.docker.com/get-docker/ |

| golangci-lint | Go linting | go install github.com/golangci-lint/golangci-lint/cmd/golangci-lint@latest |

| air | Go live-reload | go install github.com/air-verse/air@latest |

Setup Steps

Step 1: Clone and Initialize

git clone https://github.com/actonos/actonos.git
cd actonos

Step 2: Install Dependencies

make deps

This runs:

• go mod download && go mod verify — downloads Go modules
• cd web && npm ci — installs Node packages

Step 3: Create Dev Environment

# Create local data directory for development
mkdir -p dev-data/{config,agents,tokens,storage,logs,overrides,plugins,skills,mcp-servers,workspace}

Step 4: Create Local Environment File

Create .env in the project root (not committed):

RUNTIME_MODE=docker
LOG_LEVEL=debug
LISTEN_ADDR=:8080
DATA_DIR=./dev-data
DISABLE_TAILSCALE=true
DISABLE_SANDBOX=true

Step 5: Verify Setup

# Check Go modules
go mod verify

# Check frontend dependencies
cd web && npm ls --depth=0

# Try a build
make build-only

# Run tests
make test-unit

Step 6: Start Development Server

make dev

This starts:

• Go backend at http://localhost:8080
• Vite frontend at http://localhost:5173

Troubleshooting

| Issue | Solution |

|:---|:---|

| CGO_ENABLED error | Ensure using modernc.org/sqlite, not mattn/go-sqlite3 |

| Node version mismatch | Use nvm install 22 and nvm use 22 |

| Port conflict | Set LISTEN_ADDR=:8081 in .env |

| Permission denied on scripts | Run chmod +x scripts/*.sh |

Reference Files

• docs/DEVELOPMENT.md — Full development guide
• Makefile — Build targets reference
• .editorconfig — Editor configuration