Quick Start

Generated from README.md in the repository. Edit it there; this wiki is rebuilt on every change.

Quick start

I want to...	Use	Time
Run it anywhere in one command	Docker	1 min
Run it in production with Docker (HTTPS + MariaDB)	Production Compose	5 min
Keep it running with settings in a file	Docker Compose	3 min
Develop on my PC	Local	2 min
Try it against a realistic fleet, no hardware	Sandbox	5 min
Run it for real behind TLS	Production on EC2	20 min

1. Docker (any machine, amd64 or arm64)

docker run -d --name edgeshell -p 5000:5000 \
  -e SECRET_KEY="$(openssl rand -hex 32)" \
  -e CREDENTIAL_KEY="$(openssl rand -hex 32)" \
  -e SESSION_COOKIE_SECURE=false \
  -v edgeshell_instance:/app/instance -v edgeshell_uploads:/app/uploads \
  --add-host host.docker.internal:host-gateway \
  devprincekumar/edgeshell:latest

Open http://localhost:5000 and sign in as admin / admin123. The first sign-in sets up two-factor authentication (scan the QR code with an authenticator app and save the backup codes), a new password and your personal email. Docker pulls the right architecture automatically.

Important

Save the CREDENTIAL_KEY you used. It encrypts the stored node SSH passwords, so restarting with a different key means re-entering them. The Compose setup below keeps both keys in .env for you.

2. Docker Compose

git clone https://github.com/855princekumar/edgeshell.git && cd edgeshell
cp .env.example .env
python -c "import secrets; print('SECRET_KEY=' + secrets.token_hex(32))"
python -c "import secrets; print('CREDENTIAL_KEY=' + secrets.token_hex(32))"
# paste both lines into .env, then:
docker compose up -d            # pulls devprincekumar/edgeshell
docker compose up -d --build    # or build from this checkout

Data persists in the edgeshell_instance and edgeshell_uploads volumes. To reach nodes over a mesh from inside a container, see docs/VPN-NETWORK.md.

Production Compose (HTTPS + MariaDB)

docker/compose.yaml runs EdgeShell behind nginx, with MariaDB, privacyIDEA (2FA) and certbot (Let's Encrypt once you set a domain). All data lives in a ./data folder on the host, and only nginx's ports 80 and 443 are exposed.

mkdir -p edgeshell/nginx && cd edgeshell
base=https://raw.githubusercontent.com/855princekumar/edgeshell/main/docker
curl -fsSLO $base/compose.yaml
curl -fsSLo nginx/entrypoint.sh $base/nginx/entrypoint.sh
curl -fsSLo nginx/certbot.sh $base/nginx/certbot.sh
curl -fsSLO $base/lake-init.sh
curl -fsSLo .env $base/.env.example && chmod 600 .env
for k in SECRET_KEY CREDENTIAL_KEY DB_PASSWORD DB_ROOT_PASSWORD MFA_ADMIN_PASSWORD MFA_PEPPER MFA_DB_PASSWORD MFA_SECRET_KEY; do
  sed -i "s|^$k=.*|$k=$(openssl rand -hex 32)|" .env; done
docker compose up -d       # http://<server IP>; add a domain later for HTTPS

Backups, upgrades and every setting are documented on the Docker Hub page.

3. Local (Windows, macOS, Linux)

Requires Python 3.11 to 3.13 and Git.

git clone https://github.com/855princekumar/edgeshell.git
cd edgeshell
python run.py --dev

run.py creates a virtual environment, installs dependencies, generates a .env with random secret keys, creates the database, and starts the server. (On Windows and macOS --dev is the default and can be left off. On Linux, python3 run.py without --dev runs the production installer instead.)

4. Sandbox: EdgeShell + an emulated fleet

Needs Docker with Compose v2, curl and Python 3.

git clone https://github.com/855princekumar/edgeshell.git && cd edgeshell
bash sandbox/run.sh --keep

This builds EdgeShell, starts Pi Fleet Emulator, spawns 6 Pi nodes, imports them, runs the full end-to-end suite and leaves everything running for you to explore:

Service	URL
EdgeShell	http://127.0.0.1:5050
Pi Fleet Emulator spawner	http://127.0.0.1:7070

The suite gives the sandbox admin account a random password each run. To sign in yourself, reset it with docker exec edgeshell-sandbox python manage.py create-admin --username me --email me@example.test --password <yours>. Drop --keep to tear everything down automatically.