Skip to main content

Self-Hosted Studio with Docker

What you will learn

By the end of this guide, you will know what self-hosting gives you, the required setup, available installation paths, and how to troubleshoot common issues.

What’s Included​

Self-hosting gives you the Studio experience on your own machine or server, including:

  • Visual Canvas for building agents
  • Built-in authentication, Vault, and environment variable management
  • Debug, Inspect, and run history
Is this for you?

This setup is ideal if you can run Docker on your machine and want full control, privacy, and a simple install path.

System Requirements​

Before starting, make sure your environment meets these minimums:

  • Docker and Docker Compose v2
  • At least 4 CPU cores and 8 GB RAM recommended
  • A MySQL compatible database (local or managed)
Start simple

Start locally with Docker. You can add a reverse proxy and HTTPS later to share access securely.

Quickstart​

1. Clone the Repository​

git clone https://github.com/SmythOS/smythos-studio.git
cd smythos-studio

2. Create Your Environment File​

cp .env.compose.example .env

Open .env and set at minimum:

DATABASE_URL="mysql://user:pass@db:3306/smythos"
APP_BASE_URL="http://localhost"
SESSION_SECRET="long-random-string"
OPENAI_API_KEY="sk-your-key" # optional

3. Start the Stack​

docker compose up -d

Optional: Watch logs to see services start

docker compose logs -f

When services are healthy, open:

http://localhost

You should see the Studio page. Create your first agent and run a quick test.

aawa6

Source code

SmythOS Studio Community Edition is open source.
Browse the code on GitHub.

Troubleshooting​

Port already in use
Stop the conflicting service or change the published ports in Compose.

Cannot connect to database
Check DATABASE_URL. Ensure the DB is running and accessible.

Blank UI or 502 error
Review container logs for middleware or runtime errors. Fix .env or networking issues, then restart.

Login loop
Confirm APP_BASE_URL matches the actual URL and that proxies forward headers correctly.

Logs

Use docker compose logs -f to watch services start and catch errors early.

FAQ​

Can I run this on a laptop?
Yes. It's completly private to your device when you run it locally using Docker.

Do I need a public domain?
No. Local setups work without a domain. For shared access, add a reverse proxy and HTTPS.

Is Community the same as Cloud?
Community focuses on self-hosting. Some features differ from the cloud version.

Where can I get help?
Open an issue on GitHub or join the community discussions.

Next Steps​