Skip to content

Getting Started

Jump to bottom
TheMinecraftGuyGuru edited this page Jun 13, 2026 · 4 revisions

Getting Started

Get MuxCore running in under a minute. This guide covers installation, configuration, and loading your first modules via tags from the official spool.

Quick Start

Install from Source (Go)

go install github.com/Muxcore-Media/core/cmd/muxcored@latest
muxcored

This starts the loom with no modules — just the platform. You'll have a health endpoint at http://localhost:8080/health and a gRPC mesh at :9090. Nothing else happens until you load modules.

Load Modules with a Tag

Tags are curated module presets hosted in a spool. The official spool is at Muxcore-Media/spool:

# Start with the official default preset
muxcored --tag default

# Use a minimal preset
muxcored --tag minimal

Core fetches the tag definition from the spool, resolves the listed modules, and launches them as sidecar processes. Modules connect to the gRPC mesh and register themselves — no recompilation needed.

With a Custom Spool

muxcored --tag my-setup --spool https://github.com/my-org/my-spool

Security Warning: Third-party spools can list malicious modules. See Spool Security below.

With Docker

git clone https://github.com/Muxcore-Media/core.git
cd core
docker compose up

Add MUXCORE_TAG=default to your environment or docker-compose.yml to load modules.

Configuration

Configuration lives in muxcore.json in the working directory. Set MUXCORE_CONFIG to use a custom path. Environment variables override file values.

Minimal Config

{
  "server": {
    "addr": ":8080"
  },
  "grpc": {
    "addr": ":9090"
  },
  "log": {
    "level": "info",
    "format": "text"
  }
}

Full Configuration Reference

Server Settings (server)

Field Type Default Description
addr string ":8080" HTTP listen address
read_timeout int 15 Read timeout in seconds
write_timeout int 15 Write timeout in seconds
cert_file string — Path to TLS certificate PEM
key_file string — Path to TLS private key PEM

gRPC Settings (grpc)

Field Type Default Description
addr string ":9090" gRPC listen address
cert_file string — Path to TLS certificate file
key_file string — Path to TLS private key file
mtls_enabled bool false Require mutual TLS
ca_cert_file string — CA certificate for mTLS client verification
seed_nodes []string — Existing cluster nodes to join on startup
join_token string — Pre-shared token required to join the cluster

Logging (log)

Field Type Default Description
level string "info" debug, info, warn, error
format string "text" text or json

Database (database)

Field Type Default Description
driver string — Database module driver name
url string — Database connection string

Cache (cache)

Field Type Default Description
driver string — Cache module driver name
url string — Cache connection string

Module Settings (modules)

Arbitrary key-value configuration passed to individual modules:

{
  "modules": {
    "downloader-qbittorrent": {
      "url": "http://localhost:8080",
      "username": "admin"
    }
  }
}

Environment Variables

All config fields can be overridden with environment variables. These take highest precedence.

Variable Overrides Example
MUXCORE_CONFIG Config file path /etc/muxcore/config.json
MUXCORE_TAG Tag to load from spool default
MUXCORE_SPOOL Spool URL https://github.com/Muxcore-Media/spool
MUXCORE_ADDR Server listen address :3000
MUXCORE_TLS_CERT HTTP TLS certificate path /etc/ssl/cert.pem
MUXCORE_TLS_KEY HTTP TLS private key path /etc/ssl/key.pem
MUXCORE_LOG_LEVEL Log level debug
MUXCORE_LOG_FORMAT Log format json
MUXCORE_DATABASE_DRIVER Database module driver postgres
MUXCORE_DATABASE_URL Database connection string postgres://...
MUXCORE_CACHE_DRIVER Cache module driver redis
MUXCORE_CACHE_URL Cache connection string redis://...
MUXCORE_GRPC_TLS_CERT gRPC TLS certificate /etc/ssl/grpc-cert.pem
MUXCORE_GRPC_TLS_KEY gRPC TLS private key /etc/ssl/grpc-key.pem
MUXCORE_GRPC_MTLS_ENABLED Enable mutual TLS true
MUXCORE_GRPC_MTLS_CA External CA certificate for mTLS client verification /etc/ssl/ca.pem
MUXCORE_GRPC_CA_CERT_DIR Internal CA directory for auto-generated certs ~/.muxcore/ca/
MUXCORE_GRPC_SEED_NODES Cluster seed nodes node1:9090,node2:9090
MUXCORE_CLUSTER_JOIN_TOKEN Cluster join token my-secret-token
MUXCORE_AUDIT_PATH Audit log file path (JSONL) /var/log/muxcore/audit.jsonl

How Tags Work

A tag is a JSON file in a spool repo. It lists which modules to load:

{
  "name": "default",
  "description": "The official MuxCore starter setup",
  "version": "1.0.0",
  "modules": [
    {
      "repo": "https://github.com/Muxcore-Media/admin-ui",
      "version": "v1.0.0",
      "required": true
    }
  ]
}
  • required: true — core refuses to start without this module
  • required: false — core starts without it but logs a warning

Modules run as separate processes (sidecars). They connect to core's gRPC mesh, register themselves, and communicate through the mesh. Core manages their lifecycle — spawning, health checks, shutdown.

Creating Your Own Tags

  1. Create a GitHub repo (your spool)
  2. Add a tags/ directory
  3. Add JSON files for your tags
  4. Point MuxCore at your spool: muxcored --tag my-tag --spool https://github.com/you/your-spool

Spool Security

The official MuxCore spool is at https://github.com/Muxcore-Media/spool. Modules from the official spool are maintained by the MuxCore team.

Third-party spools are untrusted by default. When you use --spool <url> with a non-official URL, you are trusting that spool's author to:

  • List legitimate module repos (not malicious forks)
  • Include security-critical modules (auth, rate limiting)
  • Specify current versions without known vulnerabilities
  • Not change the module list unexpectedly

Modules run as child processes with the same OS privileges as core. A malicious module can access your filesystem, network, and environment variables.

Before Using a Third-Party Spool

  1. Audit the spool's module list and versions
  2. Verify each module repo is what it claims to be
  3. Check that security modules are included and not replaced with stubs
  4. Pin to a specific commit or tag, not a floating branch
  5. Run in a sandboxed environment first

Verifying It Works

# Check the health endpoint
curl http://localhost:8080/health
# {"status":"ok","modules":{}}

The modules field shows module health statuses. With sidecar modules, health is reported via the gRPC mesh.

Next Steps

Wiki Navigation

Clone this wiki locally