Skip to main content

Terminals (Orchestrator)

Terminals is an enterprise orchestration layer for Hrida Terminal that provisions a fully isolated terminal container for every user. Instead of sharing a single container, each person gets their own, complete with separate files, processes, resource limits, and network isolation.

Quick navigation

How it works​

The orchestrator sits between HridaAI and the Hrida Terminal instances:

  1. A user activates a terminal in HridaAI.
  2. HridaAI proxies the request to the orchestrator, a service that manages the lifecycle of terminal containers.
  3. The orchestrator provisions a personal Hrida Terminal container for that user (or reconnects to an existing one).
  4. All traffic is proxied through the orchestrator. The user never connects to their container directly.
  5. Idle containers are automatically cleaned up after a configurable timeout. Data optionally persists across sessions.

The orchestrator also exposes the same OpenAPI-based tool interface as Hrida Terminal, so the AI can execute commands, read files, and run code, all scoped to the requesting user's container.

Deployment​

Prerequisites​

Quick start with Docker Compose​

This Compose file deploys HridaAI and the Terminals orchestrator together.

services:
  hrida-ai:
    image: ghcr.io/hrida-ai/hrida-ai-studio:main
    ports:
      - "3000:8080"
    environment:
      - >-
        TERMINAL_SERVER_CONNECTIONS=[{
          "id": "terminals",
          "name": "Terminals",
          "enabled": true,
          "url": "http://terminals:3000",
          "key": "${TERMINALS_API_KEY}",
          "auth_type": "bearer",
          "config": {
            "access_grants": [{
              "principal_type": "user",
              "principal_id": "*",
              "permission": "read"
            }]
          }
        }]
    volumes:
      - hrida-ai:/app/backend/data
    networks:
      - hridaai
    depends_on:
      - terminals

  terminals:
    image: ghcr.io/hrida-ai/terminals:latest
    environment:
      - TERMINALS_BACKEND=docker
      - TERMINALS_API_KEY=${TERMINALS_API_KEY}
      - TERMINALS_IMAGE=ghcr.io/hrida-ai/hrida-terminal:latest
      - TERMINALS_NETWORK=hrida-ai-network
      - TERMINALS_IDLE_TIMEOUT_MINUTES=30
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - terminals-data:/app/data
    networks:
      - hridaai

volumes:
  hrida-ai:
  terminals-data:

networks:
  hridaai:
    name: hrida-ai-network

Set the shared API key in a .env file next to your Compose file:

TERMINALS_API_KEY=change-me-to-a-strong-random-value

Then start everything:

docker compose up -d

HridaAI will be available at http://localhost:3000. When any user activates a terminal, the orchestrator provisions their personal container automatically.

Docker socket access

The orchestrator needs access to the Docker socket (/var/run/docker.sock) to manage containers. For production, use a Docker socket proxy like Tecnativa/docker-socket-proxy to restrict the API calls it can make.

Configuration reference
VariableDefaultDescription
TERMINALS_BACKENDdockerBackend type. Set to docker for this deployment mode.
TERMINALS_API_KEY(empty)Shared secret for authenticating requests from HridaAI. Required.
TERMINALS_IMAGEghcr.io/hrida-ai/hrida-terminal:latestDefault container image for user terminals.
TERMINALS_PORT3000Port the orchestrator listens on.
TERMINALS_HOST0.0.0.0Address the orchestrator binds to.
TERMINALS_NETWORK(empty)Docker network for user containers. When set, containers communicate by name.
TERMINALS_DOCKER_HOST127.0.0.1Address for published container ports. Only relevant without TERMINALS_NETWORK.
TERMINALS_DATA_DIRdata/terminalsHost directory for per-user workspace data.
TERMINALS_IDLE_TIMEOUT_MINUTES0 (disabled)Minutes of inactivity before a container is stopped. Set to 30 for typical usage.
TERMINALS_MAX_CPU(empty)CPU limit for user containers (e.g., 2).
TERMINALS_MAX_MEMORY(empty)Memory limit for user containers (e.g., 4Gi).
TERMINALS_OPEN_HRIDAAI_URL(empty)If set, validates incoming JWTs against this HridaAI instance instead of using TERMINALS_API_KEY.
Container lifecycle details

Naming. Containers are named terminals-{policy_id}-{user_id}, making them easy to filter with docker ps --filter "label=managed-by=terminals".

Health checks. After creating a container, the orchestrator polls its /health endpoint until it returns HTTP 200 (up to 15 seconds). Only then does it start proxying traffic.

Reconciliation. If the orchestrator restarts, it rediscovers existing running containers by their labels and recovers their API keys from the container configuration. This prevents duplicate containers from being created.

Conflict handling. If a container with the same name already exists (e.g., from a previous failed cleanup), the orchestrator force-removes the old container and retries up to 3 times.

Limitations​

  • Single host. All user containers run on one Docker host. For high availability or larger teams, use the Kubernetes Operator backend.
  • No built-in HA. If the orchestrator goes down, active terminal sessions are interrupted (though containers keep running and are reconciled on restart).
  • Docker socket required. The orchestrator needs access to the Docker socket to manage containers.

Authentication​

The orchestrator supports three authentication modes:

ModeWhen to useHow to configure
HridaAI JWTProduction. The orchestrator validates tokens against your HridaAI instance.Set TERMINALS_OPEN_HRIDAAI_URL on the orchestrator to your HridaAI URL.
Shared API keyStandard. HridaAI includes a shared secret in every request.Set TERMINALS_API_KEY to the same value on both HridaAI and the orchestrator.
OpenDevelopment only. No authentication. Do not use in production.Leave both TERMINALS_OPEN_HRIDAAI_URL and TERMINALS_API_KEY unset.

When deployed via Docker Compose or Helm, the shared API key is configured automatically between HridaAI and the orchestrator.

Troubleshooting​

Terminal won't start​

  1. Check orchestrator logs. The orchestrator logs the full provisioning flow, including image pull and container creation. Look for errors related to image availability or resource limits.
  2. Verify the API key. Ensure TERMINALS_API_KEY matches between HridaAI and the orchestrator. A mismatch causes silent auth failures.
  3. Check image pull access. If using a private container registry, make sure the orchestrator (Docker) or cluster (Kubernetes) has pull credentials configured.

Authentication failures​

  • If using JWT mode, confirm TERMINALS_OPEN_HRIDAAI_URL points to a reachable HridaAI instance.
  • If using API key mode, confirm the key is set identically on both sides. Check for extra whitespace or newlines.
  • Check the orchestrator logs for 401 or 403 responses.

Container is reaped too quickly​

Increase TERMINALS_IDLE_TIMEOUT_MINUTES (or idle_timeout_minutes in a policy). The default is 0 (disabled), but if set too low, containers may be cleaned up while users are still working. A value of 30 is typical.

Connection refused​

  • Docker: ensure TERMINALS_NETWORK is set so containers can communicate by name. Without it, containers use published ports and the TERMINALS_DOCKER_HOST address must be reachable.
  • Kubernetes: verify the orchestrator Service is accessible from the HridaAI Pod. Run kubectl get svc -n hrida-ai to confirm the service exists.

Further reading​

License​

Terminals requires an HridaAI Enterprise License for production use. See the Terminals repository for details.

This content is for informational purposes only and does not constitute a warranty, guarantee, or contractual commitment. Hrida AI is proprietary software owned by Zlabs Innovation, provided "as is." See your license for applicable terms. © 2026 Zlabs Innovation. All rights reserved.