Self Hosting | Lilypad
MirascopeLilypad

Self Hosting

Lilypad self hosting is currently in a closed beta.

The Free version is available for self hosting with community support. Pro and Team plan features are available for beta testing upon request.

Interested in participating in the closed beta? Join our community and send a message to William Bakst. If we determine it's a good fit, you'll get early access to Pro and Team plan features when self hosting.

Lilypad is fully open-source and can be self-hosted in your own infrastructure.

You can also run Lilypad on your local machine.

Requirements:

To self-host Lilypad, you'll need:

  1. Python 3.10+
  2. PostgreSQL
  3. A GitHub or Google account (for authentication)
  4. Docker

In the following sections we will be using http://localhost:8000 as the host/port URL.

Replace this with the URL where you are ultimately hosting Lilypad and making it accessible.

Setup

First, you'll need to clone the repository:

git clone [email protected]:Mirascope/lilypad.git
cd lilypad

Next, you'll need to install uv and the package's dependencies:

curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync --all-extras

Last, create a .env file where you'll store all of the upcoming environment variables.

Authentication

First, you'll need to generate and set a JWT secret (e.g. using https://jwtsecret.com/generate).

Then set it in your environment:

LILYPAD_JWT_SECRET=...

Next, you'll need to set up OAuth 2.0 Authentication. You can choose between GitHub or Google:

  • Homepage URL: http://localhost:8000
  • Authorization Callback URL: http://localhost:8000/auth/callback

GitHub

To authenticate with GitHub, create a new OAuth app on GitHub and set the following environment variables:

LILYPAD_GITHUB_CLIENT_ID=...
LILYPAD_GITHUB_CLIENT_SECRET=...

Google

To authenticate with Google, create a new OAuth app on Google and set the following environment variables:

LILYPAD_GOOGLE_CLIENT_ID=...
LILYPAD_GOOGLE_CLIENT_SECRET=...

Client

First, set your environment variables:

LILYPAD_API_SERVE_FRONTEND=true

You can optionally set LILYPAD_CLIENT_BASE_URL to the URL where you're hosting the client separately. In this case, you would set LILYPAD_API_SERVE_FRONTEND=false.

Now, build the client:

cd client
touch .env
echo "VITE_REMOTE_API_URL=http://localhost:8000/v0" > .env
pnpm i
pnpm run build
cd ..

Server

Set the remote API and client URLs so the server knows where to route everything:

LILYPAD_REMOTE_API_URL=http://localhost:8000/v0
LILYPAD_REMOTE_CLIENT_URL=http://localhost:8000

Whether you're running this locally or hosted in the cloud, you'll need to build the image:

DOCKER_BUILDKIT=1 docker build -t lilypad .

Local

You can use Docker Compose to run everything together locally:

docker-compose up

You must update docker-compose.yml to match your .env setup.

You should now be able to access your Lilypad instance at http://localhost:8000.

Note that this results in a PostgreSQL database running in a container. Should you spin down the container, you'll lose all data.

Hosted

You'll need to set up a PostgreSQL database and set the following environment variables:

LILYPAD_DB_HOST=...
LILYPAD_DB_NAME=...
LILYPAD_DB_PASSWORD=...
LILYPAD_DB_PORT=...
LILYPAD_DB_USER=...

Now you can run the server:

docker run -p 8000:8000 --env-file .env lilypad

You should now be able to access your Lilypad instance at http://localhost:8000.

Application

In your LLM code that uses Lilypad, you'll need to set the API and client URLs so that your code points to your self-hosted instance:

LILYPAD_BASE_URL=http://localhost:8000/v0
LILYPAD_REMOTE_CLIENT_URL=http://localhost:8000

Now you can use Lilypad as documented.

Make sure to install the correct package version.

The production-stable latest release of the SDK on PyPI may not be the same version as the one you're self-hosting. Make sure to install the version that matches your self-hosted instance.