Quickstart

A cold start — clone to first agent reply — takes under ten minutes on a machine that already has Node and Python.

Clone the repo

You need access to sachio222/porto (private). Clone over SSH:

git clone git@github.com:sachio222/porto.git
cd porto

Run the first-run wizard

./setup.sh

The script checks Node, Python, Docker, and the Supabase CLI against the repo pins, installs frontend and backend deps, starts local Supabase, applies migrations, and writes backend/.env plus frontend/.env.local.

Safe to re-run. It will not clobber a running database or overwrite existing env files. Use ./setup.sh --check for a dry run, or --force to overwrite env files.

Start the backend

In one terminal:

cd backend
source .venv/bin/activate
uvicorn main:app --reload --port "${PORTO_PORT:-8000}"

Confirm it is up:

curl -s http://localhost:8000/healthz
# {"status":"ok"}

Start the frontend

In a second terminal:

cd frontend
npm run dev

Open http://localhost:3000.

Connect a model, then add an agent

Open Settings → Providers.
Connect one of: a CLI harness, a local host, or a cloud API key.
Create or open a project.
Add agent, pick the connected host, send a message.

Keys and host URLs live in Settings. You do not paste a key into the Add agent form.

Prefer Docker?

One command if you only have Docker installed. See Docker Compose.

cp .env.compose.example .env   # fill SUPABASE_SERVICE_ROLE_KEY + SUPABASE_ANON_KEY
docker compose up

If setup fails

Docker daemon is not running

Local Supabase needs Docker. Start Docker Desktop, then re-run ./setup.sh.

Node or Python version is off

Run ./scripts/check-versions.sh. Node must be 20–22. Python must be 3.11. Next 15 breaks on odd Node lines (21, 23, …).

Port 3000 or 8000 is already taken

Stop the other process, or set PORTO_PORT for the API and NEXT_PUBLIC_PORTO_WS_URL for the frontend. See environment.

Get started

Install

Connect models

Use porto

Prefer Docker?

If setup fails

​Prefer Docker?

​If setup fails

Prefer Docker?

If setup fails