ORBI guide

ORBI is a map-first trip planner. You plan each day as a timeline of places and activities, see the real routes between them on a map, and get arrival times that add up. An AI assistant can draft days, edit them, or turn an itinerary you already have into a trip.

It is free and open source (AGPL-3.0). Use the hosted version, or run your own copy: see Self-hosting.

Click Log in and choose Continue with Google. ORBI only receives your name, email and profile photo. Every account has its own private trips; nobody else can see or open them.

Your account menu (your photo, top right) has Settings, this Help page, the app version and Log out.

1. Open My Trips and click New Trip.
2. Give it a name and a region (for example "Cebu, Philippines").
3. Pick start and end dates, or leave them empty and set the number of days. Add a budget if you want ORBI to track costs.
4. Click Create trip. The trip opens with its days ready to fill.

Every trip is a card with a countdown, dates, days, places and budget. Use the search box and the Upcoming / Past / All filter to find one. The buttons on each card edit, duplicate (a full copy with every stop) or delete the trip.

On the right, Timezones shows live clocks. Click + to add up to five cities and hover a clock to remove it. Upcoming trips lists your next trips by date.

Inside a trip, pick a day from the day menu. The day header shows the distance, number of places, end time and cost. The sliders button opens the day's title, start time and travel mode (walking or driving).

The day is a timeline: numbered dots are places, icons are activities. The time on each card is when you arrive. Between places you see the travel distance and time. Drag a dot on the line to reorder; times and routes update straight away.

Use Add a place on the right of the trip. Search by name (results near the day you are viewing come first), then choose Add to Day N or Save as idea. Ideas wait in the trip until you schedule them on a day.

Click a place card to highlight it on the map. The pencil edits its name, visit length, fixed arrival time, category, cost, opening hours and notes, and lets you move it to another day. The arrow button opens the place in Google Maps for directions.

Activities are moments without a place on the map: wake up, breakfast, lunch, dinner, rest, free time, check in or out, transfers. Click Add activity under the timeline, pick a type (the duration fills in for you) and optionally a label like "at the hotel". Activities take time in the schedule but add no travel.

The map shows the selected day's stops and routes. Use Satellite on the map to switch to aerial imagery and back. In Settings → Map you can make the map follow the app theme, or always use light, dark or satellite.

The trip header shows the estimated total against your budget, and turns red when you go over. The pencil next to the trip name opens Edit trip: name, region, dates, budget, day start and end, pace, daily travel limit, interests and planning notes. Interests and notes also guide the AI.

ORBI uses your own AI provider, so you control the cost. Open Settings → Integrations, choose a provider (OpenRouter, OpenAI, Anthropic or Google), paste your API key and pick a model. The list only shows free and low-cost models.

In a trip, the AI assistant box takes a request like "historic sights, local food and a beach day within ₱10,000". Draft days plans full days in time order: wake up, breakfast, sights, lunch, dinner. Suggest edits changes what you already have, for example "make day 2 less tiring".

You review every suggestion before it is saved: untick anything you don't want, then apply. Every place is checked against map data; places that can't be found are marked and skipped.

The round button at the bottom right opens the ORBI on every page. Ask travel questions, or:

• Paste an itinerary ("Day 1: …, Day 2: …") and ORBI creates the whole trip with every stop on the map.
• Edit a trip by name ("add a seafood lunch to my Cebu weekend"), or say "this trip" while one is open. Chat edits apply straight away.

Minimize the chat with –: a reply keeps running and a small pill shows its progress; a dot on the button means a reply is waiting. The conversation is saved in your browser until you clear it. The assistant only discusses travel.

• General: light, dark or system theme; 24-hour or 12-hour times; kilometres or miles.
• Map: map style.
• Integrations: your AI provider and key.
• Account: who you are signed in as, and log out.

The web app works on phones: the map sits on top and the plan below. On iPhone, open ORBI in Safari, tap Share → Add to Home Screen. An Android app is part of the project (see Android app).

Trips are tied to your Google account and stored in the ORBI database. Your AI key, chat history and display settings stay in your browser. Place search and routing use OpenStreetMap services; map tiles come from OpenFreeMap and satellite imagery from Esri.

You need Node.js 26 and pnpm 11. Then:

git clone https://github.com/kaizenics/orbi.git orbi
cd orbi
pnpm install
pnpm dev

Open http://localhost:3000. The API runs inside the web app and keeps data in apps/web/data/orbi.db, created automatically. Sign-in is off on your computer until you add Google credentials. Optional demo trip:

ORBI_DATABASE_URL=file:../web/data/orbi.db pnpm --filter @orbi/server db:seed

1. Database: create a free database at turso.tech, copy its URL and a token, and create the tables:

   ORBI_DATABASE_URL=libsql://<db>.turso.io ORBI_DATABASE_AUTH_TOKEN=<token> \
     pnpm --filter @orbi/db db:migrate

2. Google sign-in: in Google Cloud Console create an OAuth client (Web application) and add https://<your-domain>/auth/google/callback as an authorized redirect URI. Publish the consent screen so any Google account can sign in.
3. Vercel: import the repository, choose the web app (root directory apps/web), add the variables below and deploy.

To run the API on a server or VM instead, use the included Docker setup (Caddy provides HTTPS):

cp infra/.env.example infra/.env   # set ORBI_DOMAIN, ORBI_API_TOKEN
docker compose -f infra/docker-compose.yml up -d --build

Then set ORBI_API_URL=https://<server-domain> and the same ORBI_API_TOKEN in the web app so it forwards API calls to your server. Maps, search and routing can also point at your own OpenFreeMap, Nominatim/Photon and OSRM instances.

The Android app needs Android Studio and a development build. Point it at your server in apps/mobile/.env, then build:

EXPO_PUBLIC_API_URL=https://<your-domain>/api
EXPO_PUBLIC_API_TOKEN=<ORBI_API_TOKEN>

pnpm --filter mobile android

"Continue with Google" shows a redirect error

Add your site's /auth/google/callback address to the OAuth client's authorized redirect URIs.

Only some Google accounts can sign in

Your OAuth consent screen is in testing mode. Publish it in Google Cloud Console.

Trips fail to load after an update

The database needs the latest migrations. Run the db:migrate command against your database.

The AI says the key was rejected

Check the key in Settings → Integrations, and that the chosen model is available to it.

A place can't be found

Try the official name plus the city, or add it with the map search and keep the AI suggestion's details.