Installation

Choose an installation method based on your needs:

Method	When to use
Docker	Runs in an isolated container, separated from your host system.
Bare Metal	The AI works directly on your machine — your real files, tools, and environment.
Docker Compose	You already run HridaAI with Docker Compose and want to add Hrida Terminal to it.

Select your method below, then follow the steps.

Docker

Requires Docker.

1. Start the container

docker run -d \
  --name hrida-terminal \
  --restart unless-stopped \
  -p 8000:8000 \
  -v hrida-terminal:/home/user \
  -e HRIDA_TERMINAL_API_KEY=your-secret-key \
  ghcr.io/hrida-ai/hrida-terminal

Replace your-secret-key with a password of your choice.

Command breakdown

Flag	Purpose
-d	Run in background
--name hrida-terminal	Container name for reference
--restart unless-stopped	Auto-restart on reboot
-p 8000:8000	Expose on http://localhost:8000
-v hrida-terminal:/home/user	Persist files across restarts
-e HRIDA_TERMINAL_API_KEY=...	Authentication key

2. Verify

Open http://localhost:8000/docs in your browser. You should see the Hrida Terminal API page.

Auto-generated API key

If no API key was set, one is generated automatically. Find it with:

docker logs hrida-terminal

Bare Metal

warning

In this mode, the AI can do anything your user account can do, including modifying and deleting files.

1. Run Hrida Terminal

Option A — Run without installing:

uvx hrida-terminal run --host 0.0.0.0 --port 8000 --api-key your-secret-key

Downloads and runs via uv with no permanent installation.

Option B — Install with pip:

pip install hrida-terminal
hrida-terminal run --host 0.0.0.0 --port 8000 --api-key your-secret-key

2. Working directory

Hrida Terminal serves files from the current directory. To scope it to a specific project:

cd /path/to/your/project
uvx hrida-terminal run --host 0.0.0.0 --port 8000 --api-key your-secret-key

Windows

Supported via pywinpty. Full PowerShell support with colored output and interactive programs.

Docker Compose

Add Hrida Terminal as a service in your existing docker-compose.yml:

1. Update your Compose file

services:
  hrida-ai:
    image: ghcr.io/hrida-ai/hrida-ai-studio:latest
    container_name: hrida-ai
    ports:
      - "3000:8080"
    volumes:
      - hrida-ai:/app/backend/data

  hrida-terminal:
    image: ghcr.io/hrida-ai/hrida-terminal
    container_name: hrida-terminal
    volumes:
      - hrida-terminal:/home/user
    environment:
      - HRIDA_TERMINAL_API_KEY=your-secret-key

volumes:
  hrida-ai:
  hrida-terminal:

2. Start the services

docker compose up -d

Connection URL

When both services share a Docker Compose network, use the service name as the host:

http://hrida-terminal:8000

localhost won't resolve between containers.

---

Next step

Connect to HridaAI →