Documentation

Last updated: 16 June 2026

This page is the primary documentation URL for Sandman Azure Marketplace offers. It is designed to be readable from a browser on the appliance or a management workstation without access to public source repositories.

Overview

Sandman schedules Azure virtual machines: admins define shift windows, users receive Microsoft Teams notifications before shutdown, and VMs deallocate automatically when shifts end (with optional postpone). The product runs as RPM packages on Azure Linux 3 ARM64 on a dedicated VM you deploy in your subscription.

  • Sandman — main API and dashboard (HTTPS, default port 8080 behind Caddy)
  • Sleepwalker — first-run and maintenance wizard (port 8091 during init/maintenance only)
  • Sandglass — scheduler for deallocate slots
  • Dreamcatcher — optional central audit ingest (gRPC)

Installation (Azure Marketplace)

  1. In Azure Portal, deploy the Sandman VM offer from Marketplace (or use the supplied ARM template). Choose plan tier: Startup (up to 10 scheduled VMs), Scaleup (50), or Corporate (unlimited scheduling cap).
  2. Provide an SSH public key (password authentication is disabled).
  3. Set inbound allowed CIDRs for HTTPS (443). Do not expose the admin wizard to the open internet without restricting source IPs.
  4. Optional: allow SSH (22) only from admin CIDRs; restrict or deny inbound 8091 except during init/maintenance.
  5. The template attaches a data disk (LUN 0) for /var/lib/sandman (database, Valkey, state).
  6. A system-assigned managed identity is created on the VM for Azure ARM access (Virtual Machine Contributor at subscription scope).
Air-gap note: After the VM is deployed, all configuration happens via HTTPS to your hostname or private IP. Outbound access requirements depend on your choices (Azure ARM, Microsoft Graph, Teams webhooks, Let’s Encrypt or uploaded TLS certs).

First boot & Sleepwalker onboarding

  1. Boot the VM. On first start, sandman-boot prepares the data disk, PostgreSQL, and Valkey.
  2. While initialized: false, Caddy redirects HTTP to Sleepwalker on port 8091 (ensure NSG allows your admin IP if needed).
  3. Open the wizard in a browser and complete:
    • Azure tenant ID, subscription ID, service principal (client ID / secret) for VM discovery
    • OIDC settings for Entra ID sign-in (redirect URI must match your public URL)
    • Admin Entra group object IDs
    • Public hostname and TLS mode (ACME HTTP/DNS or upload certificate)
    • Teams notification webhook (Logic App HTTP trigger) if enabled
  4. On completion, Sleepwalker writes /etc/sandman/config.yaml, updates Caddy, sets initialized: true, and enables the main Sandman service.
  5. Steady state: Sleepwalker is disabled; use HTTPS dashboard only. For maintenance, re-enable Sleepwalker via config and systemd (see Support).

Azure & Entra prerequisites

Before or during wizard setup, prepare in Microsoft Entra ID and Azure:

  • App registration for Sandman (client ID and secret, or managed identity where applicable)
  • Azure RBAC: Virtual Machine Contributor (or equivalent) at subscription scope for VM list/start/stop/deallocate
  • Microsoft Graph (application): User.ReadBasic.All with admin consent for directory user sync
  • OIDC (delegated): openid, profile, email, User.Read for dashboard login; redirect URI https://<your-host>/auth/callback
  • Groups claim in ID token for admin role mapping
  • Teams: Logic App or workflow with HTTP trigger URL configured in Sandman

Configuration reference

Main config file: /etc/sandman/config.yaml. Secrets may be overlaid via environment files under /etc/sandman/. Key sections:

  • sandman_url — public base URL
  • azure.* — tenant, subscription, client credentials, region
  • auth.oidc.* — Entra issuer, client ID/secret, redirect URL, admin group IDs
  • auth.valkey.* — session store (local on appliance)
  • teams.* — webhook URL and enable flag
  • database.* — PostgreSQL (local on appliance by default)
  • initialized / sleepwalker.enabled — lifecycle flags

VM discovery runs against the configured single subscription ID (all resource groups in that subscription). Use the admin dashboard to sync VMs, assign owners, and enable schedules.

Networking & security defaults

  • Inbound 443 from allowed CIDRs only (recommended)
  • Inbound 8091 only during init/maintenance, from admin CIDRs
  • SSH key-only login; disable broad SSH exposure
  • Operational logs: /var/log/sandman/

Air-gap & restricted networks

In environments with limited outbound internet:

  • Use uploaded TLS certificates instead of Let’s Encrypt if public ACME is unavailable.
  • Ensure the appliance can reach Azure Resource Manager and (if used) Microsoft Graph endpoints for your cloud (public Azure or private endpoints as you design).
  • Teams notifications require outbound HTTPS to your Logic App URL.
  • Apply RPM updates from media or an internal mirror if direct dnf access to the public repo is blocked.
  • Keep a copy of this documentation and the Support contact on an internal wiki for operators without general internet access.

Updates & plan changes

  • Minor upgrades: install updated sandman RPM via your update channel; run health checks (sandman check).
  • Changing Marketplace plan tier or golden image generation typically requires deploying a new VM and reattaching the existing data disk at LUN 0 — do not swap OS disks in place.
  • License limits are read from Azure instance metadata (compute.plan) at runtime.

Get help

Email support@sandmancloud.com with version, plan, and log excerpts. See the full Support page for response times and required details.

© 2026 Sandman