Mycel — The root engine

Self-hosting guide

• Who is self-hosting for?
• Installation
• Maintenance
• Enable HTTPS (to use with WebApps)

Who is self-hosting for?

Self-hosting means running Mycel on your own machine or server. Your data stays entirely local, in a SQLite file on your device. If you'd rather not manage a server, MycelCloud is a hosted alternative.

Self-hosting is a good fit if you want full control over your data, prefer not to depend on an external service, or simply want to run Mycel for free.

Keep in mind that availability depends on how you host Mycel. If you run it on your personal computer, Mycel will only be accessible while that computer is on and from the same network. If you use a remote server (a VPS or dedicated machine), you can make it available from anywhere, but that configuration is outside the scope of this guide.

As a self-hoster, you manage your own updates and backups.

Installation

Which installation method do you want to use? (Git is probably the simplest)

Requirements

Make sure Python v3.10+ and git are installed on your system.

Install

Clone the repository:

git clone https://github.com/mycel-project/mycel

Then run the setup script for your OS:

Windows Linux / macOS

setup.bat

Note: some dependencies may take a while to install depending on your device's architecture.

Run

run.bat

Mycel will display its URL at startup. You'll need it to connect your client.

How to Update

To update Mycel, run this command from your Mycel folder:

git pull

Then restart Mycel.

If an update introduces new configuration options, you may need to update your config.json by referring to config.example.json. See also how Mycel handles versions.

Following a specific version

By default git pull updates to the latest stable release. If you want to pin Mycel to a specific version, for instance to avoid a breaking change, you can checkout a tag:

git checkout tags/vX.X.X

Prerelease tags follow the format vX.X.X-alpha, vX.X.X-beta, or vX.X.X-rc, optionally suffixed with a number: vX.X.X-alpha.2.

Note that pinning a tag means you won't receive further updates until you switch back.

To follow the latest prerelease instead:

git checkout dev

Prerelease versions move fast and may be less stable. Not recommended unless you know what you're doing.

Troubleshooting

• Check that Mycel is running. When entering Mycel's URL in your browser, you should see a welcome message. If not, Mycel may not be running or the port may not be exposed.
• Check that Mycel is reachable from your client. Make sure both are on the same network, or that your server is accessible from the internet if needed.
• Check your firewall. The port Mycel runs on may be blocked by your firewall or router.
• Check your Python version. Run python --version or python3 --version and make sure it is 3.10 or above. If using Docker, check the Python version inside the container instead.
• Check the terminal output. If Mycel crashes at startup, the error message in the terminal is usually the best starting point.

Still stuck? Open an issue or reach out to us.

Maintenance

Your data

All your learning data is stored in mycel.db at the root of your Mycel folder.

Back up this file regularly. If it is lost or corrupted, your data cannot be recovered.

Versionning

Mycel uses semantic versioning (MAJOR.minor.patch). In short: patch updates are safe, minor updates are generally safe, major updates may require migration. See more in docs.

What to expect when updating

Updating within the same major version is generally safe. Your data and configuration won't be silently affected. If a behavioral change is introduced, the old behavior is kept as default and the new one is opt-in, so updating Mycel without updating your client will never break things unexpectedly.

Across major versions, migration tooling and documentation are provided to help transition your data and configuration.

Enable HTTPS (to use with WebApps)

Some platforms refuse to call APIs served over HTTP when the page itself is loaded over HTTPS — this is known as mixed content, and most browsers block it by default. To work around this, you'll need to expose Mycel over an HTTPS address.

The quickest way to do this without creating an account is Cloudflare's Quick Tunnels. Make sure cloudflared is installed and your Mycel instance is running, then run:

cloudflared tunnel --url http://localhost:YOUR_MYCEL_INSTANCE_PORT

This prints a random HTTPS address on trycloudflare.com. Provide that address to your client to use Mycel over HTTPS.