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

Current version: 0.2.2. Choose npm, GitHub Releases or Docker Hub.

• 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 downloadable versioned configuration below. The published image has been verified on Linux ARM64; amd64 has not been verified.
• Run from source: for development and modifications, follow Local development. 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

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

npm install --prefix ./teloa-command --ignore-scripts https://github.com/teloa-ai/teloa/releases/download/v0.2.2/teloa-cli-0.2.2.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. For the same release from npm, use npm install --ignore-scripts @teloa/cli@0.2.2.

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 and create a project.

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.2. 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.2 command package into a new command directory, then use it to stop and upgrade the installation. Pass the original --home for a custom installation:

npm install --prefix ./teloa-command-022 --ignore-scripts https://github.com/teloa-ai/teloa/releases/download/v0.2.2/teloa-cli-0.2.2.tgz
./teloa-command-022/node_modules/.bin/teloa stop
./teloa-command-022/node_modules/.bin/teloa upgrade --to 0.2.2
./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

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 afterward. A ready Web service does not prove that terminal tasks or the model work. See Troubleshooting for more cases.

3. Stop and resume an npm installation

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

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 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 or Docker Engine with Docker Compose.
• Use a Linux ARM64 environment. The image and configuration below use teloa/teloa:0.2.2; 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. It keeps the existing password initialization, dedicated database and persistent volumes; no source build is needed.

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:

mkdir teloa-free
cd teloa-free
curl --fail --location https://docs.teloa.ai/downloads/0.2.2/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

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

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 to verify a response. A working page and a working model are two separate checks.

0.2.0-beta.3 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 or build your first team. The initial environment may be empty; you do not need to import demo data first.

Stop and resume

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 before upgrading. To change the source, see Local development.