Self-Hosting

The Mesh is AGPL v3 licensed. Run your own sovereign mesh node on any machine.

One-Command Install

npx create-mesh-node

The CLI detects your OS and handles everything:

• Mac — installs k3d (Kubernetes-in-Docker), deploys locally
• Linux (VPS/droplet) — installs k3s (lightweight Kubernetes), deploys to production

What it does

1. Installs k3s or k3d (30 seconds)
2. Generates a JWT secret
3. Deploys mesh-server (Go) + mesh-web (Next.js) as Kubernetes pods
4. Configures TLS with Let's Encrypt (if you provide a domain)
5. Waits for everything to come up

With a domain (production)

npx create-mesh-node --domain mesh.example.com

Non-interactive

npx create-mesh-node --yes --mode cloud --domain mesh.example.com

Why Kubernetes?

The Mesh dynamically spawns bots and apps as containers at runtime. Docker Compose can't do that — it's static. The mesh server talks to the Kubernetes API to create Pods on demand.

k3s is a single 50MB binary that uses ~512MB RAM. create-mesh-node handles the install — you don't need to know Kubernetes.

Updating

# Update to latest
./deploy/update.sh

# Update to specific version
./deploy/update.sh v0.8.0

Zero-downtime rolling update — new pods come up before old ones terminate.

Server Requirements

Any provider works: DigitalOcean, Hetzner, Linode, Vultr, AWS, etc.

Manual Setup

If you prefer to set things up yourself:

# 1. Install k3s
curl -sfL https://get.k3s.io | sh -
export KUBECONFIG=/etc/rancher/k3s/k3s.yaml

# 2. Clone the repo
git clone https://github.com/Metatransformer/the-mesh /opt/the-mesh
cd /opt/the-mesh

# 3. Create secret
kubectl create namespace mesh-system
kubectl -n mesh-system create secret generic mesh-secrets \
  --from-literal=jwt-secret="$(openssl rand -hex 32)"

# 4. Deploy
kubectl apply -k k8s/overlays/self-host/

# 5. Wait for pods
kubectl -n mesh-system get pods -w

Docker Compose (lite mode)

For trying The Mesh without bots or app spawning:

git clone https://github.com/Metatransformer/the-mesh
cd the-mesh
cp .env.example .env
# Edit .env: set MESH_JWT_SECRET
docker compose up -d

API at http://localhost:4000, Web at http://localhost:3000.

Limitation: No dynamic bot/app spawning. Use npx create-mesh-node for the full experience.

Environment Variables

Developer Setup

For contributing to The Mesh:

make dev           # k3d cluster (full k8s, production parity)
make dev-native    # Go + Next.js directly (fastest iteration)
make status        # pod status
make logs          # server logs
make dev-stop      # tear down

Troubleshooting

Pods not starting:

kubectl -n mesh-system get pods
kubectl -n mesh-system describe pod <pod-name>
kubectl -n mesh-system logs deployment/mesh-server

Need help? GitHub Issues