Run locally in 5 minutes

This is the fastest way to see Radioso doing its job: one script, a local stack, and a grounded answer from your own document a few minutes later. You get the dashboard, the API, and the background worker on one machine, so you can upload real content and check the answers before you think about deployment.

Prerequisites

• Node.js 24+
• Docker with docker compose
• A provider API key (OpenAI, Gemini, or Anthropic) — optional at startup, needed before your first grounded answer

You need Node.js because ./run-dev.sh runs a small Node bootstrap script before the containers come up. The provider key is what turns your documents into embeddings and your questions into answers, so pick the provider you already have credit with.

Start the stack

./run-dev.sh

This is the bootstrap path, and it does the fiddly parts for you. It:

• checks local prerequisites
• creates or reuses .env
• offers to store an AI provider key; enter one now or add it later in the app under Settings → Credentials
• generates missing secrets such as SESSION_COOKIE_SECRET, WORKSPACE_TOKEN_SECRET, and PUBLIC_CHAT_SESSION_SECRET
• configures uploaded document storage to use the local filesystem by default
• builds and starts Postgres, the backend API, the background worker, and the frontend with Docker Compose
• waits until the frontend and backend are reachable

When it finishes, open:

• App: http://localhost:3000
• API: http://localhost:8080
• Enterprise embed test harness: http://127.0.0.1:4321 after running node scripts/serve-embed-test-site.mjs

For Enterprise Edition embed development, use ./run-ee-dev.sh instead. It builds the commercial packages from ee/packages, generates the local EE frontend routes, configures the local backend, starts the same app and API URLs, and starts the embed test harness automatically. The ./run-dev.sh path removes those generated routes before starting the OSS stack.

Pick a local goal

You don’t have to do everything at once. Pick the goal that matches why you’re here.

Verify first success in the app

1. Open http://localhost:3000
2. On a new server, register the first user. Otherwise, sign in or accept an invitation
3. Upload a document or let the starter documents finish processing
4. Ask one suggested question

The worker takes a moment to chew through your upload. Give it until the status reads Ready, and the document is fair game for a retrieval test.

Now ask something you know the document answers. The Chat workbench is where you talk to your agent, and a good answer cites the source it came from rather than guessing.

Success looks like this:

• the frontend loads
• you can initialize a new server or sign in to an existing one
• you can upload a document
• Radioso returns an answer grounded in that document

Verify first success through the API

You don’t need to open the web app at all. The assistant chat API is how you talk to an agent from your own scripts, and the same routes back the dashboard.

Check whether this deployment allows open registration:

curl -sS http://localhost:8080/api/v1/auth/registration

On a new open-source server, this returns { "available": true }. Register the first user:

curl -sS \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"verysecurepassword"}' \
  http://localhost:8080/api/v1/auth/register

Registration creates the open-source server’s sole organization and default workspace. It returns workspace bootstrap data and sends a verification email, but does not set a session cookie. Verify the email address, then log in. Local mail delivery logs messages unless you configure a Resend API key, so if no email arrives, read the backend logs.

After the first organization exists, open-source registration availability is false. Later users join the existing organization by invitation. Enterprise Edition keeps open registration available and supports additional organizations. In either edition, authorized users can create more workspaces inside an organization.

Log in and save the session cookie:

curl -sS -c cookies.txt \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"verysecurepassword"}' \
  http://localhost:8080/api/v1/auth/login

Reveal the workspace API token with the session cookie:

curl -sS -b cookies.txt \
  http://localhost:8080/api/v1/account/workspaces/<workspace-id>/token

That token is what your scripts and SDK clients authenticate with once you leave the browser behind.

What local development changes

Local bootstrap tunes the stack for a fast look, not for mirroring every production constraint:

• uploaded source files are stored on the local filesystem
• Docker Compose runs the app, API, worker, and Postgres together

Common failure modes

• If the stack starts but answers fail, the usual cause is missing or invalid provider credentials in .env.
• If upload works but chat ignores the new document, processing is probably still running. Check the document’s status before you blame retrieval.
• If auth links don’t arrive by email, read the backend logs first, because local mail defaults to log mode.

What to do next

• If the local app looks right, continue with API first success or Embed on your website.
• If you’re trying to understand why answers look wrong, review Document upload and Agents and skills.