---
title: Install and run Teloa
description: Install the stable Teloa 0.2.10 Community edition, with upgrade, execution and permission guidance.
lastVerified: 2026-10-24
---

# 1.4 Install and run Teloa


Teloa can run directly on your computer or inside containers. Both options use the existing Web interface in your browser. The difference is where tools execute and which files and programs they can access.

## Choose how to run Teloa

These instructions cover the **stable 0.2.10 release**, available through [GitHub Releases](https://github.com/teloa-ai/teloa/releases/tag/v0.2.10), [npm](https://www.npmjs.com/package/@teloa/cli/v/0.2.10) and [Docker Hub](https://hub.docker.com/r/teloa/teloa). Preserve the original installation identity and data when upgrading.

- **Native npm installation:** install without a source checkout or compilation. Teloa and DSH run in local Node.js, with Docker PostgreSQL by default. Follow the steps below.
- **Docker Hub with Compose:** run the application, agent engine and database in containers, using the versioned configuration below. The target platform is Linux ARM64; amd64 has not been verified. Final image support follows the release evidence.
- **Run from source:** for development and modifications, follow [Local development](https://docs.teloa.ai/v/0.2.10/markdown/en/develop/local-development.md). Building with `docker compose up -d --build` remains available from the source root.

Run natively when you need to call programs installed on your computer. A shell inside a container runs container programs. Mounting a folder provides file access, not control of native applications. A remote server also has no automatic access to files on your personal computer.

## Native installation from GitHub Releases

The npm installer provides installation and lifecycle commands for the existing open-source Web edition. You continue working in your browser. Teloa and the agent engine run natively, with PostgreSQL managed by Docker by default or an existing dedicated local `teloa` database. Arbitrary remote databases are not supported.

Minimum support is **Node.js 22.19 or later in the 22.x line, or 24.x**, with **npm 11.x from 11.12.1 onward**. Upgrade the npm 10 bundled with Node.js 22 before installing. The verified 0.2.10 security baseline is **Node.js 24.22.1** (or 22.23.4 or later in the 22.x line); upgrade older 22.x installations first.

Every option requires you to configure a model. Remote services require their corresponding API keys. Native installation retains tool permissions, working-directory restrictions and approvals; desktop or browser actions require separate tool integrations. Platform support follows actual acceptance evidence.

### 1. Install and start

Install the exact release into a separate command directory and choose an available port. The commands below install the release for `0.2.10`. Initialize with `up`, then check the running installation:

```sh
npm install --prefix ./teloa-command --ignore-scripts https://github.com/teloa-ai/teloa/releases/download/v0.2.10/teloa-cli-0.2.10.tgz
./teloa-command/node_modules/.bin/teloa up --port 3101
./teloa-command/node_modules/.bin/teloa doctor
./teloa-command/node_modules/.bin/teloa status
```

Check the download against `SHA256SUMS` on the [release page](https://github.com/teloa-ai/teloa/releases/tag/v0.2.10). For npm, use `npm install --ignore-scripts @teloa/cli@0.2.10`.

Below, `teloa` means `node_modules/.bin/teloa` in that command directory. The default installation home is `~/.teloa`; a new installation accepts `--home`, `--port` and `--workspace`. Use `teloa open` if the browser does not open automatically. Then [configure your model](https://docs.teloa.ai/v/0.2.10/markdown/en/start/models.md) and [create a project](https://docs.teloa.ai/v/0.2.10/markdown/en/guides/projects.md).

To use existing PostgreSQL, only a dedicated database named `teloa` on `localhost` or `127.0.0.1` is accepted. It must be empty for a new installation and must not belong to another installation. Pass a mode-`0600` JSON file containing `connectionString` through `--database-config`; keep credentials out of command lines and public logs.

Updating the npm command package does not replace a running application. For an existing 0.2.6/0.2.7 or Alpha/Beta installation, keep its original `--home`, use the 0.2.10 command package below to stop it, then run `teloa upgrade --to 0.2.10`. The upgrade creates a backup and checks candidate readiness. Do not overwrite program directories or reinitialize the original database. The 0.2.7 to 0.2.10 path has been verified to preserve tasks and identity.

To upgrade an existing installation, such as the previous stable release or `0.2.0-alpha.7`, to 0.2.10, install the `0.2.10` command package into a new command directory, then use it to stop and upgrade the installation. Pass the original `--home` for a custom installation:

```sh
npm install --prefix ./teloa-command-028 --ignore-scripts https://github.com/teloa-ai/teloa/releases/download/v0.2.10/teloa-cli-0.2.10.tgz
./teloa-command-028/node_modules/.bin/teloa stop
./teloa-command-028/node_modules/.bin/teloa upgrade --to 0.2.10
./teloa-command-028/node_modules/.bin/teloa status
```

When `--to` matches the version of the running command package, the upgrade uses that package as its candidate; other versions still come from the npm registry. The upgrade keeps the installation identity, port, working directory and data, and creates a backup before switching. Running `up` from the new package alone does not replace the installation; it starts the existing version and prints the upgrade command.

### 2. Environment checks

```sh
teloa doctor
teloa doctor --json
```

Before initialization, this checks Node, the npm command on PATH, and the actual terminal sandbox without creating the installation directory or starting a database. Any failed check produces exit code `1`. Text output includes advice; JSON marks that check as `ok: false` and includes a `remedy`. For an existing installation, it also checks the dependencies it needs to run, directories, the database, and the service.

A restricted Linux terminal needs working bubblewrap or a kernel that supports Landlock. Some Docker or emulated environments lack these capabilities. Fix the environment and rerun the check; do not disable the sandbox. You still need to [configure and test your model](https://docs.teloa.ai/v/0.2.10/markdown/en/start/models.md) afterward. A ready Web service does not prove that terminal tasks or the model work. See [Troubleshooting](https://docs.teloa.ai/v/0.2.10/markdown/en/deploy/troubleshooting.md) for more cases.

### 3. Stop and resume an npm installation

Use the CLI in the same command directory. Stopping preserves your installation data:

```sh
teloa status
teloa stop
teloa up
```

Finish active work before stopping. For a custom installation home, keep using its original `--home`. See [backup and upgrades](https://docs.teloa.ai/v/0.2.10/markdown/en/deploy/backup.md) before changing versions.

## Run with Docker Compose

These steps run Teloa and PostgreSQL in containers, with data stored in persistent volumes. You do not need Node.js, pnpm, or OrbStack on your computer.

### Before you begin

- Install and start [Docker Desktop](https://docs.docker.com/desktop/) or [Docker Engine](https://docs.docker.com/engine/install/) with Docker Compose.
- Use a Linux ARM64 environment. The image and configuration below use `teloa/teloa:0.2.10`; amd64 is not verified.
- Make sure the device can download images and software dependencies. Configure your own model and provide API keys for remote services.

Create a new directory and download the [versioned Compose configuration](https://docs.teloa.ai/v/0.2.10/downloads/0.2.10/compose.yaml). It keeps the existing password initialization, dedicated database and persistent volumes; no source build is needed.

```sh
docker info
docker compose version
```

The first command should return details of the running engine; the second should show the Compose version. Use a maintained Docker release that supports health checks and dependency conditions for initialization services.

### Start Teloa

In a new directory, run:

```sh
mkdir teloa-free
cd teloa-free
curl --fail --location https://docs.teloa.ai/downloads/0.2.10/compose.yaml --output compose.yaml
docker compose pull
docker compose up -d --no-build
```

On the first start, Docker uses the published image, generates a database password, initializes the database and starts Teloa. The password is stored in a separate volume; you do not need to enter a demo password.

### Check the status

```sh
docker compose ps
```

Wait until `db` and `app` are healthy. `init` is a one-time initialization service, so a successful exit is expected. If a service keeps restarting, [check the error](https://docs.teloa.ai/v/0.2.10/markdown/en/deploy/troubleshooting.md) first. Do not delete the data volumes.

The default local Web port is `3100`. The database port is not opened outside the containers. If another service already uses that port, add `TELOA_PORT=3101` to `.env` in this directory, then start Teloa. Do not stop unrelated services.

### Open the authentication link

```sh
docker compose logs --tail=50 app
```

In your own terminal, find the full authentication link printed during this startup. If you changed the port, replace the port in the link with the port you configured, preserving all authentication parameters.

Use the new link after a restart. The authentication link is not a model API key. Do not paste logs containing authentication parameters into public issues.

### Start working

On your first visit, Teloa may prompt you to add an API key. Configure it there, or choose to set it up later and open **Settings > Models**. Follow the [model guide](https://docs.teloa.ai/v/0.2.10/markdown/en/start/models.md) to verify a response. A working page and a working model are two separate checks.

[![The model selector before a chat model is configured. Save your own model credentials in Settings first.](https://docs.teloa.ai/v/0.2.10/assets/screenshots/en/model-key-024.5d7394d174ce.png)](https://docs.teloa.ai/v/0.2.10/assets/screenshots/en/model-key-024.5d7394d174ce.png)

*0.2.4 actual interface with example data. The model selector before a chat model is configured. Save your own model credentials in Settings first.*

Next, [complete your first task](https://docs.teloa.ai/v/0.2.10/markdown/en/start/first-task.md) or [build your first team](https://docs.teloa.ai/v/0.2.10/markdown/en/start/first-team.md). The initial environment may be empty; you do not need to import demo data first.

### Stop and resume

```sh
docker compose stop
docker compose start
```

Your data stays in the persistent volumes. Local tasks and automations cannot continue while your computer is asleep or shut down, or while Docker is closed. [Back up](https://docs.teloa.ai/v/0.2.10/markdown/en/deploy/backup.md) before upgrading. To change the source, see [Local development](https://docs.teloa.ai/v/0.2.10/markdown/en/develop/local-development.md).