Getting Started

From zero to a running Infra UI instance in minutes. This guide walks you through setup and agent management.

Overview

Infra UI is a modern infrastructure management platform built with FastAPI and DDD. It monitors containers, manages access, and orchestrates deployments. The platform includes an optional agent for remote host management and security scanning.

Prerequisites

Setup

1. Install

Pull the repository

 1git clone https://gitlab.com/fastapi6653130/anjou15-community.git (incoming)
 2cd anjou15-community

2. Configure

Set your environment variables in the .env file:

3. Launch

start all services with Docker Compose:

 3make start
 4make start-py

4. Deploy

Open the dashboard in your browser and start managing your infrastructure:

URL: http://localhost:9000

(Pro) Navigate to Admin → Agents to register and manage remote agents.

(Pro)Manage Agents

Infra UI includes an agent management platform for registering, monitoring, and controlling remote hosts. Agents communicate with the API via HTTPS to send heartbeats, receive commands, and report system metrics.

Architecture

Agents run a lightweight process that communicates with the Infra UI API. Each agent authenticates using a registration token and can be managed through the web dashboard or REST API.

┌──────────────────┐         ┌──────────────────┐
│   Agent (remote) │  HTTPS  │   Infra UI API   │
│                  │────────>│   localhost:9000  │
│  - Heartbeat     │         │                   │
│  - Commands      │<────────│  - Register agents│
│  - Metrics       │         │  - Assign tasks   │
└──────────────────┘         │  - Store data     │
                             └──────────────────┘

Installing the Agent

The agent is available as a Python package in its own repository:

From source

1# Clone and install
2git clone https://gitlab.com/fastapi6653130/infra-agent.git && cd infra_agent
3pip install -e ".[dev]"

Or with uv:

1uv sync

See agent_management_guide.md for a standalone binary build (PyInstaller) and scanner installation details.

Registering an Agent

Agents can be registered through the web UI or directly via the API.

Via the Web UI

1. Go to Admin → Agents

   Navigate to /admin/agents in the dashboard.

2. Click New Agent

   Open the creation form from the agents table.

3. Fill in the details

   Provide a hostname (unique identifier), display name, OS (linux/windows/macos), architecture (amd64/arm64), and agent version.

4. Create

   The agent appears with PENDING status until it connects.

Via the API

1curl -X POST http://localhost:9000/admin/agents \
2  -H "Content-Type: application/x-www-form-urlencoded" \
3  -d "hostname=wsl-ubuntu&os=linux&architecture=amd64&agent_version=1.0.0"

Agent Actions

Agents can be edited or deleted from the agents table in the web UI:

• Edit — Click the pencil icon to open a modal with pre-filled fields (hostname, display name, OS, architecture, version).
• Delete — Click the trash icon and confirm to permanently remove the agent.

Registration Tokens

Tokens are used by agents to authenticate during registration. Generate one via the web UI or API.

Generating a Token

1. Navigate to Admin → Tokens (/admin/agents/tokens).
2. Click Generate Token.
3. Set the expiration date in the modal (default: 1 hour).
4. Click Generate and copy the token — it's shown only once.

Tokens can be deleted from the table using the Delete button (visible on all tokens regardless of status).

Using a Token (Agent-Side)

1curl -X POST http://localhost:9000/api/v1/agents/register \
2  -H "Content-Type: application/json" \
3  -d '{
4    "hostname": "wsl-ubuntu",
5    "token": "<your-registration-token>",
6    "os": "linux",
7    "architecture": "amd64",
8    "agent_version": "1.0.0"
9  }'

Agent Status

Sending Commands

Commands can be sent to agents through the web UI or the REST API.

Via the Web UI

1. Go to Admin → Agents.
2. Click the Terminal icon on an agent row.
3. View command history and results.

Via the API

1# Send a command to an agent
2curl -X POST http://localhost:9000/api/agents/<agent_id>/commands \
3  -H "Content-Type: application/json" \
4  -d '{"command": "uname -a"}'

Agent Daemon (Transport Layer)

The infra-agent repository (gitlab.com/fastapi6653130/infra-agent.git) includes a transport layer that runs as a background daemon, continuously communicating with the Infra UI API. See Installing the Agent to get it.

Daemon Flow

1. Read config

   The agent reads its configuration (token, API URL, intervals).

2. Register

   Calls POST /api/v1/agents/register with the token → receives agent_id and server configuration.

3. Start background loops

   Three concurrent loops run: Heartbeat (every 30s), Container report (every 60s, if Docker SDK installed), Command poll (every 15s).

Running as a Daemon

1# Set token and start
2AGENT_REGISTRATION_TOKEN="AGT_xxx" python -m agent --daemon

3# Or via config file
4cat > agent.yaml << EOF
api_url: "http://localhost:9000"
registration_token: "AGT_xxx"
heartbeat_interval: 30
container_report_interval: 60
command_poll_interval: 15
EOF

5python -m agent --daemon -c agent.yaml

Config Options (Environment Variables or YAML)

The agent also reads heartbeat from the server's registration response, overriding the local config value.

Heartbeat & Graceful Shutdown

While the process runs, send heartbeats to stay ONLINE. On SIGTERM/SIGINT, call the shutdown endpoint so the agent goes OFFLINE immediately:

1# Periodic heartbeat (agent-side)
2curl -X POST http://localhost:9000/api/v1/agents/heartbeat \
3  -H "Content-Type: application/json" \
4  -d '{"agent_id": "<agent_id>", "hostname": "wsl-ubuntu"}'

5# Graceful shutdown (on SIGTERM/SIGINT)
6curl -X POST http://localhost:9000/api/v1/agents/shutdown \
7  -H "Content-Type: application/json" \
8  -d '{"agent_id": "<agent_id>", "hostname": "wsl-ubuntu"}'

IAM & RBAC

Infra UI provides two layers of access control: coarse-grained identity roles and granular resource-level RBAC permissions.

Overview

User → Group → Roles → Permissions

1# List available permissions
2GET /iam/permissions

3# Create a role with permissions
4POST /iam/roles
5{
6  "name": "container-manager",
7  "description": "Can manage containers",
8  "is_default": false,
9  "permission_ids": ["uuid-of-container:create", "uuid-of-container:read"]
10}

11# Update a role's permissions
12PUT /iam/roles/{role_id}
13{
14  "permission_ids": ["uuid-of-perm1", "uuid-of-perm2"]
15}