The simplest way to run Mythweaver is on your own computer with Docker: you download one file and start it with one command. This page covers that install and the commands you'll use afterwards to run, upgrade and back it up. To run Mythweaver on a server for other people, see Installation.
What you need
- Docker with Docker Compose 2.23.1 or newer. On macOS and Windows, install Docker Desktop. On Linux, install Docker Engine with the Compose plugin. Run
docker compose versionto check your version. - About 1.5 GB of free disk space for the images, plus room for your uploads and the database.
- Port 4000 free on your computer. You can pick another port; see Settings.
To install
- Make an empty directory for Mythweaver and open a terminal in it. The directory's name becomes the name of the install, so keep it once you have chosen it.
- Download the compose file into it:
You can also copy the file from To run with Docker Compose and save it ascurl -LO https://github.com/mythweaver-app/mythweaver/releases/latest/download/compose.ymlcompose.yml. - Start Mythweaver:
The first start downloads the images, creates the database, generates the secrets and loads the built-in prompts. It can take a few minutes.docker compose up -d - Open http://localhost:4000. Mythweaver sends you to
/setup, where you create the owner account; see First run.
Important
Use http://localhost:4000 exactly. Mythweaver's live connection accepts only localhost. At http://127.0.0.1:4000 pages load but don't respond, and any other name redirects to HTTPS, which this install doesn't serve.
What runs
docker compose up -d starts five services. You only open the web address; the services talk to each other inside Docker.
| Service | What it does |
|---|---|
mythweaver |
The app itself. It updates the database when a new version starts. |
db |
The PostgreSQL database that holds accounts, characters, chats and settings. |
nginx |
The web server at http://localhost:4000. It passes pages to the app and images to xi. |
xi |
Resizes uploaded images, such as character portraits, for display. |
secrets |
Runs on every docker compose up, creates the secret keys if they don't exist yet, then stops. |
Your data lives in three Docker volumes:
| Volume | What it holds |
|---|---|
db |
The database. |
data |
Your uploads and, under secrets/, the keys Mythweaver generated. One of them encrypts the API keys of your AI connections. |
xi-cache |
Resized copies of images. Safe to lose; they are made again on demand. |
To start, stop and check on it
Run these in the directory that holds compose.yml.
| Command | What it does |
|---|---|
docker compose up -d |
Starts Mythweaver, or applies changes to compose.yml and .env. |
docker compose stop |
Stops it. Your data stays. |
docker compose ps -a |
Shows each service's state. secrets showing as exited is normal. |
docker compose logs mythweaver |
Shows the app's log. Add -f to follow it. |
Mythweaver starts again by itself after a restart of your computer or of Docker, unless you stopped it with docker compose stop.
To upgrade
- Download the latest compose file over the old one, with the same
curlcommand as in To install. Each release's compose file pins that release's version, so this step is what moves you to the new one. - Run:
The new version updates the database when it starts.docker compose pull && docker compose up -d - If the release notes say it brings new built-in content (prompts, memory, caption or expression presets), load it:
docker compose run --rm mythweaver /app/bin/seed
To back up
Warning
Back up both the db and data volumes. If you lose data, you lose your uploads and the key that encrypts stored AI API keys, and every saved API key must be entered again.
With Mythweaver running, this saves the database to mythweaver.sql:
docker compose exec db pg_dump -U postgres mythweaver > mythweaver.sql
This saves the data volume to data.tar.gz. Docker names the volume after your directory, so replace mythweaver in mythweaver_data if your directory has another name:
docker run --rm -v mythweaver_data:/data -v "$PWD":/backup alpine tar -czf /backup/data.tar.gz -C /data .
Settings
Optional settings go in a file named .env beside compose.yml, one NAME=value per line. Run docker compose up -d after changing it.
| Setting | Default | What it does |
|---|---|---|
MYTHWEAVER_PORT |
4000 |
The port Mythweaver is served on. With MYTHWEAVER_PORT=4100, open http://localhost:4100. |
MYTHWEAVER_BIND |
127.0.0.1 |
The address the port is published on. The default allows only this computer. |
POSTGRES_PASSWORD |
mythweaver |
The database password. Set it before the first start: the database keeps the password it was created with. |
For example:
MYTHWEAVER_PORT=4100
POSTGRES_PASSWORD=pick-a-long-random-password
Note
Changing MYTHWEAVER_BIND lets other devices reach the port, but they are redirected to HTTPS, which this install doesn't serve. To use Mythweaver from other devices, serve it over HTTPS; see HTTPS and client IPs.
To uninstall
docker compose downremoves the containers and keeps your data in the volumes.docker compose down -valso deletes the volumes, with every account, chat, upload and key. Back up first if you might want them again.
Troubleshooting
| Problem | What to do |
|---|---|
docker compose up -d says the port is already allocated |
Another program uses port 4000. Set MYTHWEAVER_PORT to a free port in .env. |
Compose reports an unknown content option under configs |
Your Docker Compose is older than 2.23.1. Update Docker Desktop or the Compose plugin. |
| The page doesn't load right after the first start | The app is still setting up the database. Wait a minute, or watch docker compose logs -f mythweaver until it reports that it is running. |
| Pages load but buttons and chats don't respond | Open the site at http://localhost: and your port, not 127.0.0.1 or a network name. |