Hosting

Freesona runs wherever Python runs. You can spin it up on your own machine in minutes with the included setup scripts, containerize it with the provided Dockerfile, or push it to a managed platform like Railway or Render. Pick the approach that matches your infrastructure. The bot behaves identically across all of them.

Local
Docker
Railway
Render

Use the included setup scripts for a guided local setup. The scripts handle everything from .env creation to launching the bot.Linux / macOS

bash scripts/setup_local.sh

Windows

scripts\setup_local.cmd

What the scripts do:

Create .env from .env.sample on first run. Open it and fill in your real Discord IDs and provider keys before continuing.
Validate BOT_TOKEN, CHANNEL_ID, AI_PROVIDER, and the matching provider API key (for example, GOOGLE_API_KEY for Gemini, OPENAI_API_KEY for OpenAI).
Create a .venv virtual environment and install dependencies from requirements.txt.
Run scripts/check_project.py to verify syntax and config.
Launch the bot with python main.py.

If you already have a configured .env and just want to start the bot manually, run:

python main.py

The local setup scripts are for manual hosting only. Do not use them for Docker or cloud platforms. On Docker, Railway, and Render, the platform owns the bootstrap process.

A Dockerfile is included. It uses the official python:3.13-slim image and installs ffmpeg and Node.js alongside the Python dependencies, so ~download, ~audio, and ~separate work out of the box.Build and run:

docker build -t freesona .
docker run -d --env-file .env --name freesona freesona

Mount a volume for persistence:Without a volume, config.json, memory.db, warnings.db, and other storage files are lost when the container is replaced. Mount a local directory at /data to persist them:

docker run -d \
  --env-file .env \
  -v $(pwd)/data:/data \
  --name freesona freesona

Then point the file-path variables in your .env at /data/:

CONFIG_FILE_PATH=/data/config.json
MEMORY_FILE_PATH=/data/memory.db
WARNINGS_FILE_PATH=/data/warnings.db
CHARACTER_MEMORY_FILE_PATH=/data/character_memory.db
ANNIVERSARIES_FILE_PATH=/data/anniversaries.db
CANON_FILE_PATH=/data/canon.db
AI_PERSONA_FILE=/data/persona.txt
AI_PERSONA_JSON_FILE=/data/persona.json
AI_PERSONAS_FILE=/data/personas.json
LOG_FILE_PATH=/data/logs/freesona.log

The container exposes port 10000 for the built-in health check and MVSEP webhook endpoints. Override the port with HTTP_PORT in .env if needed.

Railway detects the included Dockerfile automatically. Fork the repo, connect it to a Railway project, and follow these steps:

Fork the repo and connect it to Railway

Fork soquincy/Freesona on GitHub. Then create a new Railway project and select Deploy from GitHub repo, pointing it at your fork.

Add environment variables

Open the Variables panel and add all required .env values — at minimum BOT_TOKEN, CHANNEL_ID, AI_PROVIDER, and the matching provider API key.

Mount a volume at /data

In the Railway service settings, add a Volume and mount it at /data. This keeps your config and database files alive across deploys.

Set file path variables to /data/

Add these to the Variables panel so Freesona writes its state files to the mounted volume:

CONFIG_FILE_PATH=/data/config.json
MEMORY_FILE_PATH=/data/memory.db
WARNINGS_FILE_PATH=/data/warnings.db
CHARACTER_MEMORY_FILE_PATH=/data/character_memory.db
ANNIVERSARIES_FILE_PATH=/data/anniversaries.db
CANON_FILE_PATH=/data/canon.db
AI_PERSONA_FILE=/data/persona.txt
AI_PERSONA_JSON_FILE=/data/persona.json
AI_PERSONAS_FILE=/data/personas.json
LOG_FILE_PATH=/data/logs/freesona.log

Deploy

Trigger a deploy. Railway builds the Dockerfile and starts the bot. Check the deployment logs to confirm the bot connects to Discord.

Without a persistent volume, config.json, memory.db, and warnings.db are lost on every redeploy. Your prefix, enabled modules, autonomy settings, conversation channel, warning history, and all long-term user memory will be wiped.

Render can run Freesona as a Web Service using the included Dockerfile. Use a Render Disk for persistent storage.

Fork the repo and create a Web Service

Fork soquincy/Freesona on GitHub. Then create a new Web Service on Render and connect it to your fork. Render will detect the Dockerfile automatically.

Set environment variables

Open the Environment page for the service and add all required variables — BOT_TOKEN, CHANNEL_ID, AI_PROVIDER, and your provider API key.

Create a Disk mounted at /data

In the service settings, add a Disk and set the mount path to /data. This persists your storage files across deploys and restarts.

Set file path variables to /data/ paths

Add the following to the Environment page:

CONFIG_FILE_PATH=/data/config.json
MEMORY_FILE_PATH=/data/memory.db
WARNINGS_FILE_PATH=/data/warnings.db
CHARACTER_MEMORY_FILE_PATH=/data/character_memory.db
ANNIVERSARIES_FILE_PATH=/data/anniversaries.db
CANON_FILE_PATH=/data/canon.db
AI_PERSONA_FILE=/data/persona.txt
AI_PERSONA_JSON_FILE=/data/persona.json
AI_PERSONAS_FILE=/data/personas.json
LOG_FILE_PATH=/data/logs/freesona.log

Deploy

Trigger a deploy. Confirm the bot comes online by checking the Render service logs.

Persistence

Freesona uses a small set of files to store all runtime state. Keep these files on a persistent volume in any cloud environment:

File	Contents
`config.json`	Prefix, channel IDs, autonomy settings, module enabled/disabled states
`persona.txt`	Legacy persona (fallback)
`persona.json`	Active persona fields (core, background, beliefs, style, instructions)
`personas.json`	Saved persona presets
`memory.db`	Long-term user facts, keyed by `guild_id + user_id`
`warnings.db`	Moderation warnings with per-guild hex IDs and timestamps
`character_memory.db`	Character Memory — promises, shared experiences, relationship arc
`anniversaries.db`	User-claimed anniversary entries
`canon.db`	Canon facts for characters
`.chroma/`	ChromaDB vector store for knowledge base retrieval (optional)
`logs/freesona.log`	Bot logs with monthly rotation

On a local setup these files live in the project folder. On Docker, Railway, or Render, point all *_FILE_PATH environment variables at your /data/ mount to ensure they survive restarts and redeployments.

Get Started

Features

Guides

Reference

Changelog

Persistence

​Persistence

Persistence