Installation

Talome runs as a Docker container on Linux, macOS, or Windows. The installer handles everything — Docker, secrets, networking — so you can go from bare metal to a running dashboard in a single command.

System Requirements

Operating System

Talome requires a 64-bit OS. 32-bit ARM is not supported.

Hardware

Disk requirements are for Talome itself plus Docker images. Your media, app data, and backups need additional storage.

Docker

Docker 20.10+ is required. The installer checks for Docker and installs it automatically if missing — via the official Docker repository on Linux, or by downloading OrbStack/Docker Desktop directly on macOS and Windows.

Quick Install

Linux / macOS:

curl -fsSL https://get.talome.dev | bash

Windows (PowerShell):

irm https://get.talome.dev/install.ps1 | iex

This single command does the following:

1. Detects your OS and architecture — Linux (amd64/arm64), macOS, or Windows
2. Installs Docker if not present (Linux only, via official Docker repository)
3. Generates a 64-character hex secret for session encryption
4. Pulls the Talome container image from ghcr.io/tomastruben/talome
5. Creates a Docker Compose file at ~/.talome/docker-compose.yml
6. Starts Talome with persistent storage, Docker socket access, and restart policy
7. Prints the dashboard URL — http://localhost:3000

The entire process takes 30-60 seconds on a typical connection.

Docker Compose (Manual)

If you prefer full control over the deployment, create the compose file yourself.

services:
  talome:
    image: ghcr.io/tomastruben/talome:latest
    container_name: talome
    restart: unless-stopped
    ports:
      - "3000:3000"   # Dashboard (Next.js)
      - "4000:4000"   # API server (Hono)
      - "4001:4001"   # Terminal daemon (WebSocket)
    volumes:
      - talome-data:/app/data                          # SQLite DB, configs, backups
      - /var/run/docker.sock:/var/run/docker.sock      # Docker control
    environment:
      - NODE_ENV=production
      - TALOME_SECRET=<your-64-char-hex-string>        # Required: session encryption

volumes:
  talome-data:

Generate a secret and start:

# Generate a secure secret key
export TALOME_SECRET=$(openssl rand -hex 32)

# Start Talome
docker compose up -d

Post-Install Checklist

After Talome is running, complete these steps to unlock the full experience:

1. Open the Dashboard

Navigate to http://localhost:3000 (or http://<your-server-ip>:3000 from another device on your network).

2. Create Your Admin Account

Set a password on first visit. This is the only account — Talome is designed for a single admin user.

3. Add Your AI Provider Key

Go to Settings > AI Provider and paste your API key. Talome supports three providers:

4. Verify the AI Works

Open the assistant from the sidebar (or press / to open the command palette) and type:

What can you do?

If you see a detailed response listing capabilities, the AI is connected and ready.

Ports

Talome uses three ports by default:

To change ports, set CORE_PORT, or modify the port mappings in your compose file. The dashboard port is configured via the Next.js server.

macOS Notes

OrbStack vs Docker Desktop

OrbStack is the recommended Docker runtime on macOS. It uses significantly less memory and CPU than Docker Desktop, and the socket path is more predictable.

OrbStack socket path:

DOCKER_SOCKET=/Users/$USER/.orbstack/run/docker.sock

Docker Desktop socket path:

DOCKER_SOCKET=/var/run/docker.sock

If you use OrbStack, add the socket path to your compose environment:

environment:
  - DOCKER_SOCKET=/Users/$USER/.orbstack/run/docker.sock

File sharing

Docker on macOS requires explicit file sharing for host volume mounts. If you mount media directories (e.g., /Volumes/Media), ensure the path is shared in OrbStack or Docker Desktop settings.

Updating

curl -fsSL https://get.talome.dev | bash -s -- update

Or manually with Docker Compose:

docker compose pull
docker compose up -d

Updates preserve everything:

• SQLite database (users, conversations, memories, automations, widgets, app records)
• Installed apps and their data
• Settings and API keys
• Custom tools and user-created apps
• Notification channel configurations

Updates replace:

• The Talome container image (backend + dashboard)

Firewall Configuration

If your server has a firewall (UFW, firewalld, iptables), open these ports:

# UFW (Ubuntu/Debian)
sudo ufw allow 3000/tcp   # Dashboard
sudo ufw allow 4000/tcp   # API

# firewalld (Fedora/CentOS)
sudo firewall-cmd --permanent --add-port=3000/tcp
sudo firewall-cmd --permanent --add-port=4000/tcp
sudo firewall-cmd --reload

Port 4001 (terminal daemon) only needs to be open if you access Talome's browser terminal from another machine. The MCP server uses stdio, not a network port — no firewall rule needed for MCP.

Troubleshooting

Docker socket permission denied

Error: permission denied while trying to connect to the Docker daemon socket

Your user is not in the docker group. Fix:

sudo usermod -aG docker $USER
# Log out and back in, or run:
newgrp docker

Then restart Talome:

docker compose restart

Port already in use

Error: bind: address already in use

Another service is using port 3000 or 4000. Find it:

sudo lsof -i :3000
sudo lsof -i :4000

Either stop the conflicting service or change Talome's ports in your compose file.

ARM vs x86

Talome publishes multi-arch images for both amd64 and arm64. Docker automatically pulls the correct architecture. If you see platform mismatch errors, ensure your Docker version supports multi-platform images (Docker 20.10+).

Container keeps restarting

Check the logs:

docker logs talome --tail 50

Common causes:

• Missing TALOME_SECRET — the container exits if no secret is set
• Docker socket not mounted — verify /var/run/docker.sock is in your volumes
• Port conflict — another process is binding to 3000 or 4000
• Corrupted database — rare, but solvable by restoring from a backup

Dashboard loads but AI does not respond

1. Check that you have set an API key in Settings > AI Provider
2. Verify the key works: the Settings page shows a green checkmark next to the provider
3. Check the backend logs: docker logs talome --tail 20
4. If using Ollama, ensure the Ollama server is running and accessible from the Talome container

Uninstalling

To remove Talome completely:

# Stop and remove the container
docker compose down

# Remove the data volume (THIS DELETES ALL DATA)
docker volume rm talome-data

# Remove the Talome directory
rm -rf ~/.talome

# Remove the container image
docker rmi ghcr.io/tomastruben/talome:latest

Apps installed by Talome (Jellyfin, Sonarr, etc.) are separate Docker containers with their own volumes. Uninstalling Talome does not remove them. Use docker compose down -v in each app's directory to remove them individually, or ask the AI to uninstall them before removing Talome.

Next Steps