Standalone and Development Mode

Your app runs in three environments during its lifecycle:

Environment	Platform context	Token source	How to enable
Standalone / local dev	None	`OS_JWT` from `.env`	`OS_DEV_MODE=true`
Developer Mode	Live (iframe)	Injected by platform	Octostar App Editor
Production	Live (iframe)	Injected by platform	Deployed container

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 OS_DEV_MODE. The @dev_mode() decorator reads this flag automatically and switches token sourcing accordingly:

import os
from octostar.client import dev_mode
from streamlit_octostar_utils.octostar.client import impersonating_running_user

@impersonating_running_user()
@dev_mode(os.environ.get("OS_DEV_MODE"))   # True → use OS_JWT from .env
def loop(client):
    ...

When OS_DEV_MODE=true, the decorator impersonates the user defined by OS_JWT in .env instead of requiring a live platform session. For manual checks elsewhere in your code:

import os

DEV_MODE = os.environ.get("OS_DEV_MODE", "").lower() == "true"

Set OS_DEV_MODE=true in .env to enable standalone mode locally.

Conditional Octostar Features

For features that only make sense inside the platform, guard on the return value of desktop APIs rather than the dev mode flag — these functions return None when no platform context is available:

from octostar_streamlit.desktop import get_active_workspace, get_open_workspace_ids

active = get_active_workspace()

if active is not None:
    # Running inside Octostar — use live workspace context
    open_ids = get_open_workspace_ids() or []
else:
    # Standalone fallback — let the user enter a workspace ID manually
    open_ids = [st.text_input("Workspace UID")]

Backend: SDK Availability

The Octostar Python client is only present at runtime inside the Docker container (downloaded by main.sh). Guard any SDK import with an availability check so your backend responds gracefully during local development without the SDK installed:

try:
    import octostar.client
    OCTOSTAR_SDK_AVAILABLE = True
except ImportError:
    OCTOSTAR_SDK_AVAILABLE = False
@app.get("/api/workspaces")
async def get_workspaces(token: str = Depends(get_token)):
    if not OCTOSTAR_SDK_AVAILABLE:
        return {"workspaces": [], "warning": "Octostar SDK not available"}
    # real implementation...