6.12 Run and debug from source

When changing Teloa source, run the application natively with PostgreSQL in local Docker. Template and SKILL authors can use an installed Teloa without preparing this environment.

Prerequisites

Use Git, Node.js 24, pnpm 11.7.0 and running local Docker. Node 22 requires at least 22.19; these examples consistently use Node 24.

git clone https://github.com/teloa-ai/teloa.git
cd teloa
node --version
pnpm --version
docker info
pnpm install --frozen-lockfile
pnpm setup:dsh

Run commands from the source root. The checked-out package.json, lockfile and fixed DSH baseline determine dependencies and scripts.

Start your development instance

In a fresh checkout without existing Teloa development data:

pnpm setup:database
pnpm dev:dsh

The database preparer checks ownership of the local teloa-postgres container and refuses a conflict. Do not delete an existing container, volume or configuration to pass the check.

The launcher builds, then prints an authenticated local URL. Open the complete URL, configure a test model in Settings and obtain a real response to a simple message. The default port is 3100. If it is occupied, preserve the original service and use the acceptance launcher below; changing a port alone does not isolate data.

Isolated acceptance with a prepared database

pnpm dev:dsh:acceptance

This reads the initialized local development database configuration, creates a separate schema in that database and automatically assigns a port, profile, runtime and workspace. It is not an interactive setup wizard and does not create a new PostgreSQL database. Complete the previous initialization first; missing configuration causes an error.

Local model keys are not copied by default. Configure a test model in the new instance's trusted settings. Stop the process you started through its normal lifecycle and inspect cleanup receipts; never terminate unrelated instances with a broad process match.

Change and investigate

Locate the package through architecture. Start validation with:

pnpm check:dsh
pnpm test:contract

Then run affected-package tests from testing and contributing. UI and plugin changes need a rebuild and restart of your own host; refreshing the browser does not load new server code.

Task files default to .runtime/teloa/workspace, not the source directory. Set TELOA_WORKSPACE_ROOT in the startup environment for another authorized directory; it does not move existing files.

Troubleshooting

Symptom	Check first
Missing or wrong pnpm	PATH and packageManager; avoid silently upgrading global dependencies
Database preparation fails	docker info, container ownership and existing configuration
Port conflict	Whether the original service is in use; use isolation
UI loads but model does not answer	Provider, credentials and selected model in that instance
Code change has no effect	Build completion and whether the correct host restarted

Check startup errors, then the current instance's Harness log and execution records. Remove tokens, cookies, keys, database connections and private content before sharing logs.