gini-toolkit 6.0.1.dev0__py3-none-any.whl

gini/runtime/switch.py

@@ -0,0 +1,109 @@
+"""User-space learning switch.
+
+One UDP port per link. Learns source MAC -> ingress port; floods broadcast/multicast
+and unknown unicast to all other ports; unicasts known destinations. This is the
+"multiplexed fabric switch" from the plan, here as a standalone process for the spike.
+
+Run as a process:  SWITCH_CONFIG='{"name":"s1","ports":[{...}]}' python -m dataplane.switch
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+from .control import maybe_start
+from .frame import is_multicast_mac, parse_eth
+from .transport import Port, run_loop
+
+
+class LearningSwitch:
+    def __init__(self, cfg: dict) -> None:
+        self.name = cfg["name"]
+        self.ports = [Port.from_cfg(p, name=f"p{i}") for i, p in enumerate(cfg["ports"])]
+        self.table: dict[str, Port] = {}     # mac -> port
+        self.log = cfg.get("log", False)
+        self._ctrl = maybe_start(self.name, self._control, f"switch {self.name}")
+
+    def _control(self, cmd: str) -> str:
+        cmd = cmd.lower()
+        if cmd in ("help", "?", "h"):
+            return "commands: mactable, ports, help, exit"
+        if cmd in ("mactable", "mac", "table"):
+            if not self.table:
+                return "(mac table empty)"
+            return "\n".join(f"  {m}  ->  {p.name}" for m, p in self.table.items())
+        if cmd == "ports":
+            return ", ".join(p.name for p in self.ports)
+        return f"unknown command: {cmd} (try 'help')"
+
+    def handle(self, inport: Port, frame: bytes) -> None:
+        dst, src, _etype, _payload = parse_eth(frame)
+        self.table[src] = inport
+        if dst == "ff:ff:ff:ff:ff:ff" or is_multicast_mac(dst):
+            self._flood(inport, frame)
+            return
+        out = self.table.get(dst)
+        if out is None:
+            self._flood(inport, frame)
+        elif out is not inport:
+            out.send(frame)
+        if self.log:
+            print(f"[{self.name}] {src} -> {dst} in={inport.name}", file=sys.stderr)
+
+    def _flood(self, inport: Port, frame: bytes) -> None:
+        for p in self.ports:
+            if p is not inport:
+                p.send(frame)
+
+    def run(self) -> None:
+        print(f"[{self.name}] learning switch up, {len(self.ports)} ports", file=sys.stderr)
+        run_loop(self.ports, self.handle)
+
+
+class Hub(LearningSwitch):
+    """A Layer-1 repeater — the device a switch replaced.
+
+    A hub is "dumb wire with more ports": every frame that arrives is repeated out of
+    every *other* port, with no MAC learning and no filtering. All ports therefore share
+    one collision domain and one broadcast domain. Pedagogically this is the foil to the
+    Switch: send a unicast h1->h2 through a hub and h3 still sees it (repeated to all);
+    through a switch, once it has learned, only h2 does. The control console makes the
+    difference explicit — a hub has no MAC table to show."""
+
+    def handle(self, inport: Port, frame: bytes) -> None:
+        self._flood(inport, frame)                 # repeat everything; never learn, never filter
+        if self.log:
+            dst, src, _etype, _payload = parse_eth(frame)
+            print(f"[{self.name}] repeat {src} -> {dst} in={inport.name} (flood all)",
+                  file=sys.stderr)
+
+    def _control(self, cmd: str) -> str:
+        cmd = cmd.lower()
+        if cmd in ("help", "?", "h"):
+            return ("commands: ports, help, exit  "
+                    "(a hub has no MAC table — it repeats every frame to all ports)")
+        if cmd in ("mactable", "mac", "table"):
+            return "(a hub has no MAC table — it repeats every frame out all other ports)"
+        if cmd == "ports":
+            return ", ".join(p.name for p in self.ports)
+        return f"unknown command: {cmd} (try 'help')"
+
+    def run(self) -> None:
+        print(f"[{self.name}] hub up (L1 repeater), {len(self.ports)} ports", file=sys.stderr)
+        run_loop(self.ports, self.handle)
+
+
+def make_switch(cfg: dict):
+    """Build the right L2 node for a fabric entry: a Hub (flood-all repeater) when the
+    compiler marked it `hub`, else a learning Switch."""
+    return Hub(cfg) if cfg.get("hub") else LearningSwitch(cfg)
+
+
+def main() -> None:
+    cfg = json.loads(os.environ["SWITCH_CONFIG"])
+    make_switch(cfg).run()
+
+
+if __name__ == "__main__":
+    main()

gini/runtime/transport.py

@@ -0,0 +1,77 @@
+"""Ethernet-in-UDP transport: a Port is a UDP socket carrying one frame per datagram.
+
+Same abstraction works two ways:
+  * Docker: bind 0.0.0.0:P, peer_host = a service name (Docker DNS), peer_port = P.
+  * Loopback test: bind 127.0.0.1 on distinct ports per endpoint.
+
+A "port" on a switch/router/host is exactly this. Internal fabric links would later
+swap this for an in-memory ring; the node code wouldn't change.
+"""
+from __future__ import annotations
+
+import selectors
+import socket
+
+
+class Port:
+    def __init__(self, bind_port: int, peer_host: str, peer_port: int,
+                 bind_host: str = "0.0.0.0", name: str = "") -> None:
+        self.name = name
+        self.peer_host = peer_host
+        self.peer_port = peer_port
+        self._peer_ip: str | None = None
+        self.sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        self.sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        self.sock.bind((bind_host, bind_port))
+        self.sock.setblocking(False)
+
+    @classmethod
+    def from_cfg(cls, cfg: dict, name: str = "") -> "Port":
+        return cls(cfg["bind_port"], cfg["peer_host"], cfg["peer_port"],
+                   cfg.get("bind_host", "0.0.0.0"), name)
+
+    def _resolve(self) -> str | None:
+        if self._peer_ip is None:
+            try:
+                self._peer_ip = socket.gethostbyname(self.peer_host)
+            except OSError:
+                return None  # DNS not ready yet (Docker startup) — caller drops
+        return self._peer_ip
+
+    def send(self, frame: bytes) -> None:
+        ip = self._resolve()
+        if ip is None:
+            return
+        try:
+            self.sock.sendto(frame, (ip, self.peer_port))
+        except OSError:
+            pass
+
+    def recv(self) -> bytes | None:
+        try:
+            data, _ = self.sock.recvfrom(65535)
+            return data
+        except BlockingIOError:
+            return None
+
+
+def run_loop(ports: list[Port], handler, tick=None, tick_interval: float = 0.5) -> None:
+    """Select over all ports; call handler(port, frame) for each frame.
+
+    handler receives the Port the frame arrived on, so a node can identify its
+    ingress port without any per-frame addressing.
+    """
+    sel = selectors.DefaultSelector()
+    for p in ports:
+        sel.register(p.sock, selectors.EVENT_READ, p)
+    while True:
+        events = sel.select(timeout=tick_interval)
+        for key, _ in events:
+            port: Port = key.data
+            while True:
+                frame = port.recv()
+                if frame is None:
+                    break
+                handler(port, frame)
+        if tick is not None:
+            tick()

gini/runtime/xv6_bridge.py

@@ -0,0 +1,312 @@
+"""xv6 live bridge (Mac side) — fills MachineState from the in-container agent over HTTP.
+
+The gdb reads happen INSIDE the gini-xv6 container (backend/xv6/gini_agent.py), where gdb and
+the kernel symbols live; this bridge just makes plain HTTP calls to the agent's published port
+and parses the returned text with the already-tested domain parsers. It is a drop-in for the
+offline DemoScheduler: snapshot()/step()/set_timeslice()/set_policy() plus `.vm`/`.fs` readers,
+so MachineState, the Machine Lab, and the Ask GINI card use it unchanged.
+
+The HTTP calls are injectable (`get=`/`post=`) so the compose + parsing logic is unit-tested
+without a running container; the VM/FS readers fall back to the demo shape on any error, so the
+Memory/Storage dialogs always open even if the live read momentarily fails.
+"""
+from __future__ import annotations
+
+import json
+import urllib.request
+
+from ..domain.xv6 import (
+    Snapshot, apply_proc_sched, parse_backtrace, parse_cpu_lines, parse_cpu_regs, parse_csr,
+    parse_modetime, parse_policies, parse_procdump, parse_registers, parse_regs_line, parse_sched,
+    parse_shadow_manifest, running_pid,
+)
+from ..domain.xv6_fs import FsSnapshot, Superblock, layout, parse_logheader, parse_superblock
+from ..domain.xv6_vm import VmSnapshot, parse_faults, parse_vmall, parse_vmprint
+
+# must match gini_pick() in gini_patch.py: 0=round-robin 1=priority 2=lottery. Custom student
+# policies (MLFQ, stride, …) get their own ids when added via the Scheduler Builder.
+POLICY_ID = {"round-robin": 0, "priority": 1, "lottery": 2}
+# each shadow overrides the policy at this index (the kernel toggles the CURRENT policy's shadow).
+SHADOW_POLICY = {"rr_sched": 0, "prio_sched": 1, "lottery_sched": 2}
+
+
+class AgentClient:
+    """HTTP client for the in-container agent. `get`/`post` are injectable for tests."""
+
+    # longer than the agent's own 6s gdb timeout, so a slow proc-walk under CPU load returns a
+    # result (even an empty one we can ignore) instead of the client abandoning it mid-read.
+    def __init__(self, base_url: str, get=None, post=None, timeout: float = 10.0) -> None:
+        self.base = base_url.rstrip("/")
+        self.timeout = timeout
+        self._get = get or self._http_get
+        self._post = post or self._http_post
+
+    def _http_get(self, url: str) -> str:  # pragma: no cover - real network
+        with urllib.request.urlopen(url, timeout=self.timeout) as r:
+            return r.read().decode(errors="replace")
+
+    def _http_post(self, url: str, body: str = "") -> str:  # pragma: no cover - real network
+        req = urllib.request.Request(url, data=body.encode() if body else None, method="POST")
+        with urllib.request.urlopen(req, timeout=self.timeout) as r:
+            return r.read().decode(errors="replace")
+
+    def get_json(self, path: str) -> dict:
+        try:
+            return json.loads(self._get(self.base + path))
+        except Exception:
+            return {}
+
+    def get_text(self, path: str) -> str:
+        try:
+            return self._get(self.base + path)
+        except Exception:
+            return ""
+
+    def post(self, path: str, body: str = "") -> str:
+        try:
+            return self._post(self.base + path, body) if body else self._post(self.base + path)
+        except TypeError:
+            return self._post(self.base + path)          # injected posts without a body arg
+        except Exception:
+            return ""
+
+
+class _VmReader:
+    def __init__(self, agent: AgentClient) -> None:
+        self.agent = agent
+
+    def snapshot(self):
+        # REAL only: return the live page table, or an explicit no-data VmSnapshot. Never fake.
+        # The region map + physical-allocator bar aren't dumped for real yet, so they're left
+        # empty (not in `have`) rather than borrowed from the demo.
+        try:
+            vm = parse_vmprint(self.agent.get_text("/vm"))
+            if vm.leaves:                               # got real mappings
+                vm.source, vm.ok, vm.have = "real", True, ("pagetable",)
+                return vm
+        except Exception:
+            pass
+        return VmSnapshot(source="real", ok=False, have=())
+
+    def all_procs(self):
+        """Every user process's page table (gini_vmdump_all) -> {pid: ProcVm}, for the two-proc
+        COW / sharing view. REAL only: empty dict if the read fails (the face shows an error)."""
+        try:
+            procs = parse_vmall(self.agent.get_text("/vmall"))
+            if procs:
+                return procs
+        except Exception:
+            pass
+        return {}
+
+    def faults(self):
+        """The live page-fault ring (gini_faultdump) -> [PageFault]. REAL only: empty list if the
+        read fails. Classification happens in the Memory face against the all-procs picture."""
+        try:
+            f = parse_faults(self.agent.get_text("/faults"))
+            if f:
+                return f
+        except Exception:
+            pass
+        return []
+
+
+class _FsReader:
+    def __init__(self, agent: AgentClient) -> None:
+        self.agent = agent
+
+    def snapshot(self):
+        # REAL only: superblock + log are dumped for real today; inodes/dir/bcache are NOT, so
+        # they stay empty and out of `have` (the face marks them "not available", never fakes).
+        # A failed read returns ok=False so the face shows an error instead of demo data.
+        try:
+            txt = self.agent.get_text("/fs")            # gini_fsdump over the serial (no gdb)
+            sb = parse_superblock(txt)
+            if sb.size:
+                log = parse_logheader(txt, start=sb.logstart, size=sb.nlog)
+                return FsSnapshot(sb=sb, regions=layout(sb), log=log,
+                                  source="real", ok=True, have=("layout", "log"))
+        except Exception:
+            pass
+        return FsSnapshot(sb=Superblock(), source="real", ok=False, have=())
+
+
+class Xv6Bridge:
+    """The live provider (talks HTTP to the in-container agent)."""
+
+    def __init__(self, agent: AgentClient, quantum: int = 1) -> None:
+        self.agent = agent
+        self.timeslice = int(quantum)
+        self.policy = "round-robin"
+        self.vm = _VmReader(agent)
+        self.fs = _FsReader(agent)
+        self._seq = 0
+        self._last_cpu = None       # register/stack detail (from gdb) — reused between fast reads
+        self._last_stack: list = []
+        self.kernel_quantum = None  # the kernel's ACTUAL sched_quantum (from the SCHED line)
+        self.kernel_policy = None   # the kernel's ACTUAL sched_policy id (from the SCHED line)
+        self.kernel_policies = {}   # {id: name} roster (POLICY lines) — drives the UI selector
+
+    def snapshot(self) -> Snapshot:
+        """The Run/observe read: gini_dump() over the serial gives BOTH the process table AND
+        the running process's live registers in one shot — FAST and NO halt, so scheduling keeps
+        running and registers (sp/satp change per process!) update live. The kernel stack (bt)
+        still needs gdb, so it's only refreshed on Step; here we reuse the last one."""
+        self._seq += 1
+        txt = self.agent.get_text("/procs")
+        procs = apply_proc_sched(parse_procdump(txt), txt)   # procs + priority/tickets/level/aging
+        sched = parse_sched(txt)                     # the kernel's ACTUAL quantum + policy
+        if sched:
+            self.kernel_quantum = sched.get("quantum")
+            self.kernel_policy = sched.get("policy")
+        roster = parse_policies(txt)                  # {id: name}; drives the UI policy selector
+        if roster:
+            self.kernel_policies = roster
+        cpu = parse_regs_line(txt)                  # live registers from the same no-halt dump
+        if cpu.regs:
+            self._last_cpu = cpu
+        else:
+            cpu = self._last_cpu                     # CPU idle / no REGS line -> keep last
+        return Snapshot(procs=procs, running_pid=running_pid(procs), ticks=self._seq,
+                        cpu=cpu, stack=self._last_stack, cpus=parse_cpu_lines(txt),
+                        cpu_regs=parse_cpu_regs(txt),
+                        modetime=parse_modetime(txt), csr=parse_csr(txt))
+
+    def _detail_snapshot(self) -> Snapshot:
+        """A full gdb read (halts the guest briefly): registers + kernel stack + a proc walk.
+        Used on open and on Step, where a momentary halt is expected."""
+        d = self.agent.get_json("/snapshot")
+        self._last_cpu = parse_registers(d.get("registers", ""))
+        self._last_stack = parse_backtrace(d.get("bt", ""))
+        procs = parse_procdump(d.get("procs", ""))
+        return Snapshot(procs=procs, running_pid=running_pid(procs), ticks=self._seq,
+                        cpu=self._last_cpu, stack=self._last_stack)
+
+    def step(self) -> Snapshot:
+        self.agent.post("/step")
+        self._seq += 1
+        return self._detail_snapshot()              # halted at swtch -> full frozen detail
+
+    def set_timeslice(self, ticks: int) -> None:
+        self.timeslice = int(ticks)
+        self.agent.post(f"/control?quantum={int(ticks)}")
+
+    def set_policy(self, policy: str) -> None:
+        self.policy = policy
+        # map the display name -> id via the live kernel roster (so a NEW policy works), falling
+        # back to the built-in ids for the shipped three.
+        by_name = {name: pid for pid, name in self.kernel_policies.items()}
+        pid = by_name.get(policy, POLICY_ID.get(policy, 0))
+        self.agent.post(f"/control?policy={pid}")
+
+    # -- shadows + control-plane operations (NOT system calls) --------------------- #
+    def shadows(self) -> dict:
+        """The shadow manifest -> {name: ShadowStatus}: which student shadows are present, enabled,
+        active, and fault-free. The liveness signal the assignment oracle checks first."""
+        return parse_shadow_manifest(self.agent.get_text("/shadows"))
+
+    def set_shadow(self, name: str, on: bool) -> None:
+        """Enable/disable a shadow. The kernel only knows how to toggle the CURRENT policy's shadow,
+        so we make that policy active, then toggle iff its state doesn't already match — all the
+        naming/targeting logic lives here (testable) and the kernel stays dumb."""
+        idx = SHADOW_POLICY.get(name)
+        if idx is None:
+            return
+        self.agent.post(f"/control?policy={idx}")            # make that policy active
+        cur = self.shadows().get(name)
+        if cur is None or bool(cur.enabled) != bool(on):
+            self.agent.post("/shadow/toggle")                # flip the current policy's shadow
+
+    def set_priority(self, pid: int, value: int) -> None:
+        """Control-plane op (not a syscall): set a process's scheduling priority so the workload
+        has real differences to schedule on."""
+        self.agent.post(f"/control/priority?pid={int(pid)}&v={int(value)}")
+
+    def set_tickets(self, pid: int, n: int) -> None:
+        """Control-plane op (not a syscall): set a process's lottery ticket count."""
+        self.agent.post(f"/control/tickets?pid={int(pid)}&n={int(n)}")
+
+    def load(self) -> tuple[bool, str]:
+        """The Load loop: rebuild the kernel in the container (incremental make) and restart QEMU
+        with the new kernel. Returns (ok, log) — log carries compile errors scoped to the student's
+        shadow file on failure."""
+        try:
+            d = json.loads(self.agent.post("/rebuild"))
+            return bool(d.get("ok")), str(d.get("log", ""))
+        except Exception as e:
+            return False, f"load failed: {e}"
+
+    def revert(self) -> tuple[bool, str]:
+        """Restore the shipped stub shadow and rebuild — one click back to a known-good kernel."""
+        try:
+            d = json.loads(self.agent.post("/revert"))
+            return bool(d.get("ok")), str(d.get("log", ""))
+        except Exception as e:
+            return False, f"revert failed: {e}"
+
+    # -- programs (launch / kill / console) via the in-container agent's serial ---- #
+    def programs(self) -> list:
+        return self.agent.get_json("/programs").get("programs", [])
+
+    def run(self, prog: str) -> bool:
+        try:
+            return bool(json.loads(self.agent.post(f"/run?prog={prog}")).get("ok"))
+        except Exception:
+            return False
+
+    def kill(self, pid: int) -> None:
+        self.agent.post(f"/kill?pid={int(pid)}")
+
+    def sc(self) -> str:
+        """Raw gini_scdump text (SC counts + TRACE ring) for the histogram + strace panels."""
+        return self.agent.get_text("/sc")
+
+    def traps(self) -> str:
+        """Raw gini_trapdump text (TC per-kind counters + TR trap ring) for the Traps face."""
+        return self.agent.get_text("/traps")
+
+    def catch_trap(self, kind: str = "any"):
+        """Freeze the next live user trap (gdb /trapcatch) and parse it into a TrapFrame — the
+        real scause/sepc/stval + saved user registers that seed the CPU journey. `kind` conditions
+        the breakpoint (pagefault/syscall/timer/illegal/device). Returns a not-ok TrapFrame on
+        timeout/idle, so the journey falls back to its authored captions."""
+        from ..domain.xv6 import parse_trapframe
+        raw = self.agent.post(f"/trapcatch?kind={kind}")
+        txt = ""
+        try:
+            txt = json.loads(raw).get("out", "")
+        except Exception:
+            txt = raw or ""
+        return parse_trapframe(txt)
+
+    def alarms(self) -> str:
+        """Raw gini_dump text (contains the per-proc `ALARM …` lines) for the sigalarm-lab strip."""
+        return self.agent.get_text("/procs")
+
+    def console(self) -> str:
+        return self.agent.get_text("/console")
+
+    def console_since(self, since: int = 0) -> tuple[str, int]:
+        """Append-only console delta for the Terminal: (new text after `since`, new cursor). The
+        Terminal keeps the cursor and appends, so output streams in instead of re-rendering."""
+        d = self.agent.get_json(f"/console/stream?since={int(since)}")
+        return d.get("text", ""), int(d.get("next", since))
+
+    def clear_console(self) -> None:
+        """Blank the Screen: tell the agent to move its console baseline to 'now', so the tail
+        starts fresh (the kernel keeps running; this only affects what the console view shows)."""
+        self.agent.post("/console/clear")
+
+    def send_input(self, text: str) -> None:
+        self.agent.post("/input", body=text)
+
+    def interrupt(self) -> None:
+        """Break a hung foreground program (xv6 has no Ctrl-C/SIGINT). Sends the kernel's break
+        control-char over the serial; the console driver handles it directly (not sh), so it works
+        even while a foreground process has the shell blocked in wait()."""
+        self.agent.post("/interrupt")
+
+
+def connect(agent_port: int, host: str = "127.0.0.1", quantum: int = 1) -> Xv6Bridge:
+    """Build a live bridge to a running gini-xv6 container's agent (published `agent_port`)."""
+    return Xv6Bridge(AgentClient(f"http://{host}:{agent_port}"), quantum=quantum)

gini/server/__init__.py

@@ -0,0 +1,22 @@
+"""GINI server — an authenticated broker in front of Docker/Kata.
+
+Students never get a Docker socket or SSH. gBuilder sends a *topology* (the device/link
+model, not a compose file) to this server, which runs on the Kata host; the server compiles
+it with GINI's own trusted compiler, enforces policy (allowed images, Kata/runc runtimes
+only, no privileged or host mounts, per-student resource caps + namespacing), and runs it.
+The constrained API is the only surface students can reach — Docker never sees a
+student-supplied command.
+
+Pieces:
+  * auth.py    — flat user file (PBKDF2 hashes) + HMAC-signed session tokens.
+  * policy.py  — validate/sanitize a compiled RuntimeConfig before it can run.
+  * session.py — per-student project name + workdir (multi-tenant isolation).
+  * app.py     — the request router (GiniServer.handle) + a stdlib HTTP wrapper.
+"""
+from .app import GiniServer
+from .auth import Tokens, UserStore, hash_password
+from .policy import PolicyError, enforce
+from .session import SessionManager
+
+__all__ = ["GiniServer", "UserStore", "Tokens", "hash_password",
+           "PolicyError", "enforce", "SessionManager"]

gini/server/__main__.py

@@ -0,0 +1,74 @@
+"""Run the GINI server, or manage its flat user file.
+
+    python -m gini.server adduser  users.json  s_jane
+    python -m gini.server run  --users users.json  --base ./gini-labs  --port 10000
+
+The server secret comes from $GINI_SERVER_SECRET (else a random one each start, which just
+invalidates old tokens on restart — fine for a class).
+"""
+from __future__ import annotations
+
+import getpass
+import json
+import os
+import sys
+from pathlib import Path
+
+
+def _adduser(argv: list[str]) -> int:
+    if len(argv) < 2:
+        print("usage: adduser <userfile> <username>")
+        return 2
+    from .auth import hash_password
+    path, user = Path(argv[0]), argv[1]
+    users = json.loads(path.read_text()) if path.exists() else {}
+    users[user] = hash_password(getpass.getpass(f"password for {user}: "))
+    path.write_text(json.dumps(users, indent=2))
+    print(f"saved {user} to {path}")
+    return 0
+
+
+def _run(argv: list[str]) -> int:
+    import argparse
+    ap = argparse.ArgumentParser(prog="gini.server run")
+    ap.add_argument("--users", default="users.json")
+    ap.add_argument("--base", default="./gini-labs")
+    ap.add_argument("--host", default="0.0.0.0")
+    ap.add_argument("--port", type=int, default=10000)
+    ap.add_argument("--max-cpus", type=float, default=2.0)
+    a = ap.parse_args(argv)
+
+    from .. import runtime as _rt
+    from ..services.orchestrator import Orchestrator
+    from .app import GiniServer, serve
+    from .auth import Tokens, UserStore
+    from .session import SessionManager
+
+    runtime_dir = Path(_rt.__file__).parent
+    secret = os.environ.get("GINI_SERVER_SECRET", os.urandom(32).hex()).encode()
+
+    def factory(project: str, workdir):
+        return Orchestrator(runtime_dir, project=project)
+
+    srv = GiniServer(UserStore.from_file(a.users), Tokens(secret),
+                     SessionManager(a.base), factory, max_cpus=a.max_cpus)
+    serve(srv, a.host, a.port)
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if not argv:
+        print("usage: python -m gini.server {run|adduser} ...")
+        return 2
+    cmd, rest = argv[0], argv[1:]
+    if cmd == "adduser":
+        return _adduser(rest)
+    if cmd == "run":
+        return _run(rest)
+    print(f"unknown command: {cmd}")
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())