Setup and configuration
Prepare the globe computer
You need the built TellUs AI package, a separate asset library, Node.js 20 or later on the globe computer, a microphone and speakers, and internet access for the assistant. Ethernet, Wi-Fi, or 5G can provide that internet connection; 5G is not a software requirement.
Connect the microphone receiver and speakers before starting the app. The project has used a RØDE Wireless PRO microphone, but select the devices actually present at your site.
- Extract the complete app package into your PufferConsole applications directory, for example
C:\PufferConsole\applications\TellUsAI. - Extract
tellus-datato a suitable folder. It can live separately from the application. - Copy the supplied
config.example.jsontoconfig.jsonbesiderun.exe. - Set
openaiApiKeyandassetsPath. Keep the real key in the local configuration. - Start TellUs AI from PufferConsole, or run the package's
run.exeon the globe computer.
Keep the packaged directory structure intact; the launcher expects its components under infra.
Configuration reference
Start with the supplied example. For a standalone globe, keep mode: "server" and assets: "local". Restart after configuration edits.
All launcher settings (reference)
| Field | Example / starting value | Purpose |
|---|---|---|
mode | "server" | Starts the local service server. "remote" connects the service client to remoteUrl. |
port | 8000 | Local WebSocket server port in server mode. |
remoteUrl | "wss://example.com/tellus-server/" | Service connection in remote mode. Replace the placeholder for a remote installation. |
services | ["tuio", "audio", "openai", "scenario", "thumbnails"] | Starts touch, hardware audio, AI, orchestration, and shared quick-topic configuration. Keep thumbnails enabled for editable quick topics. |
assets | "local" | Serves the local asset folder. "remote" uses remoteAssetsUrl. Independent of server/remote service mode. |
assetsPath | "C:\\PufferConsole\\applications\\tellus-data" | Absolute local data directory containing index.json. |
assetsPort | 3002 | Local asset HTTP port. |
remoteAssetsUrl | "https://example.com/tellus-data" | Root of the remote asset library in remote asset mode. |
frontendPort | 3000 | Operator dashboard HTTP port. |
webrenderPort | 3001 | Browser renderer and second-screen preview HTTP port. |
tuioUrl | "ws://localhost:8080" | Touch input connection on the globe computer. |
consoleMode | "hidden" | No child console windows; service output is written under logs. "shared" also shows combined output. "separate" opens individual consoles and does not provide those launcher log files. |
defaultMicMuted | false in the current example | Controls launch-time microphone mute. Set true to start quietly. If omitted, the launcher defaults to true. |
openaiApiKey | Empty in the example | Your site's OpenAI API key. Must be set for AI conversation. |
mode selects the service connection; assets selects the data source. Remote setups need an installation-specific plan.
JSON strings need escaped Windows backslashes. For the example data location, write:
{
"assets": "local",
"assetsPath": "C:\\PufferConsole\\applications\\tellus-data",
"defaultMicMuted": true
}
This excerpt belongs in the full configuration. Use valid JSON without comments or trailing commas.
Model, voice, personality, and rules are adjusted in the frontend; they are not extra fields in this launcher example. See scenario profiles.
Connect from a tablet or laptop
Use the same reachable network as the globe computer. If its hostname is pufferfish, open:
- Main interface:
http://pufferfish:3000/ - Quick topics:
http://pufferfish:3000/topics - Service dashboard:
http://pufferfish:3000/dashboard/services - Second-screen preview:
http://pufferfish:3001/?display=screen
Replace pufferfish with your installation's hostname or IP address. On a tablet, localhost means the tablet itself. Use your configured ports if they differ from the examples.
The preview receives scene updates but keeps dragging local. Use Webrender to control the real globe.
Verify startup
Open the home page and check connected. Under Scenario Configuration, the normal local service selections are:
| Selection | Typical value |
|---|---|
| Scenario service | scenario:node:1 |
| Scenario | guide |
| Scene | scene:webrender:1 |
| Assistant | assistant:openai:1 |
| Touch | touch:tuio:1 |
| Audio | audio:hardware:1 |
Service instance numbers can differ. An empty separate Transcriber selection is not itself a problem for guide mode, which uses the realtime assistant's input transcription.
Check the selected microphone and speaker in the audio tab. Then try loading Blue Marble using the Webrender tab. The initial startup map is a placeholder, so select a catalogue asset before testing dataset features.
Do not rely solely on a spoken startup message; audio routing can hide it.
Preserve local content when updating
Before replacing a package, stop the app and back up its local profiles and thumbnail files. Keep the real API configuration private and set the new installation's own key and asset path. Reopen the UI and check the default profile, linked asset IDs, and audio devices after the update.