Layi Docs

Self Hosting Guide

Deploy the data plane inside your network while Layi runs the orchestration layer

Last updated: December 2025

Own the data plane, keep the orchestration managed

Self hosting gives you full custody over databases, object storage, and observability artifacts while Layi keeps operating the Temporal control plane, Tool Gateway, and Org Manager. You decide where data lives; we keep the workflows durable, patched, and resilient.

You deploy
Cassandra, Redis, Elasticsearch, and MinIO clusters inside your VPC or on-prem footprint to store every run, vector, and attachment.
We operate
Temporal workflows, the Tool Gateway, and Org Manager identity stay under Layi’s watch so durability patches and reliability layers keep rolling.
Clear boundary
Only encrypted task state crosses the boundary. Secrets, user data, and audit trails stay within the systems you manage.

What you need first

Before running the wizard, confirm the following basics are ready:

  • Python 3.11+ for the setup wizard
  • Docker or Kubernetes access to host Cassandra, Redis, Elasticsearch, and MinIO
  • Git + Node.js 18+ for optional manual bootstrapping
  • TLS certificates for the data endpoints you expose to the control plane

Step 1: Clone and Enter

Get the code and navigate to the project directory:

git clone https://github.com/layi-ai.git  cd layi

Step 2: Run the Setup Wizard

Start the interactive setup wizard:

python setup.py

The wizard will ask you to choose between two setup methods:

Docker Compose (Recommended)
Automatically manages all services and dependencies. Just run and go.
Manual
Requires installing dependencies and running services manually.

Step 3: Provision your data plane

The wizard captures connection details for every service you host. It saves progress so you can pause for networking or security reviews.

You operate these systems

Cassandra (Primary datastore)

Stores agent runs, workflow checkpoints, and long-lived context. Deploy a multi-node ring inside your VPC or data center.

Provide the contact points, credentials, and keyspace names during the wizard.

Redis (Hot path cache)

Handles session state, rate limiting, and transient reasoning context. Cluster or sentinel setups are both supported.

Share the Redis URI(s) plus TLS requirements so the control plane can negotiate securely.

Elasticsearch (Search + telemetry)

Indexes transcripts, attachments, and run metrics for fast recall. You control retention and index lifecycle.

Make sure API keys map to dedicated indices per environment.

MinIO (Object storage)

Backs file uploads, audio, and large knowledge base artifacts. Deploy it wherever your compliance rules allow, with replication if needed.

The wizard accepts S3-compatible credentials and bucket policies.

Layi-managed services you connect to

Temporal + Tool Gateway

We supply the workflow endpoints, tool execution perimeter, and reliability monitors. You only share signed service accounts so workflows can persist into your data plane.

Org Manager

Identity, RBAC, billing, and audit events live in Org Manager. Generate API keys + webhook URLs there; the wizard stores them as sealed secrets.

LLM + Search providers

Bring your preferred model and search APIs. The wizard only needs the base URLs and API keys—no provider-specific logic is hardcoded.

Step 4: Register endpoints with the control plane

Once your clusters are reachable, the wizard validates connectivity and hands the connection info to the managed Temporal workers.

  • Upload TLS cert bundles for each service so mutual TLS can be enforced end-to-end.
  • Map keyspaces, indices, and buckets to environments (dev/staging/prod) and confirm retention policies.
  • Approve the Org Manager webhook + API key pairing so audit logs flow back into your systems of record.

Step 5: Start the Layi stack

If you chose Docker setup:

The wizard automatically starts everything for you! After setup completes:

# Check if everything is runningdocker compose ps# Follow the logs to see what's happeningdocker compose logs -f# Stop everything when you're donedocker compose down

If you chose manual setup:

You'll need to start each service in separate terminals:

Terminal 1 - Infrastructure:

docker compose up redis -d

Terminal 2 - Frontend:

cd frontend && npm run dev

Terminal 3 - Backend API:

cd backend && uv run api.py

Terminal 4 - Background Worker:

cd backend && uv run dramatiq run_agent_background

You're Done! 🎉

Once all services are running, open your browser and go to:

http://localhost:3000

You should see the Layi dashboard where you can confirm data-plane connectivity, assign storage policies, and start onboarding agents.

SDK Guide