Standalone and Development Modes

Your app runs in three environments during its lifecycle:

Mode	How it runs	Token source
Production	Docker container deployed to Octostar, embedded as an iframe	ContextAPI.getContext()
Developer Mode	Local dev server connected to Octostar via the App Editor's Developer Mode	ContextAPI.getContext()
Standalone	Local dev server accessed directly, no Octostar shell	VITE_OS_JWT from frontend/.env

In Developer Mode and production, the app runs inside the Octostar iframe and receives a live platform context. In standalone mode, the app runs completely outside the platform — useful for pure UI work and faster iteration without needing an Octostar connection.

Detecting Standalone Mode

The template detects the current environment via an environment variable, not iframe inspection:

// utils/env.ts
export const isStandalone = (): boolean =>
  import.meta.env.VITE_OS_STANDALONE === 'true'

This flag is checked in App.tsx to tell StateProvider whether to fetch the token from the Octostar context or fall back to VITE_OS_JWT:

// App.tsx
<StateProvider withOctostar={!isStandalone()}>
  <AppContent />
</StateProvider>

Set VITE_OS_STANDALONE=true in frontend/.env to enable standalone mode locally:

# frontend/.env
VITE_OS_JWT=your_token_here
VITE_OS_STANDALONE=true

Conditional Octostar Features

For features that only make sense inside the platform, guard on API availability at runtime rather than the standalone flag:

const { DesktopAPI } = useOctostarContext()

if (DesktopAPI) {
  // Running inside Octostar
  const workspaces = await DesktopAPI.getOpenWorkspaces()
} else {
  // Standalone fallback
  const workspaces = await api.request('/workspaces')
}

Backend: SDK Availability

The Octostar Python client is only present at runtime inside the Docker container. Guard any SDK usage with an availability check:

try:
    import octostar.client
    OCTOSTAR_SDK_AVAILABLE = True
except ImportError:
    OCTOSTAR_SDK_AVAILABLE = False

This lets your backend respond gracefully (or return a mock) during local development without the SDK installed.