"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",

"ask_agent": "auto", # auto | claude | codex | gemini | devin: who writes `?` / `sd ask` commands

"ask_model": "", # that agent's model; empty = its smallest

"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

"""This browser's grant on the running share: from an opened link, or an allowed grant for a trusted device."""

if not _share:

return None

if (cookie := conn.cookies.get(SHARE_COOKIE)) and (g := _share["grants"].get(_sha(cookie))):

return g

if not (token := conn.cookies.get(DEVICE_COOKIE)) or not (d := db.trusted_device(_sha(token))):

return None

key = f"device:{d['id']}"

if key not in _share["grants"]: # once per share

db.touch_trusted_device(d["id"])

_share["grants"][key] = {"id": d["id"], "ip": _client(conn), "agent": d["name"], "at": time.time(), "state": "ok", "session": None}

"""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 asyncio.to_thread(plugins.load, _plugins_off())

await sched.start()

sched.set_alarm_callback(_broadcast_alarm)

await sched.reminder_service.sync_all()

global manager

if addr := os.environ.get(ptyhost.ADDR_ENV): # under the supervisor: the shells live in sd-pty

manager = ptyhost.PtyClient(addr, os.environ.pop(ptyhost.TOKEN_ENV, ""))

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

await manager.connect(_host_terminal, _host_lost)

else:

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())

updates = asyncio.create_task(_watch_updates())

# 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()

updates.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()

if not isinstance(manager, ptyhost.PtyClient): # sd-pty keeps its shells; the supervisor stops it

manager.save()

for sid in list(manager.procs):

"""A terminal already running in sd-pty when this UI started (an update restarted it): pump it again."""

if token := manager.env.get(sid, {}).get("SHELLDECK_AGENT_REPORT_TOKEN"):

report_tokens[sid] = token

if sid not in readers:

if not STOPPING.is_set():

log.error("lost the pty host; asking the supervisor for a full restart")

logging.shutdown()

# 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 _via_share(request): # browsers then never use plain http to the tunnel host (cookies, password)

response.headers["Strict-Transport-Security"] = "max-age=31536000"

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])

"""Is a newer shelldeck out? how: 'ota' (this standalone install updates in place) or 'uv' (uv tool upgrade)."""

try:

info = await asyncio.to_thread(update.check, VERSION, force)

except (OSError, ValueError, KeyError) as e:

log.warning("update check failed: %s", e)

return err("update_check_failed", 503)

# in place needs the supervisor: only then do the shells outlive a restart of this process

"""Install the latest standalone release next to this one and restart sd-ui from it; the shells keep running."""

if not _host(request):

return err("host_only", 403)

if not isinstance(manager, ptyhost.PtyClient):

return err("not_supervised", 409)

try:

new = await asyncio.to_thread(update.apply, VERSION)

except (OSError, ValueError, KeyError, RuntimeError) as e:

log.warning("update failed: %s", e)

return JSONResponse({"error": "update_failed", "detail": str(e)}, status_code=500)

log.info("updated to %s; restarting the UI", new)

_restart_ui()

"""Host only: restart sd-ui (new code, same shells)."""

if not _host(request):

return err("host_only", 403)

if not isinstance(manager, ptyhost.PtyClient):

return err("not_supervised", 409)

_restart_ui()

"""Tell host browsers once per new version (the page offers Update, or the upgrade command)."""

told = ""

while True:

await asyncio.sleep(60)

try:

info = await asyncio.to_thread(update.check, VERSION)

except (OSError, ValueError, KeyError):

info = {}

if info.get("available") and info["latest"] != told:

told = info["latest"]

await _broadcast({"type": "update", **info, "in_place": info["how"] == "ota" and isinstance(manager, ptyhost.PtyClient)}, host_only=True)

"""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

app = request.headers.get(CLIENT_HEADER, "").lower() == "ios" or APP_AGENT in request.headers.get("user-agent", "")

# ponytail: "app" is only a claim, so a LAN browser could fake it; it still needs the password, and remote only skips takeover

remote = app and (g["state"] == "ok" if g else not _via_share(request) and not _is_local(request))

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="/",

# through the tunnel sd-ui sees http (cloudflared -> loopback), but the browser is on https

secure=request.url.scheme == "https" or _via_share(request), 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"]:

# the fragment never leaves the scanning device: the app pins the end-to-end key from it (e2e.py)

url = f"https://{host}/share/{token}#k={e2e.public()}"

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]

return [{"id": g["id"], "ip": g["ip"], "agent": g["agent"], "at": g["at"], "code": g.get("code")}

"""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)

_spawn(_announce(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()

"""Trusted devices learn the new share URL now, and again every REPEAT_S while this share runs."""

while _share.get("host") == host:

if devices := db.list_trusted_devices():

await asyncio.to_thread(relay.publish, devices, f"https://{host}")

"""The iOS app, logged in (over the LAN or an approved share), makes itself a trusted device. The token,

if not auth.remote(request.state.session):

return err("app_only", 403)

token = secrets.token_urlsafe(32)

topic, key = relay.new_device()

d = db.add_trusted_device(str((payload or {}).get("name") or "iPhone"), _sha(token), topic, key)

log.info("trusted device %s (%s) added from %s", d["id"], d["name"], _client(request))

await _broadcast({"type": "trusted", "device": {"id": d["id"], "name": d["name"]}}, host_only=True)

if _share.get("host"):

await asyncio.to_thread(relay.publish, [d], f"https://{_share['host']}")

return {"id": d["id"], "token": token, "topic": topic, "key": key, "relay": relay.NTFY, "cookie": DEVICE_COOKIE,

"""Untrust a device (not from the tunnel). Its logins through the share end too."""

if _via_share(request):

return err("host_only", 403)

if not db.delete_trusted_device(device_id):

return err("not_found", 404)

if g := _share.get("grants", {}).pop(f"device:{device_id}", None):

await _revoke([g["session"]] if g["session"] else [])

"""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 waiting page's poll: pending, ok, denied, or none."""

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

body = {"state": g["state"] if g else "none"}

if g and g["state"] == "pending":

body["code"] = g.get("code") # only this browser's own code: the host compares it before allowing

"""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,

# shown on the device and next to Allow: whoever saw the QR and opened it first gets a different code

"code": f"{secrets.randbelow(10000):04d}",

}

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", ""))