---
title: Install and run Teloa
description: Prepare for the Teloa 0.2.4 Community edition candidate, with installation, upgrade, execution, and permission guidance for its release.
lastVerified: 2026-10-21
---

# 1.2 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 **0.2.4 candidate, not yet released**. The channel commands below are for use after publication. For the currently released version, use the [0.2.3 installation guide](https://docs.teloa.ai/v/0.2.3/en/start/quickstart).

- **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.4/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.

Use Node.js 24.x or 22.x from 22.19 onward, and npm 11.x from 11.12.1 onward. Upgrade the npm 10 bundled with Node.js 22 before installing.

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

After publication, install the exact release into a separate command directory and choose an available port. The commands below are the target installation steps for `0.2.4`. 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.4/teloa-cli-0.2.4.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.4). For the same release from npm, use `npm install --ignore-scripts @teloa/cli@0.2.4`.

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.4/markdown/en/start/models.md) and [create a project](https://docs.teloa.ai/v/0.2.4/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 Alpha or Beta installation, keep its original `--home`, use the stable command package below to stop and back it up, then run `teloa upgrade --to 0.2.4`. The upgrade creates a backup and checks candidate readiness. Do not overwrite program directories or reinitialize the original database.

To upgrade an existing installation, such as `0.2.0-alpha.7`, to the stable release, install the `0.2.4` 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-024 --ignore-scripts https://github.com/teloa-ai/teloa/releases/download/v0.2.4/teloa-cli-0.2.4.tgz
./teloa-command-022/node_modules/.bin/teloa stop
./teloa-command-024/node_modules/.bin/teloa upgrade --to 0.2.4
./teloa-command-022/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.4/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.4/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.4/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.4`; 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.4/downloads/0.2.4/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.4/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.4/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.4/markdown/en/start/models.md) to verify a response. A working page and a working model are two separate checks.

[![Workspace model selector showing No models available before any model is configured](https://docs.teloa.ai/v/0.2.4/assets/screenshots/en/model-key-022.fda2951c54b9.png)](https://docs.teloa.ai/v/0.2.4/assets/screenshots/en/model-key-022.fda2951c54b9.png)

*0.2.2 interface before a key is entered. When the model selector shows No models available, add your model provider's API key in Settings > Models. This is not the local authentication link from the previous step.*

Next, [complete your first task](https://docs.teloa.ai/v/0.2.4/markdown/en/start/first-task.md) or [build your first team](https://docs.teloa.ai/v/0.2.4/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.4/markdown/en/deploy/backup.md) before upgrading. To change the source, see [Local development](https://docs.teloa.ai/v/0.2.4/markdown/en/develop/local-development.md).