polyclaw v5.0.0

Setup Wizard

Once polyclaw finishes building and passes its health check, the TUI automatically opens the Setup screen in your default browser. From here you configure authentication, bot settings, and infrastructure.

Setup Screen

Setup screen

Authentication

Understand what these logins mean

Both Azure Login and GitHub Login are required during setup. You cannot skip either one at this stage.

GitHub Login authenticates with GitHub Copilot. The Copilot SDK is the agent’s reasoning engine—without it, polyclaw cannot function. This authentication must remain active for the lifetime of the agent. Your GitHub account determines which Copilot models and rate limits are available.

Azure Login signs you in with the Azure CLI. During setup, your Azure identity is used to provision infrastructure (Bot Service, Container Registry, Key Vault, etc.). After setup, the agent runtime operates under its own Azure identity—a service principal (Docker) or user-assigned managed identity (Azure Container Apps) with least-privilege RBAC. See Agent Identity for details.

The runtime identity is scoped to:

  • Bot Service Contributor on the resource group (create/update bot registrations)
  • Reader on the resource group (enumerate resources)
  • Key Vault access (read/write secrets)
  • Session Executor (if sandbox is configured)

No elevated roles (Owner, Contributor, User Access Administrator) are assigned to the runtime. The security preflight checker verifies this. Your personal Azure CLI session remains on the admin container and is not shared with the runtime.

To further limit exposure, enable Guardrails to require human approval before the agent executes high-risk tools. Enable Sandbox Execution to redirect code execution to isolated Azure Container Apps sessions.

Status indicators for Azure, GitHub, and tunnel connectivity. Each can be initiated directly from this page:

  • Azure Login – opens device-code flow for Azure CLI authentication
  • Azure Logout – signs out of the current Azure CLI session
  • GitHub Login – authenticates with GitHub Copilot via device code
  • Set GitHub Token – manually configure a GitHub PAT
  • Start Tunnel – starts a Cloudflare tunnel to expose the bot endpoint publicly

You can sign out of Azure after setup

Your personal Azure CLI session is used during setup for provisioning infrastructure and the runtime identity. Once the runtime identity is provisioned (service principal or managed identity), the agent authenticates independently. If you sign out of Azure on the admin container, core agent functionality (chat, skills, scheduling) continues to work. Operations that require your personal Azure CLI session (e.g., provisioning new infrastructure) will fail until you sign back in.

Bot Configuration

A form for configuring the Bot Framework deployment:

  • Resource Group – Azure resource group for bot resources (default: polyclaw-rg)
  • Location – Azure region (default: eastus)
  • Bot Display Name – display name for the Azure Bot resource
  • Telegram Token – Bot token from @BotFather (optional)
  • Telegram Whitelist – comma-separated list of allowed Telegram usernames

Set a Telegram whitelist

Without a whitelist, anyone who discovers your bot’s Telegram handle can send it messages—and the agent will respond using the runtime identity’s Azure credentials. That means a stranger could instruct your agent to take actions within the scope of its RBAC roles. Always set a whitelist with only the Telegram usernames you trust.

Infrastructure Actions

  • Save Configuration – persists bot and channel settings
  • Deploy Infrastructure – provisions Azure Bot Service, channels, and related resources
  • Deploy Content Safety – provisions Azure AI Content Safety for Prompt Shields integration (recommended)
  • Provision Agent Identity – creates the runtime service principal or managed identity with least-privilege RBAC
  • Decommission Infrastructure – tears down deployed Azure resources
  • Run Preflight Checks – validates bot credentials, JWT, tunnel, endpoint auth, channel security, identity, and RBAC
  • Run Security Preflight – comprehensive evidence-based validation of identity, RBAC roles, secret isolation, and credential separation
  • Run Smoke Test – end-to-end connectivity test for Copilot

Preflight checks

Identity Setup (Web Dashboard)

On first launch, the agent detects whether identity has been configured by checking the SOUL.md file and profile state. If not configured, a bootstrap prompt activates that walks through the setup conversationally.

Steps

  1. Identity – the agent chooses a name, emoji, location, and personality traits for itself
  2. SOUL.md – a Markdown file at ~/.polyclaw/SOUL.md defining the agent’s personality, communication style, and behavioral guidelines. Used as part of the system prompt for every interaction.
  3. Channel setup (optional) – if Bot Framework credentials are configured, the wizard can start a tunnel, deploy a bot resource, and configure Teams or Telegram channels
  4. Completion – the bootstrap prompt deactivates and the agent switches to normal operation

Agent profile configuration

Re-running Setup

To reset identity and re-enter the wizard:

  1. Delete ~/.polyclaw/SOUL.md
  2. Clear the profile state via /profile commands or delete ~/.polyclaw/agent_profile.json
  3. Restart Polyclaw

Customization Page

The web dashboard includes a Customization page that gives an overview of everything you can configure on your agent:

  • Skills – installed and self-created agent skills
  • Plugins – active MCP plugin connections
  • MCP Servers – registered Model Context Protocol servers
  • Scheduling – recurring and one-shot scheduled tasks

Customization main page