6.7 Run and debug from source

For daily development, use native Teloa and Harness processes with Docker PostgreSQL. This lets you test local files, programs, PATH, and tool permissions directly, using the same execution model as the planned npm installer. Users who need native execution today can also run from source using this page. Compare the options in the installation guide.

Full-container Compose is useful for isolated integration tests and deployment regression checks. Native programs and operating-system permissions still require a native test environment; see Testing environments.

Prerequisites and startup

You need a source checkout, Node ^22.19.0 || >=24.0.0, pnpm 11.7.0, and a reachable local Docker installation.

pnpm install
pnpm setup:database
pnpm setup:dsh
pnpm dev:dsh

The launcher builds the application first, then prints the current authentication URL. Open the complete URL. Do not commit its token or include it in an issue report.

These commands run the application on your computer and only the database in Docker. The current setup:database workflow requires a working local Docker engine. The npm installer's option to use an existing local database is still planned.

Local working directory and tools

The default working directory is .runtime/teloa/workspace. Set TELOA_WORKSPACE_ROOT to select your own directory explicitly. It cannot be the Teloa program directory, one of its parents, or a location inside the program directory outside its runtime directory. Changing the working directory does not move existing files.

The Harness invokes authorized tools from the working directory. Available programs depend on tool integrations, the startup environment's PATH, and operating-system permissions. A native runtime does not grant access to the entire computer. Restart the service and verify a real call after changing PATH. Browser, desktop, and office application actions need the corresponding tools; successful installation does not prove those capabilities are available.

Validate your changes

pnpm check:dsh
pnpm test:contract
pnpm test:bindings

Run additional backend, Harness, or browser tests for the areas you changed. Plugin configuration and UI changes usually require a rebuild and host restart; refreshing the browser is not enough to load new code.

Run in isolation

Use the repository's pnpm dev:dsh:acceptance launcher and follow its instructions to create a separate profile, port, working directory, and database scope. Changing only the port does not isolate your everyday work data.

Port 3100 is the default everyday host. When ending an acceptance run, stop only the processes you started. Do not terminate processes in bulk using a broad keyword match.

Find diagnostic logs

Check startup command errors first, then .runtime/teloa/harness.log and the relevant execution records. Remove tokens, cookies, keys, database connection details, and private content before sharing. Record build output, model errors, and business state errors separately.