Linux Command Center

Linux Command Center is a custom Linux fleet management command center. The current implementation includes the local development stack, cookie-based local auth, base dashboard UI, node enrollment, and initial outbound agent WebSocket connectivity.

Job execution, approvals, metrics collection, service management, package management, and terminal functionality are not implemented yet.

Stack

• Backend: FastAPI, Python 3.12, SQLAlchemy 2.x, Alembic, PostgreSQL, Pydantic Settings, structured logging
• Frontend: Next.js, TypeScript, App Router, TailwindCSS, ShadCN-ready configuration
• Agent: Go CLI with config loader, enrollment, and outbound WebSocket connection
• DevOps: Docker Compose with backend, frontend, PostgreSQL, and Redis

Local Requirements

• Docker and Docker Compose
• Go 1.22 or newer for local agent builds
• Python 3.12 or newer for local backend development outside Docker
• Node.js 20 or newer for local frontend development outside Docker

Start With Docker Compose

docker compose up --build

Backend: http://localhost:8000

Frontend: http://localhost:3000

PostgreSQL: localhost:5432

Redis: localhost:6379

Verify Backend Health

curl http://localhost:8000/health

Expected response:

{
  "status": "ok",
  "service": "linux-command-center-backend"
}

Phase 1 Local Auth

The backend seeds a local admin user from environment variables when it starts:

ADMIN_USERNAME=admin
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=change-me-now
ADMIN_DISPLAY_NAME=Administrator

Use admin / change-me-now at http://localhost:3000/login in local development.

The backend uses an HttpOnly lcc_session cookie and requires X-CSRF-Token on unsafe authenticated requests such as logout.

Phase 2 Node Enrollment

Admins can create one-time enrollment tokens from http://localhost:3000/dashboard/nodes.

After building the agent, enroll a host with the token shown in the dashboard:

cd agent
./command-agent enroll --server-url http://localhost:8000 --token <enrollment-token>
./command-agent connect

For local testing without writing /etc/linux-command-agent/config.toml, pass a temporary config path:

./command-agent enroll --server-url http://localhost:8000 --token <enrollment-token> --config /tmp/helix-agent.toml
./command-agent connect --config /tmp/helix-agent.toml

Enrollment tokens and agent tokens are stored only as hashes in PostgreSQL. The WebSocket requires agent.auth as the first message before any other agent message is accepted.

Access Frontend

Open http://localhost:3000.

The home page should show:

Linux Command Center
Custom Linux fleet management dashboard

Build The Go Agent

cd agent
go build -o command-agent ./cmd/command-agent
./command-agent version

Expected output:

linux-command-agent 0.1.0

Phase 0 Acceptance Criteria

• Repository structure exists
• FastAPI backend starts
• Backend config loader works
• PostgreSQL connection scaffolding exists
• SQLAlchemy base/session exists
• Alembic scaffolding exists
• /health returns OK
• Structured logging exists
• Root .env.example exists
• Next.js TypeScript frontend starts
• App Router routes exist
• API client helper exists
• Base layout exists
• Login placeholder page exists
• Dashboard placeholder page exists
• Go agent module exists
• Agent config loader exists
• Agent CLI exists
• Agent version command works
• Systemd unit template exists
• Install script placeholder exists
• Docker Compose starts backend, frontend, Postgres, and Redis
• Backend health endpoint returns OK through Docker
• Frontend loads in browser through Docker
• Agent binary builds locally