Installation & Deployment

Docker — the standard deployment method

CortexShell is packaged and distributed as a Docker container image. Docker is the recommended and most straightforward deployment method for all environments. The platform ships as a single image that includes the backend application server, the web interface, and all runtime dependencies. A companion docker-compose configuration covers the full stack — the CortexShell application container, a database container for persistent storage, and optionally a reverse proxy container for TLS termination.

The Docker-based deployment requires no package manager, no manual dependency installation, and no language runtime setup on the host. Upgrades are performed by pulling the new image version and restarting the container — the process takes under a minute and carries no risk of dependency conflicts. Configuration is passed through environment variables, making the deployment compatible with any secrets management system or CI/CD pipeline.

This model also means that CortexShell is entirely isolated from the host operating system. It does not modify system files, does not require privileged access to the host, and can be removed completely by stopping and deleting the containers and their associated volumes.

Linux — native server deployment

Any Linux distribution capable of running Docker Engine is a supported deployment target. This covers the full range of common server distributions: Debian and Ubuntu LTS releases, Red Hat Enterprise Linux and its derivatives (Rocky Linux, AlmaLinux), SUSE Enterprise Linux, and minimal cloud-optimised images such as Ubuntu Server Minimal, Debian Slim, or Alpine-based hosts.

The typical Linux deployment scenario is a dedicated virtual machine or bare-metal server running a recent LTS distribution with Docker Engine installed. The CortexShell containers run as unprivileged services managed by Docker's own process supervision. For production deployments on Linux, it is common to place a reverse proxy — Nginx or Caddy — in front of the application to handle TLS termination, HTTP/2, and optional rate limiting. CortexShell includes a ready-to-use Caddy configuration for this purpose.

Linux also offers the most flexibility for storage configuration. Session recordings, audit logs, and database files can be placed on separate volumes — on a mounted NFS share, a network-attached block device, or a local SSD — depending on the performance and retention requirements of the deployment.

Windows — WSL 2 and Docker Desktop

On Windows, CortexShell can be deployed through two routes that both ultimately rely on Linux container execution: Windows Subsystem for Linux 2 (WSL 2) and Docker Desktop for Windows.

WSL 2 provides a genuine Linux kernel running inside a lightweight utility VM on Windows. With Docker Engine installed inside a WSL 2 distribution, CortexShell runs in exactly the same way as on a native Linux host. This approach gives full control over the Linux environment, requires no Docker Desktop licence, and is suitable for both development and production-equivalent use on Windows Server or Windows 11 machines. The WSL 2 virtual network is reachable from Windows applications and from the LAN, making the deployment accessible through a standard browser without additional configuration.

Docker Desktop for Windows is the more accessible route for teams unfamiliar with WSL configuration. It provides a graphical management interface for containers, integrates with WSL 2 under the hood, and supports docker-compose natively. For evaluation, development environments, or small internal deployments within a Windows-dominated organisation, Docker Desktop is a practical and well-supported option. Note that Docker Desktop licensing terms apply to commercial use and should be reviewed for your organisation's size.

In both cases, the CortexShell containers and their data volumes live inside the WSL 2 virtual machine filesystem. For persistent deployments on Windows, it is recommended to bind-mount data volumes to a path inside the WSL 2 instance rather than relying on Docker's default volume location, which may be affected by WSL state resets.

Cloud deployment

CortexShell is well-suited to cloud deployment and is regularly used on virtual machines across all major cloud providers. Because it runs as Docker containers, cloud deployment follows the same pattern as a Linux server deployment — provision a VM, install Docker Engine, and bring up the compose stack.

AWS deployments typically run on EC2 instances (t3 or t4g family for cost efficiency, m6i for higher throughput). The CortexShell data directory can be backed by an EBS volume for persistence, and CloudFront or an ALB can be placed in front for public-facing deployments. Secrets — SMTP credentials, Vault tokens, database passwords — map naturally to AWS Secrets Manager or Parameter Store, with values injected at container startup via environment variables.

Google Cloud users typically deploy on Compute Engine VMs or on Cloud Run if a serverless-adjacent approach is preferred. Note that Cloud Run's ephemeral filesystem requires that all stateful data — recordings, database files — be externalised to Cloud SQL and Cloud Storage respectively; this configuration is supported but requires additional setup compared to the standard VM deployment.

Microsoft Azure deployments run on Azure VMs (B-series for development, D-series for production). Azure Blob Storage can be mounted as a backend for session recording storage, and Azure Key Vault integrates with CortexShell's HashiCorp Vault support through the Vault Azure Secrets Engine.

DigitalOcean, Hetzner, OVH, and other VPS providers are fully supported and commonly used for CortexShell deployments, particularly for teams managing infrastructure in European data centres. A Hetzner CX22 or DigitalOcean Droplet at the 4 GB RAM tier is sufficient for deployments managing up to 50 servers.

For all cloud deployments, restrict inbound access to the CortexShell web port to known IP ranges or route through a VPN. The platform manages privileged access to your infrastructure and should not be exposed to the public internet without appropriate network controls in place.

Kubernetes

CortexShell can be deployed in a Kubernetes cluster for organisations that already operate a Kubernetes-based platform and prefer to centralise all workloads within that environment. The Docker image is compatible with any OCI-compliant container runtime, and the application can be defined as a Kubernetes Deployment with a corresponding Service and Ingress.

A CortexShell Kubernetes deployment typically involves a single-replica Deployment for the application (horizontal scaling is not required for the application tier — CortexShell is stateful by design and handles all workload within a single instance), a PersistentVolumeClaim for session recordings and database storage, a Secret resource for environment variables, and an Ingress resource with TLS termination via cert-manager.

The stateful nature of the application — specifically the session recording filesystem — means that storage class selection matters. ReadWriteOnce block storage (AWS EBS CSI, GCP Persistent Disk, Azure Disk) is appropriate for single-node deployments. If the scheduling requirements of your cluster might move the pod between nodes, a ReadWriteMany-capable storage class (NFS, AWS EFS CSI, Longhorn) is required to avoid data loss during rescheduling.

For teams using Helm, a community-maintained chart is available that covers the full deployment including ConfigMap management, rolling upgrade strategy, and liveness/readiness probes. Managed Kubernetes services — Amazon EKS, Google GKE, Azure AKS — are all supported deployment targets and are used in production by CortexShell customers.

System requirements

CortexShell's resource requirements scale primarily with two factors: the number of managed hosts and the volume of concurrent terminal sessions. The following guidelines cover the most common deployment sizes.

CPU usage is driven by concurrent SSH sessions and AI request processing. A CortexShell instance managing 50 hosts with typical usage — a few concurrent terminal sessions, periodic scheduled jobs — runs comfortably on 2 vCPUs with headroom to spare. CPU spikes occur when CortexShell executes fleet-wide commands across many hosts simultaneously; for fleets above 100 servers, 4 vCPUs are recommended to maintain responsiveness during parallel operations.

RAM requirements are modest: the application server and database together consume approximately 400–600 MB at idle. Active terminal sessions add roughly 20–40 MB per open session. For a team of 10 engineers with several concurrent sessions, 2 GB provides comfortable headroom.

Disk storage is the most variable factor, driven almost entirely by session recording retention. Each recorded terminal session typically occupies between 50 KB and 2 MB depending on session duration and output volume. A team running 200 sessions per month with a 12-month retention policy should budget approximately 5–20 GB for recordings alone. Deployments with compliance requirements mandating extended retention — 3 to 6 years — should plan storage accordingly and consider mounting an external volume or object storage backend for the recordings directory.

The database itself is lightweight. Even for deployments managing hundreds of hosts with years of audit log history, the database rarely exceeds 1–2 GB.

Network and connectivity

CortexShell requires outbound network access from the deployment host to the managed servers on their SSH port (typically port 22, though non-standard ports are supported). The platform acts as an SSH client — it does not require any agent installation on managed servers, no inbound firewall rule changes on the servers themselves, and no persistent tunnel or VPN setup. If your deployment host can reach a server over SSH, CortexShell can manage it.

For AI functionality, CortexShell requires outbound HTTPS access to the API endpoints of the configured AI providers (Anthropic, OpenAI, Google, etc.). For deployments using locally-hosted models via Ollama or LM Studio, this requirement is eliminated entirely — the AI backend runs on your own infrastructure.

The web interface is served over HTTPS on a single port (default 443, configurable). Users access CortexShell through a standard browser — no client software, browser extension, or VPN client is required on user machines.

HashiCorp Vault integration

CortexShell includes native integration with HashiCorp Vault for secrets management. When Vault is configured, all SSH credentials, API keys, and SMTP passwords are stored in Vault's KV v2 secrets engine rather than in CortexShell's own database. This makes CortexShell fully compatible with enterprise secrets management policies and eliminates any plaintext credential storage from the application layer.

Vault can be deployed as an additional container alongside CortexShell in the same compose stack, or pointed at an existing Vault instance in your infrastructure. Both Vault OSS (open source) and Vault Enterprise are supported. Vault is optional — teams without an existing Vault deployment can use CortexShell's built-in encrypted credential storage and migrate to Vault at any point without service interruption.