Getting Started

Getting Started

Audience: Everyone Status: ✅ Ready

This is the on-ramp for a first-time operator: get a TelosMUD running on your own machine, load a content pack so there's a world to walk around in, and connect a client. The three child pages below take you through it in order; start with Running Locally.

Prerequisites

You can run the whole stack from Docker, so the only hard requirements are a container runtime and make. A Go toolchain is needed if you want to run the binaries directly or hack on the engine.

• Docker + Docker Compose — brings up the backing services (Postgres, Redis, NATS) and, optionally, the whole fleet. This is the path make up uses.
• make — the repository's Makefile wraps every common task (up, deps, seed, migrate, build).
• Go 1.25 toolchain — required only for the direct-binary path (make build, make seed, make migrate all shell out to go) and for engine development. Not needed if you run the pure-Docker stack.
• A telnet client — anything that speaks telnet (telnet, nc, or a MUD client such as Mudlet) to connect on the gate's port.

The backing services — Postgres (durable state), Redis (session routing / placement leases), and NATS/JetStream (cross-shard bus) — are all provisioned for you by Compose; you do not install them by hand. See Running Locally for the exact commands and what each Compose topology brings up.

Two ways to authenticate locally

TelosMUD is OAuth-only in production, but for local work you have a choice, and it's worth deciding up front:

• Dev bypass (fast). A compiled-in, opt-in bypass lets you log in by typing a character name — no identity provider, no browser round-trip. This is how the dev Compose stack and the automated tests connect. It is gated behind an explicit insecure opt-in and is never present in a release build.
• Real OAuth (realistic). Run telos-account and authenticate through GitHub in the browser — the gate prints a login URL you click to approve — exactly as a public server would. Use this when you want to exercise the real login path or test account/character behavior.

Both are covered in Running Locally; the dev bypass is the default for a first look.

The three guides

• Running Locally — what Compose brings up (single-box vs. multi-shard), the make targets, the config file, service ports, the migrate + seed bootstrap, and how to connect a client. Includes both authentication paths.
• First Admin Setup — bootstrap the first admin, promote further admins and builders, and onboard players.
• Content Packs Intro — the built-in demo world, the minimal core bootstrap pack, and how the active pack set is chosen.