Skip to content
User Guide

Introduction

What MisterShell is

MisterShell is a unified remote-access and fleet-intelligence platform for the infrastructure you operate — network devices, Linux and Windows servers, cloud accounts, and Kubernetes clusters. From a single browser tab you can:

  • Connect interactively to any managed resource — SSH terminals, cloud CLI shells (AWS, Azure), Kubernetes shells, database (SQL) shells, graphical remote desktops (Windows over RDP, or any host over VNC), and browser-based web application sessions (HTTP/HTTPS) — with every session recorded for audit and replay, and the option to share a live session with a teammate or an account-less external guest.
  • Govern that access with a session-policy firewall (allow/deny rules enforced when a session opens and on each command typed), encrypted credentials, read-only live shadowing of any session, and an audit trail you can forward to your own logging or SIEM systems.
  • Inventory your estate in a hierarchy of locations, with per-resource identification, configuration, and health data kept up to date automatically.
  • Monitor the whole estate from dashboards — an overview, a map, a site grid, live health, historical trends, a real-time activity feed, and on-demand network diagnostics.
  • Detect & collect (licensed) — watch network traffic with passive IDS sensors that stream intrusion-detection alerts, and ingest device syslog into one searchable, correlatable store.
  • Track configuration drift over time, down to the level of individual elements (interfaces, running-config, policies, cluster manifests).
  • Automate reactions to events with a visual playbook editor — react to a health change, a configuration drift, a session ending, etc.
  • Report on inventory, configuration, and activity, on demand or on a schedule, with optional AI-generated executive summaries.
  • Ask an AI assistant for help with any of the above, either interactively in a chat, as in-session guidance, or as scheduled background work.

You can also use your own SSH client. The SSH gateway and Text UI let you browse resources, work in multiple shell tabs, and use Session Assist from your terminal. Direct resource connections support automation tools, and SFTP provides access to the location file catalog. The same account permissions and session governance apply.

MisterShell is self-hosted. You install it on your own infrastructure and control where its data is stored. Optional integrations, including AI providers, receive the data needed for the features you enable. Licensing is offline. The platform is licensed per managed resource, and the Free edition covers 25 resources with no time limit.

Who MisterShell is for

  • Network engineers managing global or hybrid networks and looking for a single pane of glass over switches, routers, firewalls, and the adjacent cloud / Kubernetes fabric.
  • System administrators operating Linux and Windows estates alongside the cloud accounts and clusters they depend on.
  • Platform and SRE teams who want configuration, health, and activity data captured consistently across a diverse estate so that incident response, change review, and compliance reporting are no longer a manual aggregation exercise.

Power users and read-only users are both first-class citizens: role-based access control lets you grant granular permissions per location and per feature area.

High-level architecture

MisterShell is made of three cooperating tiers:

flowchart TB
  browser["Web UI · browser"]
  sshClient["SSH client · Text UI · SFTP"]
  apiClient["REST API client<br/>scripts · CI · integrations"]
  mcpClient["MCP client<br/>external AI assistants &amp; agents"]
  subgraph coreServer["Core server · control plane"]
    core["Web UI · REST API · MCP endpoint<br/>event bus · session gateway"]
    reldb[("Relational data store<br/>inventory · users · history · snapshots")]
    memdb[("In-memory store<br/>live caches · session state · buffers")]
    core --- reldb
    core --- memdb
  end
  browser --> core
  sshClient --> core
  apiClient --> core
  mcpClient -. "personal API key" .-> core
  worker["Worker<br/>(+ optional syslog collector)"]
  sensor["Passive IDS sensor"]
  proxy["Proxy · external guest bridge"]
  worker -. "authenticated outbound" .-> core
  sensor -. "authenticated outbound" .-> core
  proxy -. "authenticated outbound" .-> core
  resources["Managed resources<br/>SSH · RDP / VNC · cloud · Kubernetes · databases"]
  worker --> resources

By default the two data stores are embedded inside the core container; for production you point the core at externally managed services instead — see Deployment.

1. Core server

The core server is the control plane. It runs in a single container that serves the web UI, the REST API, the real-time event bus, and the session gateway. It stores your inventory, configuration history, session recordings, automation playbooks, licenses, and user identities.

Two data services back the core:

  • A relational data store — the authoritative record for inventory, users, roles, licenses, tasks, automation history, reports, and configuration snapshots.
  • A high-performance in-memory store — used for live feed caches, recent-event buffers, session state, and low-latency counters that must refresh many times per second.

By default both data services are embedded inside the core container so a single command brings up a complete workspace. For production deployments you can point the core at externally managed data services instead — see Deployment.

2. Workers

Workers are lightweight agents deployed close to the resources they manage. A worker opens an authenticated outbound connection to the core and receives the work it is responsible for: connectivity checks, snapshot collection, session proxying, automation actions. All traffic between worker and core flows over a single outbound channel; resources themselves are never exposed to the public internet through MisterShell.

  • The core container ships with an embedded worker that handles any inventory reachable from the core host itself — perfect for small single-site deployments.
  • For distributed environments you register additional remote workers, one per site / region / network segment, and route work to them by location: each worker is assigned to a location, and a resource’s location determines which worker handles its tasks.

Workers are stateless and disposable: they can be replaced or scaled up without affecting history or configuration — all state lives in the core server. A worker can additionally run a syslog collector (licensed feature) that ingests logs from your devices into MisterShell — see Collectors.

Workers are the first of several remote components that all follow the same model — a single authenticated outbound connection to the core, token-based enrolment, and live status reporting:

  • IDS sensors (licensed feature) — passive intrusion-detection sensors that watch network traffic and stream alerts back to the core. See Sensors.
  • Proxies (licensed feature) — public-facing bridges that let external session guests reach a shared session without exposing the core. See Proxies.

Like workers, sensors and proxies are declared in the UI, deployed close to where they are needed, and authenticate with a one-time token; you see each one’s live status as it checks in.

3. Browser, SSH, API, and MCP access

The same MisterShell instance provides several ways to work with your resources:

  • The web UI — everything this guide describes: browse, automate, connect, report.
  • The SSH gateway — a Text UI with resource browsing and shell tabs, direct connections for terminal clients and automation tools, and SFTP access to catalog files.
  • The REST API — programmatic access for scripts, CI pipelines, integrations, and third-party dashboards. Users authenticate with personal API keys generated from the Account → Account Security → My API key page.
  • The MCP endpoint — an authenticated Model Context Protocol surface that lets external AI assistants and agents (your own tools, an IDE assistant, a desktop agent) read inventory, look up changelog and events, and run read-only diagnostics over your fleet. It authenticates with the same personal API key as the REST API and is scoped to that user’s permissions.

Access through each interface follows your account permissions and resource policies.

Where AI fits

AI assistance in MisterShell is opt-in and optional. It is built as a composable set of primitives rather than a pre-wired feature:

  • Models — register any number of large-language-model providers (Anthropic, OpenAI, Azure OpenAI, Google, AWS Bedrock, Mistral, xAI, Cohere, OpenRouter, or self-hosted via Ollama). You own the provider account and the billing.
  • Agents — named combinations of model, prompt, and tool access. Built-in agents handle configuration analysis, session assistance, chat, and summary generation; you can create your own.
  • Tools — the vocabulary MisterShell exposes to agents so they can read inventory, look up changelog entries, query events, and trigger read-only diagnostic commands on real resources.
  • Surfaces — the places where AI appears: the chat page, the Quick Assist button next to a resource or a config diff, in-session assistance that follows along while you type, and the Run Agent automation action that lets you wire agents into event-driven flows.

No data is sent to a model provider until you explicitly invoke an agent. The set of tools an agent may call is configurable per agent.

flowchart LR
  subgraph agent["An agent"]
    model["Model provider<br/>your account"]
    prompt["Prompt"]
    tools["Allowed tools"]
  end
  surfaces["Invoked from<br/>chat · quick assist · in-session · automation action"]
  surfaces --> agent
  agent --> act["Reads inventory, change log, events;<br/>runs read-only diagnostics"]
  act --> reply["Answer · summary · action result"]

What’s next