"default_shell": shells.default_kind(),

"wsl_distro": "",

"font_size": "13",

"theme": "dark",

"layout_mode": "tiled",

"project_tint": "on",

"terminal_theme": "default",

"font_family": "",

"editor": "vscode",

"agent_resume": "ask",

"recall_agent": "off", # off | auto | claude | codex | gemini | devin: whose small model widens `sd recall --smart` # never | ask | auto: start a stored agent session again when its terminal comes back

"""Same-origin check. Browsers always send Origin cross-site; the CLI sends none.

headers = conn.headers

host = headers.get("host", "")

if _via_share(conn):

g = _grant(conn)

if not (conn.url.path.startswith("/share/") or (g and g["state"] == "ok")):

return False

elif ALLOWED_HOSTS is not None and host.rsplit(":", 1)[0] not in ALLOWED_HOSTS:

return False

origin = headers.get("origin")

if not iso:

return None

try:

return datetime.fromisoformat(iso).astimezone(timezone.utc).isoformat()

except ValueError:

s = {k: db.get_setting(k, v) for k, v in SETTINGS_DEFAULTS.items()}

if s["default_shell"] not in shells.kinds(): # e.g. a Windows db opened on Linux

s["default_shell"] = shells.default_kind()

STOPPING.clear()

db.init_db()

if code := auth.init_auth():

log.warning("no password yet; remote setup code: %s", code)

await sched.start()

sched.set_alarm_callback(_broadcast_alarm)

await sched.reminder_service.sync_all()

manager.store = db.config_dir() / "scrollback"

manager.prune({s["id"] for s in db.list_sessions()})

saver = asyncio.create_task(_save_scrollback())

asker = asyncio.create_task(_watch_questions())

watcher = asyncio.create_task(_watch_share())

agent_watch = asyncio.create_task(_watch_agents())

# every start refreshes the shelldeck skill of each agent CLI on PATH (dev/test homes skip it);

# `sd install-skill --remove` turns this off

if "SHELLDECK_HOME" not in os.environ and db.get_setting("agent_skills", "on") == "on":

try:

await asyncio.to_thread(team.install)

except OSError:

log.warning("installing agent skills failed", exc_info=True)

log.info("shelldeck %s started", VERSION)

yield

saver.cancel()

asker.cancel()

watcher.cancel()

agent_watch.cancel()

STOPPING.set()

if _share:

await asyncio.to_thread(share.stop)

_share.clear()

stats.stop()

sched.shutdown()

for task in list(readers.values()):

task.cancel()

manager.save()

for sid in list(manager.procs):

# ponytail: periodic flush; a hard power-off loses at most the last 15s of output

while True:

await asyncio.sleep(15)

try:

await asyncio.to_thread(manager.save)

except OSError:

"""Tell host browsers when the link or a pending device expires (every other change says so itself)."""

while True:

await asyncio.sleep(5)

if _share and _share_key(_share_state()) != _share_sent["key"]:

"""Browsers must revalidate (a cheap 304), or they keep running old JS after an upgrade."""

def file_response(self, *args, **kwargs):

response = super().file_response(*args, **kwargs)

response.headers["Cache-Control"] = "no-cache"

"""("cli", None) for the host CLI, ("browser", session hash) for a login, else None."""

if auth.cli_ok(conn.headers.get(auth.TOKEN_HEADER)):

return ("cli", None)

h = auth.session_hash(conn.cookies.get(auth.COOKIE))

"""True when browser session `h` may act: it is the active one, or no live session is.

if auth.remote(h):

return True

if _active["h"] != h and auth.alive(_active["h"]):

return False

_active["h"] = h

"X-Frame-Options": "DENY",

"Content-Security-Policy": "frame-ancestors 'none'",

"X-Content-Type-Options": "nosniff",

"Referrer-Policy": "no-referrer",

response = await _guarded(request, call_next)

response.headers.update(SECURITY_HEADERS)

if request.url.path.startswith("/api/"):

response.headers["Cache-Control"] = "no-store" # terminal output, history, devices

if not _trusted(request):

return err("forbidden_origin", 403)

path = request.url.path

request.state.session = None

# an integration inside a terminal (hook script, OpenCode plugin) holds only its terminal's report token;

# agent_report() checks it. Host-local only: never through a share tunnel or the network.

report_only = path == "/api/agent-reports" and request.method == "POST" and REPORT_HEADER in request.headers and _is_local(request)

if path.startswith("/api/") and not path.startswith(AUTH_EXEMPT) and not report_only:

who = _who(request)

if not who:

return _denied()

request.state.session = who[1]

if who[1] and not _claim(who[1]):

return err("in_use", 423)

if who[1] and request.method != "GET": # polling GETs are not activity

auth.touch(who[1])

"""Start a login session (cookie on `res`, JSON body by default). It becomes the active device:

if old := auth.session_hash(request.cookies.get(auth.COOKIE)):

auth.end_session(old)

g = _grant(request) if _via_share(request) else None

remote = bool(g and g["state"] == "ok" and request.headers.get(CLIENT_HEADER, "").lower() == "ios")

token = auth.new_session(f"{_client(request)} {request.headers.get('user-agent', '')}", _via(request),

"remote" if remote else "browser")

h = auth.session_hash(token)

if g:

g["session"] = h # revoking this login also voids the grant

if not remote:

_active["h"] = h

await _close_session_sockets(lambda owner: owner != h and not auth.remote(owner), IN_USE)

res = res or JSONResponse(body)

res.set_cookie(

auth.COOKIE, token, httponly=True, samesite="strict", path="/",

secure=request.url.scheme == "https", max_age=30 * 24 * 3600,

)

wait = auth.blocked_for(_client(request))

if wait:

return JSONResponse({"error": "too_many_attempts", "retry_after": wait}, status_code=429, headers={"Retry-After": str(wait)})

who = _who(request)

if who and who[1]:

auth.touch(who[1])

return {

"has_password": auth.has_password(),

"setup_code_required": not auth.has_password() and not _is_local(request),

"authenticated": bool(who),

"in_use_elsewhere": bool(who and who[1] and not auth.remote(who[1]) and who[1] != _active["h"] and auth.alive(_active["h"])),

"idle_timeout": auth.LOCK_TIMEOUT_SECONDS,

"min_length": auth.MIN_PASSWORD,

"""First run: create the password. Remote clients also need the code printed on the host."""

if auth.has_password():

return err("password_already_set", 409)

if blocked := _too_many(request):

return blocked

if not _is_local(request):

ok = hmac.compare_digest(str(payload.get("code", "")).strip().lower(), (auth.setup_code() or "").lower())

auth.record_attempt(_client(request), ok)

if not ok:

return err("invalid_setup_code", 403)

password, confirm = str(payload.get("password", "")), str(payload.get("confirm", ""))

if problem := auth.validate_new(password, confirm):

return err(problem)

auth.set_password(password)

log.info("password created from %s", _client(request))

if not auth.has_password():

return err("setup_required", 401)

if blocked := _too_many(request):

return blocked

ok = await asyncio.to_thread(auth.check_password, str(payload.get("password", "")))

auth.record_attempt(_client(request), ok)

if not ok:

log.warning("failed login from %s", _client(request))

return err("invalid_password", 401)

"""Host CLI only: a one-time URL that logs a browser in (emergency unlock)."""

if not auth.cli_ok(request.headers.get(auth.TOKEN_HEADER)):

return err("host_cli_only", 403)

code = secrets.token_urlsafe(24)

_login_links[code] = time.time() + 300

"""ShareState (see plans/ios-app.md, API contract)."""

host, token = _share.get("host"), _share.get("token")

link = None

if token and time.time() < _share["link_until"]:

url = f"https://{host}/share/{token}"

link = {"path": f"/share/{token}", "url": url, "expires_at": int(_share["link_until"]), "qr_svg": _qr(url)}

return {

"sharing": bool(_share), "starting": _share_lock.locked(), "url": f"https://{host}" if host else None,

"link": link, "pending": _pending(), "strong_password": auth.strong_password(), "cloudflared": bool(share.command()),

"terms_accepted": auth.terms_accepted(share.TERMS_VERSION), "terms": share.TERMS,

"""Every host browser gets the new ShareState."""

state = _share_state()

_share_sent["key"] = _share_key(state)

"""Devices waiting for the host; stale ones are dropped."""

grants, now = _share.get("grants", {}), time.time()

for k in [k for k, g in grants.items() if g["state"] == "pending" and now - g["at"] > APPROVAL_TTL]:

del grants[k]

"""Host only: start the tunnel (or return the running share) with a fresh link."""

if not _host(request):

return err("host_only", 403)

if not auth.strong_password():

return err("weak_password", 409)

if not auth.terms_accepted(share.TERMS_VERSION):

return err("terms_required", 409)

if not share.command():

return JSONResponse({"error": "no_cloudflared", "hint": share.HINT}, status_code=404)

problem = None

async with _share_lock:

if not _share:

await _share_changed() # starting

loop = asyncio.get_running_loop()

def exited(host: str) -> None: # cloudflared's reader thread

loop.call_soon_threadsafe(_spawn, _tunnel_exited(host))

try:

host = await asyncio.to_thread(share.start, SELF_URL["url"], exited)

_share.update(host=host, grants={})

_new_share_link()

log.info("sharing via %s", host)

except TimeoutError:

problem = err("tunnel_timeout", 504)

except (OSError, RuntimeError):

log.warning("cloudflared failed to start", exc_info=True)

problem = err("tunnel_failed", 502)

await _share_changed()

"""Host only: ShareState."""

if not _host(request):

return err("host_only", 403)

"""Host only: accept the share terms (asked once, again when TERMS_VERSION changes)."""

if not _host(request):

return err("host_only", 403)

if payload.get("accept") is not True:

return err("accept_required")

auth.accept_terms(share.TERMS_VERSION)

"""Host only: a fresh link for another device on the running share."""

if not _host(request):

return err("host_only", 403)

if not _share:

return err("not_sharing", 404)

_new_share_link()

await _share_changed()

"""Allow or deny a device that opened a link: the host CLI, or any logged-in browser not on the tunnel."""

if _via_share(request):

return err("host_only", 403)

_pending()

g = next((g for g in _share.get("grants", {}).values() if g["id"] == payload.get("id")), None)

if not g or g["state"] != "pending":

return err("not_found", 404)

g["state"] = "ok" if payload.get("allow") is True else "denied"

log.info("share device %s from %s %s", g["id"], g["ip"], "allowed" if g["state"] == "ok" else "denied")

await _share_changed()

if not _host(request):

return err("host_only", 403)

await _share_stop()

"""Stop the tunnel and sign out every browser that logged in through it."""

if not _share:

return

gone = db.delete_auth_sessions_via(f"share:{_share['host']}")

_share.clear()

await asyncio.to_thread(share.stop)

await _revoke(gone)

"""The QR link: works once, within LINK_TTL. It makes a pending grant that the host must allow (in a host

if not _via_share(request):

return err("link_expired", 403)

if g := _grant(request): # this browser already opened a link (e.g. a reload)

return RedirectResponse("/", status_code=303) if g["state"] == "ok" else _share_page(_WAIT_PAGE)

if not _share_link_ok(token):

return _share_page(_WAIT_PAGE.replace("poll();", 'say("This link has expired or was already used.", "Ask the host for a new one.");'), 403)

_share["token"] = None # one use

cookie = secrets.token_urlsafe(32)

_share["grants"][_sha(cookie)] = {

"id": secrets.token_hex(4), "ip": _client(request), "agent": request.headers.get("user-agent", "")[:200],

"at": time.time(), "state": "pending", "session": None,

}

log.info("share link opened from %s; waiting for the host", _client(request))

await _share_changed()

res = _share_page(_WAIT_PAGE)

res.set_cookie(SHARE_COOKIE, cookie, httponly=True, samesite="lax", secure=True, path="/", max_age=24 * 3600)

expiry = _login_links.pop(code, 0)

if expiry < time.time() or not auth.has_password():

return err("link_expired", 403)

"""Lock this browser: end its session and close its sockets."""

h = auth.session_hash(request.cookies.get(auth.COOKIE))

if h:

auth.end_session(h)

await _close_session_sockets(lambda owner: owner == h)

res = JSONResponse({"status": "locked"})

res.delete_cookie(auth.COOKIE, path="/")

"""Browsers signed in: where from, when, and which one is in use."""

online: dict[str, int] = {}

for owner in socket_owner.values():

if owner:

online[owner] = online.get(owner, 0) + 1

rows = []

for r in db.list_auth_sessions():

h = r["token_hash"]

if not auth.alive(h):

continue

ip, _, agent = (r["client"] or "").partition(" ")

rows.append({

"id": h, "ip": ip, "agent": agent, "via": r["via"] or "local", "kind": r["kind"] or "browser",

"created_at": r["created_at"], "last_seen": r["last_seen"],

"active": h == _active["h"], "current": h == request.state.session, "sockets": online.get(h, 0),

})

on = _share_on()

"""Sign one browser out, or with id "others" every browser but this one."""

if device_id == "others":

return await _revoke([d["token_hash"] for d in db.list_auth_sessions() if d["token_hash"] != request.state.session])

grants = _share.get("grants", {})

for k in [k for k, g in grants.items() if g["session"] in hashes]:

del grants[k] # a revoked share device needs a new link and approval

db.delete_push_tokens(hashes)

for h in hashes:

auth.end_session(h)

if _active["h"] == h:

_active["h"] = None

await _close_session_sockets(lambda owner: owner in hashes)

"""Change the password (logged-in browser only). Signs out every other browser."""

h = auth.session_hash(request.cookies.get(auth.COOKIE))

if not h:

return _denied()

if blocked := _too_many(request):

return blocked

ok = await asyncio.to_thread(auth.check_password, str(payload.get("current", "")))

auth.record_attempt(_client(request), ok)

if not ok:

return err("wrong_current_password", 403)

password, confirm = str(payload.get("password", "")), str(payload.get("confirm", ""))

if problem := auth.validate_new(password, confirm):

return err(problem)

auth.set_password(password)

auth.end_other_sessions(keep=h)

await _close_session_sockets(lambda owner: owner != h)

log.info("password changed from %s", _client(request))

for key, value in payload.items():

if key not in SETTINGS_DEFAULTS:

return err(f"unknown_setting:{key}")

value = str(value).strip()

if key == "default_shell" and value not in shells.kinds():

return err("invalid_shell")

if key == "font_size" and not (value.isdigit() and 8 <= int(value) <= 32):

return err("invalid_font_size")

if key == "theme" and value not in ("dark", "light", "system"):

return err("invalid_theme")

if key == "layout_mode" and value not in ("tiled", "free"):

return err("invalid_layout_mode")

if key == "project_tint" and value not in ("on", "off"):

return err("invalid_project_tint")

if key == "terminal_theme" and value not in TERMINAL_THEMES:

return err("invalid_terminal_theme")

if key == "font_family" and not FONT_FAMILY.fullmatch(value):

return err("invalid_font_family")

if key == "editor" and value not in ("vscode", "system", "shelldeck"):

return err("invalid_editor")

if key == "agent_resume" and value not in ("never", "ask", "auto"):

return err("invalid_agent_resume")

if key == "recall_agent" and value not in ("off", "auto", *smart_recall.PRIORITY):

return err("invalid_recall_agent")

for key, value in payload.items():

db.set_setting(key, str(value).strip())

"""The processes running in one terminal (below its shell), for sd ps."""

proc = manager.get(session_id)

if not proc or not proc.isalive():

return err("not_running", 409)

"""End a process inside one terminal (and its children): terminate, then kill after 3s; `force` kills at once.

proc = manager.get(session_id)

if not proc or not proc.isalive():

return err("not_running", 409)

result = await asyncio.to_thread(stats.end, proc.pid, pid, bool((payload or {}).get("force")))

if result in ("not_in_terminal", "gone"):

return err(result, 404)

log.info("process %s in %s %s", pid, session_id, result)

"""Known AI coding agents (installed or not, with their models) and the terminals running one."""

shells = _shell_pids()

found = await asyncio.to_thread(agents.running, shells)

by_id = {s["id"]: s for s in db.list_sessions_with_project()}

running = [

{"session_id": sid, "name": s.get("name"), "nick": s.get("nick"), "parent": s.get("parent"), "project_id": s.get("project_id"), "project": s.get("project_name"),

"cwd": s.get("cwd"), "agent": key, "label": agents.AGENTS[key][0], "model": model, "state": agent_state.get(sid, "idle"),

"status": agent_status.get(sid) or lifecycle.to_dict(lifecycle.Status(lifecycle.State.UNKNOWN)),

"resumable": bool(db.get_agent_session(sid))}

for sid, (key, model) in found.items() if (s := by_id.get(sid))

]

return {

"agents": await asyncio.to_thread(agents.catalog),

"running": running,

"outside": await asyncio.to_thread(agents.outside, _tree_pids(shells)),

"devin_sessions": await asyncio.to_thread(agents.devin_sessions),

"""Install shelldeck's lifecycle hook/plugin into an agent's config (host only: it writes files in your home)."""

if not _host(request):

return err("host_only", 403)

try:

out = await asyncio.to_thread(integrations.install, agent)

_emit("integration.changed", {"agent": agent, "status": out["status"]})

return out

except KeyError:

return err("unsupported_agent", 404)

except (OSError, ValueError) as e:

if not _host(request):

return err("host_only", 403)

try:

out = await asyncio.to_thread(integrations.uninstall, agent)

_emit("integration.changed", {"agent": agent, "status": out["status"]})

return out

except KeyError:

return err("unsupported_agent", 404)

except (OSError, ValueError) as e:

"""Every pid under a shelldeck shell (so `outside` skips them)."""

pids = set(shells.values())

for pid in shells.values():

try:

pids.update(p.pid for p in psutil.Process(pid).children(recursive=True))

except psutil.Error:

continue

return {

"kinds": shells.kinds(),

"labels": {k: shells.label(k) for k in shells.kinds()},

"default": shells.default_kind(),

"available": shells.available(),

"wsl_distros": await asyncio.to_thread(shells.wsl_distros),

"""Changed files in a project's work tree for the sidebar, cached; None when git fails."""

at, n = _git_counts.get(path, (0, None))

if time.monotonic() - at < GIT_COUNT_S:

return n

_git_counts[path] = (time.monotonic(), n) # one check at a time