Getting Started

This guide walks you through logging in, registering your first device, and verifying that everything works — all in one page.

Prerequisites

Before you begin, make sure:

• An Umoo server is deployed and reachable (see Deployment)
• You have login credentials (email + password) from your administrator
• You have a Linux, macOS, or OpenWrt device to register as an IoT node
• The target device can reach the Umoo server over HTTPS (port 8080) and gRPC (port 8443)

Step 1 — Log In

1. Open your browser and navigate to your Umoo instance (e.g. https://umoo.yun).
2. Enter your email and password, then click Sign In.
3. If you belong to multiple tenants, select the organization you want to work in.

Your session lasts 15 minutes and refreshes automatically. If you see "Session expired", sign in again.

Step 2 — Create a Device Group

Device groups let you organize devices and apply configuration, rollouts, and plugin settings as a unit. Create one before adding devices.

1. Go to Devices in the left sidebar.
2. Click the Groups tab.
3. Click + Create Group.
4. Enter a name (e.g. edge-gateways) and optional description.
5. Click Create.

You can skip this step — devices can be registered without a group and assigned later.

Step 3 — Register Your First Device

Device registration uses claim tokens: single-use, time-limited tokens that authorize a device to self-register and receive its mTLS certificate.

Generate a claim token

1. Go to Devices in the left sidebar.
2. Click + Add Device in the top-right corner.
3. Optionally select a Device Group and a TTL (token lifetime: 1 hour, 24 hours, 7 days, or no expiry).
4. Click Generate.

The dialog shows two installation methods:

Option A — Quick Install (recommended)

A single command that downloads the agent, installs it as a system service, registers the device, and starts it:

curl -fsSL https://umoo.yun/api/v1/agent/install.sh | CLAIM_TOKEN=<token> sudo sh

This script:

• Detects your OS (Linux, macOS) and architecture (amd64, arm64, armv7)
• Downloads the correct umoo-agent binary from the server
• Installs it to /usr/local/bin/umoo-agent
• Creates a system service (systemd, launchd, procd, or SysV init)
• Bootstraps the agent with the claim token
• Enables and starts the service

That's it. Your device will appear in the Devices list within seconds.

Option B — Manual Install

If you prefer to control each step:

1. Download the agent binary:

# Auto-detect architecture
curl -fsSL -o /usr/local/bin/umoo-agent \
  https://umoo.yun/api/v1/agent/download/linux/amd64
chmod +x /usr/local/bin/umoo-agent

Available binaries: linux/amd64, linux/arm64, linux/armv7, darwin/amd64, darwin/arm64.

2. Bootstrap (register with the server):

sudo umoo-agent bootstrap \
  --claim-token <token> \
  --server-url https://umoo.yun \
  --data-dir /var/lib/umoo-agent

This exchanges the claim token for an mTLS client certificate. The token is consumed and cannot be reused.

3. Start the agent:

# systemd (most Linux distros)
sudo systemctl enable --now umoo-agent

# OpenWrt (procd)
/etc/init.d/umoo-agent enable && /etc/init.d/umoo-agent start

# macOS (launchd)
sudo launchctl load /Library/LaunchDaemons/com.umoo.agent.plist

# Manual foreground (any OS)
sudo umoo-agent --data-dir /var/lib/umoo-agent

Using the CLI

You can also generate claim tokens from the command line:

# Generate a claim token
umoo-cli device create-claim-token --tenant <TENANT_ID> --group-id <GROUP_ID> --ttl 3600

# Then install on the device as shown above

Step 4 — Verify the Device Is Online

1. Go to Devices in the sidebar.
2. Your new device should appear with a green Online badge.
3. Click the device row to open its detail page.

The device detail page has several tabs:

Tab	What it shows
Detail	Name, hardware info, IP address, OS, agent version, group membership
Shadow	Desired vs. reported state (JSON), used for configuration sync
Terminal	Browser-based shell access to the device (requires Terminal plugin)
Monitor	CPU, memory, disk, and network metrics (requires Telemetry plugin)
Events	Audit trail: provisioned, connected, config changes
Logs	Device log stream (requires Logs plugin)

If the device shows Offline, check that it can reach the server on port 8443 (gRPC/mTLS). Check agent logs with journalctl -u umoo-agent -f.

Step 5 — Open a Terminal Session

With the Terminal plugin enabled, you can get a shell on any online device directly from the browser:

1. Open a device's detail page.
2. Click the Terminal tab.
3. A WebSocket-backed PTY session opens in your browser.

The connection flows through: Browser → WebSocket → NATS → Agent → PTY. All sessions are RBAC-protected and audit-logged.

Step 6 — View Device Metrics

New tenants automatically get a Fleet Overview dashboard with pre-built panels for device count, online rate, CPU, memory, and disk usage.

1. Go to Monitor in the sidebar.
2. The default dashboard shows fleet-wide metrics.
3. For per-device metrics, open any device and click the Monitor tab.

The Telemetry plugin collects system metrics every 60 seconds by default. You can adjust the interval and enabled metrics in Settings → Plugin Config → Telemetry.

Core Concepts

Concept	Description
Tenant	A logical organization. All data is isolated per tenant via PostgreSQL Row-Level Security.
Device	An edge node running umoo-agent, authenticated with an mTLS client certificate.
Device Group	A named collection of devices. Target for rollouts, plugin configs, and monitoring.
Shadow State	Desired/reported JSON document synced between backend and device. The backend sets desired state; the agent reports actual and reconciles the difference.
Plugin	A runtime component that adds functionality: WireGuard networking, telemetry, terminal, log shipping, container management. Configured per tenant and per group.
Rollout	An orchestrated update campaign targeting a device group, using rolling, canary, or blue-green strategy.
Application	A container image or script packaged with versioned releases, deployed to devices via rollouts.

RBAC Roles

Role	Capabilities
viewer	Read-only access to devices, events, metrics
operator	Viewer + manage devices, trigger rollouts, open terminals
tenant_admin	Operator + manage users, apps, network, alert rules, notification channels
super_admin	Platform-wide: manage tenants, quotas, platform users, platform alerts

Role assignments are per-tenant. A user can be operator in Tenant A and viewer in Tenant B. Custom roles with fine-grained permissions are also supported.

Platform Navigation

The left sidebar groups all platform features:

Section	Features
Dashboard	Fleet overview, KPIs, quick links
Devices	Device list, groups, device detail
Applications	App catalog, versions, deployments
Containers	Remote Docker/Podman management on devices
Rollouts	Rollout orchestration (rolling, canary, blue-green)
Network	WireGuard mesh subnets, peers, VPN connections
Monitor	Prometheus-backed dashboards with custom panels
Alerts	Active alerts, rule groups, notification channels, history
Events	System event log
Users	User accounts, roles, invitations
Tenants	Tenant management and plugin config (super admin)
Settings	API keys, audit log, plugin configuration

What's Next

Goal	Guide
Deploy a containerized app to your fleet	Applications
Manage Docker containers on devices	Containers
Orchestrate updates across device groups	Rollouts
Set up WireGuard mesh networking	Network
Configure monitoring dashboards	Monitoring
Set up alert rules and notifications	Alerts
Manage users and custom roles	Users & RBAC
Use the CLI for automation	CLI Reference
Build a custom plugin	Developing Plugins