---
title: Run and debug from source
description: Clone the source, prepare dependencies and start your own development workspace.
lastVerified: 2026-10-22
---

# 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.

```sh
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:

```sh
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

```sh
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](https://docs.teloa.ai/v/0.2.7/markdown/en/develop/architecture.md). Start validation with:

```sh
pnpm check:dsh
pnpm test:contract
```

Then run affected-package tests from [testing and contributing](https://docs.teloa.ai/v/0.2.7/markdown/en/develop/testing.md). 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.