Getting started

The fastest way to run Loma is Docker Compose. You’ll need:

  • A MongoDB connection string (Atlas or self-managed)
  • A Slack app in Socket Mode — see Slack app setup
  • An OpenCode API key for the default agent runtime — see Agent runtime

Quickstart (Docker Compose)

git clone https://github.com/plotlinelabs/loma.git
cd loma

cp .env.example .env                       # backend config
cp dashboard/.env.example dashboard/.env   # dashboard config
# edit both — see Configuration for the full reference

docker compose up --build

Then open http://localhost:3001, create the first admin (your email, a password, and your LOMA_SETUP_TOKEN), and send a message in chat.

Fresh EC2 / GCP install

Use this path to stand up a new self-hosted install on Ubuntu 24.04+ LTS. While testing, allow inbound TCP 22 and 3001 in the instance firewall. Only open 3000 if you need external webhooks or direct backend debugging — better still, put everything behind a reverse proxy (see Deployment & networking).

1. SSH in

ssh -i your-key.pem ubuntu@<server-ip>

2. Install Docker Engine + Compose plugin

sudo apt update
sudo apt install -y ca-certificates curl git
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo usermod -aG docker ubuntu

Log out and back in so the Docker group applies.

3. Clone and configure

git clone https://github.com/plotlinelabs/loma.git
cd loma
cp .env.example .env
nano .env

A minimal backend .env for a smoke test:

PUBLIC_BASE_URL=http://<server-ip>:3001
LOMA_SETUP_TOKEN=<random-first-admin-token>
SLACK_BOT_TOKEN=xoxb-...
SLACK_APP_TOKEN=xapp-...
OPENCODE_API_KEY=opencode-...
AGENT_DEFAULT_MODEL=opencode-go/deepseek-v4-flash
OBSERVABILITY_MONGODB_URI=mongodb+srv://user:pass@cluster.example.com/
OBSERVABILITY_DB_NAME=loma_observability
LOMA_SKILL_ASSET_DIR=/var/lib/loma/skill-assets
WEBHOOK_PORT=3000
ENV=PROD

Then the dashboard .env:

cd dashboard
cp .env.example .env
nano .env
cd ..
AUTH_SECRET=<random-long-secret>
AUTH_PROVIDER=local
NEXT_PUBLIC_AUTH_PROVIDER=local
LOMA_SETUP_TOKEN=<same-as-backend>
OBSERVABILITY_MONGODB_URI=mongodb+srv://user:pass@cluster.example.com/
OBSERVABILITY_DB_NAME=loma_observability
AUTH_URL=http://<server-ip>:3001
BACKEND_URL=http://loma-backend:3000
NEXT_PUBLIC_API_URL=

Generate secrets with openssl rand -base64 32. Use the same MongoDB database for backend and dashboard so the admin you create is visible to the API. See Configuration for the full env reference and Authentication for auth options.

4. Start

docker compose up --build

5. Smoke test

  • Open http://<server-ip>:3001 and create the first admin.
  • Send a message in dashboard chat.
  • Create a skill on the Skills page, then ask the agent to use it.
  • Invite the Slack bot to a channel and mention it; DM it.
  • Confirm conversation history appears in the dashboard.

Useful commands:

docker compose ps
docker compose logs -f loma-backend
docker compose logs -f loma-dashboard

If OpenCode fails, check the backend logs for a missing OPENCODE_API_KEY or OpenCode server did not become ready — most first-run issues are missing credentials or blocked network access.

Local development

Backend:

git clone https://github.com/plotlinelabs/loma.git
cd loma
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env   # edit
python app.py          # listens on WEBHOOK_PORT, default 3000

Dashboard:

cd dashboard
npm install
cp .env.example .env   # edit
npm run dev            # http://localhost:3001

The first local user created with LOMA_SETUP_TOKEN is provisioned as admin.