Skip to content

Getting Started

This guide gets a new user into the platform and a new developer into the codebase. For the product overview and architecture, see the README.

For users

  1. Sign in. Go to https://mit.nonlocally.org and sign in with Google or GitHub (OAuth). New accounts use self-service signup; access is granted per the platform's approval policy.
  2. Chat. Pick a model from the model selector (Claude / OpenAI / local Ollama) and start a conversation. Tools for notebooks and photonic design are available from the chat.
  3. Open a notebook. Use the workspace split-screen: chat on the left, a live Marimo notebook on the right. Create a notebook, edit cells, and run them — execution happens in a sandboxed, per-user environment.
  4. Browse the gallery. Public notebooks are available in the gallery and are linked from chat. You can submit your own notebook for publication; submissions go through a review queue before appearing publicly.
  5. Design & verify. Use the photonic/EDA tools (GDSFactory layout, Optiverse ray tracing, Lean4/VVUQ verification) directly from chat.

Need help? See support.md.

For developers

Prerequisites

  • Python 3.11
  • (Optional) kubectl access to the GKE cluster for deployment/live tests

Set up

git clone https://github.com/Englund-Garage/openweb-marimo-platform.git
cd openweb-marimo-platform
pip install -e ".[dev]"

Run the tests

# Fast unit suite (safe defaults: 30s timeout, integration/external deselected)
python -m pytest tests/unit/ -v --timeout=30

# Critic quality gates
python -m pytest tests/critic-generated/ --timeout=30

# Executable goal-state gates — the definition of "done" (GOAL.md)
make goal-check-source      # source-level subset (CI gate)
make goal-check             # full suite; live (requires_cluster) gates xfail off-cluster

How the goal state works

The launch goal is encoded as tests under tests/goal/. Each criterion in GOAL.md maps to one named test. Unmet criteria ship as @pytest.mark.xfail(strict=True), so the day a feature lands its test starts passing → a strict XPASS failure forces you to remove the marker and check the box. The goal therefore cannot be silently faked. CI enforces this via .github/workflows/goal-gate.yml.

Making a change

  1. Write or update a test first (TDD).
  2. Implement the minimal code to pass it.
  3. Run the relevant suite + make goal-check-source.
  4. Commit with a conventional-commit message (feat:/fix:/docs:/…).
  5. Open a PR; the org-conventions, unit-tests, and goal-gate checks must pass.

Deploying

Deployment to GKE is driven by the workflows in .github/workflows/ (deploy-staging.yml, workspace-agent-staging.yml). See AGENT.md for operational details, gotchas, and the source-companion test pattern for cluster-dependent invariants.