Skip to main content

Local Development

The frontend and backend run as two separate processes. Vite proxies API calls from the frontend to the backend, so you never deal with CORS during development.

Architecture​

Browser → Vite dev server (:5173)
              └── /api/* → proxied to FastAPI (:8000)
              └── everything else → React app (hot-reloaded)

This proxy is configured in vite.config.ts:

server: {
  port: 5173,
  proxy: {
    '/api': {
      target: 'http://localhost:8000',
      changeOrigin: true,
    },
  },
}

base: './' makes all asset paths relative, which is required for the React build to load correctly when served from FastAPI in production.

Environment setup​

Create frontend/.env with your development credentials:

# frontend/.env
VITE_OS_JWT=your_jwt_token_here     # Profile → Developer Tokens → Out Token
VITE_OS_STANDALONE=true             # Skip Octostar context, use the token above

Tokens expire hourly. Update VITE_OS_JWT when calls start returning 401. If your backend needs to call the Octostar API directly, also create a root .env:

# .env (backend)
OS_API_ENDPOINT=https://your-octostar-instance.com
OS_ONTOLOGY=os_ontology_v1
OS_JWT=your_jwt_token_here
OS_USER=your_username
OS_STANDALONE=true

Starting the servers​

Terminal 1 — backend:

source venv/bin/activate
uvicorn backend.main:app --reload --port 8000

Terminal 2 — frontend:

cd frontend
npm run dev

Open http://localhost:5173. The app runs in standalone mode — Octostar context is bypassed and the JWT is read from VITE_OS_JWT.

Testing Inside Octostar (Developer Mode)​

Standalone mode is useful for UI work, but to test entity context, drag-and-drop, and context menu integration you need to run your app inside the actual platform. Developer Mode lets you do this without a Docker build.

Setup​

  1. In Octostar, create a workspace to hold your app.
  2. Right-click the workspace → Create → App → Empty App Folder → give it a name.
  3. Open the app folder with the App Editor.
  4. Click Developer Mode and enter your local dev server URL: http://localhost:5173 Your frontend dev server is now embedded as a live iframe inside Octostar. The platform injects a real session token and entity context — exactly as in production.

Developer Mode connects Octostar directly to your local dev server. Keep npm run dev running while you test. You do not need VITE_OS_STANDALONE=true in this mode — the platform provides the token.

What you can test in Developer Mode that standalone can't provide​

  • ContextAPI.getContext() returns a real entity and token
  • Right-click context menu entries (defined in manifest.yaml services) trigger with actual entities
  • OsDropzone receives real entities dragged from the Octostar sidebar
  • DesktopAPI.getOpenWorkspaces() returns the actual open workspaces