Pular para o conteúdo principal

Python em Linux/macOS

Instalação direta para quem quer rodar o Toposync no próprio sistema, sem Docker.

Para Quem É​

Use este caminho em Linux ou macOS.

Este guia instala o bundle padrão em CPU.

Para suporte por arquitetura e GPU, consulte Compatibilidade.

Pré-requisitos​

  • Python 3.12 recomendado.
  • uv.
  • Acesso ao terminal.

Instale o uv se ainda não tiver:

curl -LsSf https://astral.sh/uv/install.sh | sh

Feche e abra o terminal se o comando uv ainda não aparecer no PATH.

Instalação​

Crie uma pasta para o Toposync:

mkdir -p ~/toposync
cd ~/toposync

Instale o Python recomendado e crie o ambiente virtual:

uv python install 3.12
uv venv .venv --python 3.12
source .venv/bin/activate

Instale o Toposync:

uv pip install --upgrade --refresh toposync

Se precisar reproduzir uma versão específica:

uv pip install --upgrade --refresh "toposync==0.7.2"

Como Rodar​

Para uso local:

toposync serve

Para acessar pela rede local:

toposync serve --host 0.0.0.0 --port 8000

Para escolher a pasta de dados:

toposync serve --data-dir ./toposync-data

Como Acessar​

No mesmo computador:

http://127.0.0.1:8000/

De outro dispositivo na mesma rede, use o IP do servidor:

http://<ip-do-servidor>:8000/

Como Verificar​

Em outro terminal:

curl -I http://127.0.0.1:8000/
curl http://127.0.0.1:8000/api/health
curl http://127.0.0.1:8000/api/auth/status

O esperado:

  • / responde 200;
  • /api/health responde 200;
  • /api/auth/status responde JSON e pode indicar requires_setup: true no primeiro acesso.

Depois de concluir o setup/login pela UI, a API autenticada passa a responder as rotas protegidas, como /api/extensions.

Como Atualizar​

Com o ambiente virtual ativo:

uv pip install --upgrade --refresh toposync

Depois reinicie o processo toposync serve.

Como Desinstalar​

Pare o servidor e remova a pasta onde você criou o ambiente:

deactivate 2>/dev/null || true
rm -rf ~/toposync

Se você usou outra pasta de dados, remova também essa pasta.

Troubleshooting​

toposync: command not found​

Ative o ambiente virtual:

source .venv/bin/activate

A UI não abre​

Confirme se o servidor está rodando e se /api/health responde:

curl http://127.0.0.1:8000/api/health
curl http://127.0.0.1:8000/api/auth/status

Quero streaming​

Instale o bundle de streaming:

uv pip install --upgrade --refresh toposync-streaming

O streaming pode exigir FFmpeg disponível no sistema.