agent-framework-lib 0.8.8__tar.gz → 0.8.8.post3__tar.gz

{agent_framework_lib-0.8.8/agent_framework_lib.egg-info → agent_framework_lib-0.8.8.post3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-framework-lib
-Version: 0.8.8
+Version: 0.8.8.post3
 Summary: A comprehensive Python framework for building and serving conversational AI agents with FastAPI
 Author-email: Sebastian Pavel <sebastian@cinco.ai>, Elliott Girard <elliott.girard@icloud.com>
 Maintainer-email: Sebastian Pavel <sebastian@cinco.ai>

{agent_framework_lib-0.8.8 → agent_framework_lib-0.8.8.post3}/agent_framework/security/authz.py

@@ -55,6 +55,36 @@ def auth_required() -> bool:
     return not dev_mode_enabled()
 
 
+def trust_client_user_id() -> bool:
+    """Le déployeur fait confiance au client pour fournir le ``user_id``.
+
+    Activé via ``AUTH_TRUST_CLIENT_USER_ID``. Cas d'usage : un backend de
+    confiance authentifié par API key (un portail) qui multiplexe plusieurs
+    end-users et passe leur ``user_id`` en paramètre. Quand actif, le serveur
+    HONORE le ``user_id`` client (au lieu de le forcer au principal authentifié),
+    et ``is_owner`` autorise ce principal de confiance sur toute ressource —
+    l'auth (API key) reste exigée, mais le contrôle par end-user est délégué au
+    portail.
+
+    ⚠️ N'activer QUE si le client est de confiance et applique lui-même le
+    contrôle d'accès par end-user — sinon tout détenteur de la clé peut réclamer
+    n'importe quel ``user_id``.
+    """
+    return _env_flag("AUTH_TRUST_CLIENT_USER_ID")
+
+
+def resolve_effective_user_id(current_user: str, requested_user_id: str | None) -> str:
+    """Identité effective pour scoper sessions/fichiers.
+
+    Honore le ``user_id`` client quand l'auth est désactivée (dev mode) OU que le
+    déployeur fait confiance au client (``AUTH_TRUST_CLIENT_USER_ID``). Sinon, lie
+    au principal authentifié (anti-usurpation multi-tenant).
+    """
+    if requested_user_id and (not auth_required() or trust_client_user_id()):
+        return requested_user_id
+    return current_user
+
+
 def is_owner(resource_user_id: str | None, principal: str) -> bool:
     """Vérifie que ``principal`` possède la ressource.
 
@@ -64,14 +94,17 @@ def is_owner(resource_user_id: str | None, principal: str) -> bool:
         principal: Identité authentifiée demandant l'accès.
 
     Returns:
-        ``True`` si le principal possède la ressource, ou si le mode
-        développement est actif et que le principal est ``"anonymous"``
-        (compat mono-utilisateur).
+        ``True`` si le principal possède la ressource, si le mode développement
+        est actif et que le principal est ``"anonymous"`` (compat mono-utilisateur),
+        ou si le client est de confiance (``AUTH_TRUST_CLIENT_USER_ID`` — le portail
+        de confiance peut accéder aux ressources de n'importe quel end-user).
     """
     if resource_user_id is not None and resource_user_id == principal:
         return True
     if dev_mode_enabled() and principal == ANONYMOUS_PRINCIPAL:
         return True
+    if trust_client_user_id():
+        return True
     return False
 
 

{agent_framework_lib-0.8.8 → agent_framework_lib-0.8.8.post3}/agent_framework/security/sandbox_provider.py

@@ -474,12 +474,23 @@ class OpenShellProvider(SandboxProvider):
         src = f"{SANDBOX_OUTPUT}/{_safe_name(out_subdir)}" if out_subdir else SANDBOX_OUTPUT
         # Source dir may not exist if the command wrote nothing — tolerate failure.
         proc = self._run_cli(["sandbox", "download", name, src, dest_dir], timeout=120)
+        # Visibility: this PULL is the only file-delivery path in the sandboxed
+        # topology, so its outcome must be observable (was DEBUG → silent file loss).
+        try:
+            pulled = sum(len(files) for _, _, files in os.walk(dest_dir))
+        except OSError:
+            pulled = -1
         if proc.returncode != 0:
-            logger.debug(
-                "openshell download (no output?) for %s: %s",
+            logger.warning(
+                "[sandbox] download failed for %s (src=%s) rc=%s — generated files "
+                "may be lost: %s",
                 name,
-                (proc.stdout + proc.stderr).strip()[:200],
+                src,
+                proc.returncode,
+                (proc.stdout + proc.stderr).strip()[:300],
             )
+        else:
+            logger.info("[sandbox] pulled %d file(s) from %s for %s", pulled, src, name)
         # Best-effort: remove the per-command subdir so a long-lived session does
         # not accumulate output slices in /sandbox/output.
         if out_subdir:

{agent_framework_lib-0.8.8 → agent_framework_lib-0.8.8.post3}/agent_framework/tools/shell_tool.py

@@ -754,6 +754,15 @@ class ShellTool(AgentTool):
         )
         env["AGENT_HOST"] = callback_host
         env["AGENT_PORT"] = str(callback_port)
+        # In the per-session sandbox the in-shell HTTP upload is the WRONG path:
+        # the sandbox is a sibling container with no reliable route back to the
+        # agent (in Coolify the agent port is not published — host.docker.internal
+        # :8000 is NOT the agent → 401/wrong server). The skill therefore only
+        # WRITES its file to AGENT_OUTPUT_DIR; the parent ShellTool finalizer pulls
+        # it out via the gateway (collect_out) and registers it to the agent itself
+        # (localhost) with the session token. Forcing skip also prevents the skill
+        # from printing a file_id that would make the finalizer skip the file.
+        env["AGENT_SKILL_SKIP_HTTP_UPLOAD"] = "true"
         # Tell upload scripts whether to authenticate.
         env["REQUIRE_AUTH"] = os.environ.get("REQUIRE_AUTH", "false")
         # Scoped, short-lived session token (HMAC, user/session) so the sandbox
@@ -846,8 +855,20 @@ class ShellTool(AgentTool):
                 )
                 return out
 
-            with contextlib.suppress(Exception):
+            # Pull the files the sandbox produced out via the gateway. This is the
+            # ONLY delivery path in the sandboxed topology (the sandbox itself has
+            # no route to register them). Failures here = lost files, so they MUST
+            # be visible (previously swallowed silently → undiagnosable file loss).
+            try:
                 provider.collect_out(session_id, collect_dir, out_subdir=out_subdir)
+            except Exception as e:  # noqa: BLE001 — never raise into the agent
+                logger.warning(
+                    "[ShellTool] collect_out failed (session=%s, out_subdir=%s) — "
+                    "generated files may not be delivered: %s",
+                    session_id,
+                    out_subdir,
+                    e,
+                )
 
             stdout = result.stdout or ""
             stderr = result.stderr or ""

{agent_framework_lib-0.8.8 → agent_framework_lib-0.8.8.post3}/agent_framework/web/server.py

@@ -193,6 +193,7 @@ from ..security.authz import (
     OutboundURLValidationError,
     auth_required,
     is_owner,
+    resolve_effective_user_id,
     validate_outbound_url,
 )
 from ..security.file_view_token import verify_file_token
@@ -667,6 +668,30 @@ async def _load_session_or_raise(storage: Any, user_id: str, session_id: str) ->
     return session_data
 
 
+def _matches_status_filter(
+    metadata: dict[str, Any] | None, include_closed: bool, only_closed: bool
+) -> bool:
+    """Decide whether a session matches the requested open/closed filter.
+
+    A session is considered closed when ``metadata.status == "closed"``; any
+    other value (including a missing status) is treated as open.
+
+    Args:
+        metadata: Session metadata dict (may be None).
+        include_closed: Return both open and closed sessions.
+        only_closed: Return only closed sessions (takes precedence).
+
+    Returns:
+        True if the session should be included in the result.
+    """
+    is_closed = (metadata or {}).get("status") == "closed"
+    if only_closed:
+        return is_closed
+    if include_closed:
+        return True
+    return not is_closed
+
+
 # Pydantic model for incoming messages, now uses content list
 class MessageRequest(BaseModel):
     # This model directly mirrors StructuredAgentInput for the request body
@@ -2306,7 +2331,7 @@ async def handle_message_endpoint(
     # mismatch that made uploaded files 404 on download. In dev-mode (auth
     # disabled) the query param is honored for single-user compatibility.
     # Mirrors /files/upload (see effective_user_id there).
-    user_id = current_user if auth_required() else user_id
+    user_id = resolve_effective_user_id(current_user, user_id)
 
     # Determine session_id: query param > body.session_id > new UUID
     session_id_from_query = request.query_params.get("session_id")
@@ -2720,7 +2745,7 @@ async def handle_stream_endpoint(
     # user_id query param — bind the session (and every file it stores) to the
     # authenticated principal. In dev-mode (auth disabled) the query param is
     # honored for single-user compatibility. Mirrors /files/upload.
-    user_id = current_user if auth_required() else user_id
+    user_id = resolve_effective_user_id(current_user, user_id)
 
     # Support both /sessions/{session_id}/stream and /stream?session_id=...
     # If session_id is not provided as a path parameter, try to get it from query/body
@@ -4055,14 +4080,27 @@ async def list_sessions_endpoint(
     user_id: str = Query(
         DEFAULT_USER_ID, description="Identifier for the user whose sessions to list"
     ),
+    include_closed: bool = Query(
+        False,
+        description="When true, return both open and closed sessions instead of open only.",
+    ),
+    only_closed: bool = Query(
+        False,
+        description="When true, return only closed sessions. Takes precedence over include_closed.",
+    ),
     current_user: str = Depends(get_current_user),
 ):
-    """Lists all active session IDs for a given user_id, filtered by current agent ID."""
+    """Lists session IDs for a given user_id, filtered by current agent ID.
+
+    By default only open sessions (status != "closed") are returned. Use
+    ``only_closed=true`` to list only closed sessions, or ``include_closed=true``
+    to list both open and closed sessions.
+    """
     global session_storage
 
     # Multi-tenant: under auth, list only the authenticated principal's sessions
     # (ignore client user_id). Keeps the UI consistent with /message + /stream.
-    user_id = current_user if auth_required() else user_id
+    user_id = resolve_effective_user_id(current_user, user_id)
 
     if not session_storage:
         raise HTTPException(status_code=500, detail="Session storage not available")
@@ -4073,13 +4111,20 @@ async def list_sessions_endpoint(
         agent_identity = StateManager.create_agent_identity(temp_agent)
         current_agent_id = agent_identity.agent_id
 
-        # Use agent-filtered session retrieval by agent_id (not agent_type)
-        user_sessions = await session_storage.get_user_sessions_by_agent(
-            user_id, agent_id=current_agent_id
-        )
+        # Use session info (includes metadata.status) so we can filter by status.
+        # Already sorted by updated_at desc across all backends.
+        sessions_info = await session_storage.list_user_sessions_with_info(user_id)
+
+        user_sessions = [
+            info["session_id"]
+            for info in sessions_info
+            if info.get("agent_id") == current_agent_id
+            and _matches_status_filter(info.get("metadata"), include_closed, only_closed)
+        ]
+
         # An empty list during a storage outage would look like "no sessions".
         # Surface the outage as 503 instead so the client can retry.
-        if not user_sessions and not await session_storage.is_available():
+        if not sessions_info and not await session_storage.is_available():
             raise HTTPException(
                 status_code=503,
                 detail=STORAGE_UNAVAILABLE_DETAIL,
@@ -4107,7 +4152,7 @@ async def list_sessions_with_info_endpoint(
 
     # Multi-tenant: under auth, list only the authenticated principal's sessions
     # (ignore client user_id). Keeps the UI consistent with /message + /stream.
-    user_id = current_user if auth_required() else user_id
+    user_id = resolve_effective_user_id(current_user, user_id)
 
     if not session_storage:
         raise HTTPException(status_code=500, detail="Session storage not available")
@@ -4212,7 +4257,7 @@ async def cancel_execution_endpoint(
 
     # Multi-tenant: under auth, only the authenticated principal may cancel their
     # own session (ignore client user_id). Matches /message + /stream ownership.
-    user_id = current_user if auth_required() else user_id
+    user_id = resolve_effective_user_id(current_user, user_id)
 
     if not session_storage:
         raise HTTPException(status_code=500, detail="Session storage not available")
@@ -4288,7 +4333,7 @@ async def get_execution_state_endpoint(
 
     # Multi-tenant: under auth, scope to the authenticated principal (ignore
     # client user_id) so ownership matches /message + /stream.
-    user_id = current_user if auth_required() else user_id
+    user_id = resolve_effective_user_id(current_user, user_id)
 
     if not session_storage:
         raise HTTPException(status_code=500, detail="Session storage not available")
@@ -4379,7 +4424,7 @@ async def get_history_endpoint(
     # Multi-tenant: under auth, scope reads to the authenticated principal and
     # ignore the client-supplied user_id. Mirrors the write side (/message,
     # /stream) so sessions created there are visible to the same UI identity.
-    user_id = current_user if auth_required() else user_id
+    user_id = resolve_effective_user_id(current_user, user_id)
 
     if not session_storage:
         raise HTTPException(status_code=500, detail="Session storage not available")
@@ -5015,7 +5060,7 @@ async def get_code_delivery_config_endpoint(
     # The client-provided user_id query param is only honored in dev-mode to
     # preserve single-user/finalizer compatibility (cannot be used to read or
     # mutate another user's code-delivery config when auth is enabled).
-    effective_user_id = current_user if auth_required() else user_id
+    effective_user_id = resolve_effective_user_id(current_user, user_id)
 
     resolved = await get_shared_store().resolve(effective_user_id, session_id)
     meta = resolved.github_auth
@@ -5059,7 +5104,7 @@ async def set_code_delivery_github_auth_endpoint(
     )
     # Storage identity bound to the authenticated principal (query param honored
     # only in dev-mode) so a user cannot store a token under another identity.
-    effective_user_id = current_user if auth_required() else user_id
+    effective_user_id = resolve_effective_user_id(current_user, user_id)
     try:
         await get_shared_store().set_github_token(
             effective_user_id, body.token, meta, session_id=body.session_id
@@ -5084,7 +5129,7 @@ async def delete_code_delivery_github_auth_endpoint(
     from agent_framework.code_delivery.store import get_shared_store
 
     # Storage identity bound to the authenticated principal (dev-mode honors the query param).
-    effective_user_id = current_user if auth_required() else user_id
+    effective_user_id = resolve_effective_user_id(current_user, user_id)
     await get_shared_store().clear_github_token(effective_user_id, session_id=session_id)
     return {"success": True, "scope": "session" if session_id else "user"}
 
@@ -5099,7 +5144,7 @@ async def get_code_delivery_repos_endpoint(
     from agent_framework.code_delivery.store import get_shared_store
 
     # Storage identity bound to the authenticated principal (dev-mode honors the query param).
-    effective_user_id = current_user if auth_required() else user_id
+    effective_user_id = resolve_effective_user_id(current_user, user_id)
     resolved = await get_shared_store().resolve(effective_user_id, session_id)
     return {"repos": [r.model_dump() for r in resolved.repos]}
 
@@ -5116,7 +5161,7 @@ async def set_code_delivery_repos_endpoint(
 
     repos = [RepoEntry(**r.model_dump()) for r in body.repos]
     # Storage identity bound to the authenticated principal (dev-mode honors the query param).
-    effective_user_id = current_user if auth_required() else user_id
+    effective_user_id = resolve_effective_user_id(current_user, user_id)
     await get_shared_store().set_repos(effective_user_id, repos, session_id=body.session_id)
     return {"success": True, "count": len(repos)}
 
@@ -5167,7 +5212,7 @@ async def set_code_delivery_herdr_endpoint(
     if body.mode not in ("local", "remote"):
         raise HTTPException(status_code=400, detail="mode must be 'local' or 'remote'")
     # Storage identity bound to the authenticated principal (dev-mode honors the query param).
-    effective_user_id = current_user if auth_required() else user_id
+    effective_user_id = resolve_effective_user_id(current_user, user_id)
     fields: dict[str, Any] = {"mode": body.mode}
     if body.base_url is not None:
         # SSRF / token-exfiltration guard before persistence or use.
@@ -5200,7 +5245,7 @@ async def set_code_delivery_settings_endpoint(
             model=body.backend_model or "claude-sonnet-4-20250514",
         )
     # Storage identity bound to the authenticated principal (dev-mode honors the query param).
-    effective_user_id = current_user if auth_required() else user_id
+    effective_user_id = resolve_effective_user_id(current_user, user_id)
     await get_shared_store().set_settings(
         effective_user_id,
         enabled=body.enabled,
@@ -5273,7 +5318,7 @@ async def upload_file(
         # spoofing another user's ownership. In dev-mode the query param is
         # honored (passive finalizer uploads via localhost using the
         # AGENT_USER_ID wiring), preserving single-user compatibility.
-        effective_user_id = current_user if auth_required() else user_id
+        effective_user_id = resolve_effective_user_id(current_user, user_id)
 
         file_id = await app.state.file_storage_manager.store_file(
             content=content,
@@ -5621,7 +5666,7 @@ async def list_files(
     # Multi-tenant: under auth, list only the authenticated principal's files
     # (ignore the client user_id) so the UI sees the files uploaded by skills,
     # which are owned by the same principal. Mirrors /files/upload + download.
-    user_id = current_user if auth_required() else user_id
+    user_id = resolve_effective_user_id(current_user, user_id)
     try:
         logger.info(
             f"🔍 FILES ENDPOINT - Parameters: user_id={user_id}, session_id={session_id}, is_generated={is_generated}"
@@ -6929,7 +6974,7 @@ async def get_session_response_times_endpoint(
     # Multi-tenant: under auth, scope to the authenticated principal (ignore the
     # client user_id) so the ownership check below matches sessions created by
     # /message and /stream under the same identity.
-    user_id = current_user if auth_required() else user_id
+    user_id = resolve_effective_user_id(current_user, user_id)
 
     if session_storage is None:
         raise HTTPException(status_code=500, detail="Session storage not available")

{agent_framework_lib-0.8.8 → agent_framework_lib-0.8.8.post3/agent_framework_lib.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-framework-lib
-Version: 0.8.8
+Version: 0.8.8.post3
 Summary: A comprehensive Python framework for building and serving conversational AI agents with FastAPI
 Author-email: Sebastian Pavel <sebastian@cinco.ai>, Elliott Girard <elliott.girard@icloud.com>
 Maintainer-email: Sebastian Pavel <sebastian@cinco.ai>

{agent_framework_lib-0.8.8 → agent_framework_lib-0.8.8.post3}/agent_framework_lib.egg-info/SOURCES.txt

@@ -296,6 +296,7 @@ docs/MEMORY_INSTALLATION.md
 docs/MODIFICATIONS_CONCURRENCE.md
 docs/MULTIMODAL_TOOLS_GUIDE.md
 docs/OBSERVABILITY_GUIDE.md
+docs/OPENSHELL_GATEWAY_HOST_SETUP.md
 docs/PYPI_PUBLISHING.md
 docs/QA_STREAMING_LATENCY.md
 docs/SCREENSHOTS_GUIDE.md

agent_framework_lib-0.8.8.post3/docs/OPENSHELL_GATEWAY_HOST_SETUP.md

@@ -0,0 +1,195 @@
+# OpenShell sandbox — host gateway setup (Docker deployments)
+
+How to run the per-session OpenShell sandbox when the agent is deployed in a
+**Docker container** (docker-compose, Coolify, plain `docker run`, …) on a Linux
+host. This is the configuration that makes `shell_exec` run untrusted code in an
+isolated sandbox in production — without it the shell silently degrades to the
+**local path with no FS/network jail**.
+
+## TL;DR — one script per host
+
+On each deployment host (dev, staging, prod), as the user that owns Docker
+(e.g. `ubuntu`):
+
+```bash
+bash scripts/setup-openshell-host.sh
+```
+
+It is idempotent and does everything below (install, JWT keys, config, persistent
+systemd service, smoke test) and prints the exact env vars to set on each agent.
+The rest of this doc explains what it does and how to debug it. The agent
+container side is in the agent `docker-compose.prod.yml` / `openshell-entrypoint.sh`.
+
+## Why the gateway runs on the HOST (not in the agent container)
+
+OpenShell has two parts: the **CLI** (the agent calls it) and the **gateway**
+server, which drives Docker to create the per-session sandbox containers.
+
+On native Linux Docker, the gateway's Docker driver must bind the **Docker
+bridge gateway IP** (e.g. `172.16.x.1`) so the sandbox containers can reach it.
+Only the **host** owns that address — a gateway running *inside* the agent
+container cannot bind it and crashes with:
+
+```
+Error: failed to bind to 172.16.21.1:17670: Cannot assign requested address (os error 99)
+```
+
+(It "just works" on a Mac because Docker Desktop's networking is different.)
+
+So the supported topology on Linux is:
+
+```
+┌─ Host (has Docker) ───────────────────────────────────────────┐
+│  openshell-gateway  (binds 0.0.0.0:17670, drives Docker)       │
+│        ▲                         │ creates                     │
+│        │ http (insecure, LAN)    ▼                             │
+│  ┌─ Agent container ─┐     ┌─ Sandbox containers (per session)─┐│
+│  │ openshell CLI     │     │ jailed; reach the gateway via the ││
+│  │ + docker.sock     │     │ host bridge IP                    ││
+│  └───────────────────┘     └───────────────────────────────────┘│
+└───────────────────────────────────────────────────────────────┘
+```
+
+## 1. Host setup
+
+Prereq: the host runs Docker, and the user that will run the gateway can use it
+**without sudo** (`docker info` works → that user is in the `docker` group). If
+not, one-time: `sudo usermod -aG docker <user>` then re-login. No sudo is needed
+at runtime.
+
+Install the OpenShell CLI + gateway:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh
+```
+
+Write a gateway config. With TLS off there is no mTLS user auth, so we must
+(a) allow unauthenticated callers (the agent CLI), and (b) still give the gateway
+a JWT signing key — **Docker sandboxes require a gateway-minted JWT** to
+authenticate their supervisor back to the gateway, otherwise `sandbox create`
+fails with `docker sandboxes require gateway JWT auth`. The install already
+generated the JWT keys under `~/.local/state/openshell/tls/jwt/`.
+
+```bash
+# JWT signing keys (created by the installer; regenerate if missing):
+ls ~/.local/state/openshell/tls/jwt/ \
+  || openshell-gateway generate-certs --output-dir ~/.local/state/openshell/tls
+
+cat > ~/openshell-gateway.toml <<EOF
+[openshell.gateway.auth]
+allow_unauthenticated_users = true
+
+[openshell.gateway.gateway_jwt]
+signing_key_path = "$HOME/.local/state/openshell/tls/jwt/signing.pem"
+public_key_path = "$HOME/.local/state/openshell/tls/jwt/public.pem"
+kid_path = "$HOME/.local/state/openshell/tls/jwt/kid"
+EOF
+```
+
+Run the gateway with **TLS disabled** (the agent reaches it over the trusted
+internal Docker network), bound to all interfaces, with that config:
+
+```bash
+# the installer's systemd --user service starts with mTLS + 127.0.0.1 and may
+# crash (no certs / no docker group in the unit) — run it ourselves instead:
+systemctl --user stop openshell-gateway 2>/dev/null || true
+pkill -f openshell-gateway 2>/dev/null || true
+
+nohup openshell-gateway --disable-tls --bind-address 0.0.0.0 \
+  --config ~/openshell-gateway.toml >~/openshell-gateway.log 2>&1 &
+disown
+
+ss -ltnp | grep 17670     # expect: LISTEN 0.0.0.0:17670
+```
+
+A healthy log shows three lines: `Unauthenticated user access enabled`,
+`gateway-minted sandbox JWT enabled`, and `Server listening address=0.0.0.0:17670`
+— and it stays up (`Using compute driver driver=docker`).
+
+### Make it permanent (survive logout/reboot)
+
+Override the installed `systemd --user` unit to use the same flags:
+
+```bash
+mkdir -p ~/.config/systemd/user/openshell-gateway.service.d
+cat > ~/.config/systemd/user/openshell-gateway.service.d/override.conf <<'EOF'
+[Service]
+ExecStartPre=
+ExecStart=
+ExecStart=/usr/bin/openshell-gateway --disable-tls --bind-address 0.0.0.0 --config %h/openshell-gateway.toml
+Restart=always
+EOF
+systemctl --user daemon-reload
+systemctl --user restart openshell-gateway
+systemctl --user status openshell-gateway --no-pager
+
+sudo loginctl enable-linger "$USER"   # one-time: keep the user service alive after logout/reboot
+```
+
+If the service still fails on `query Docker daemon version: Connect`, the user
+manager was started before the `docker` group was granted — re-login (or reboot)
+so it picks up the group, then `systemctl --user restart openshell-gateway`.
+
+## 2. Agent container setup (docker-compose)
+
+The agent needs the Docker socket (to build the sandbox image on the host Docker
+and pass the framework's `docker info` check) and the gateway endpoint. See the
+agent compose files for a full example; the OpenShell-relevant parts:
+
+```yaml
+services:
+  agent:
+    environment:
+      - SHELL_SANDBOX_PROVIDER=openshell
+      - OPENSHELL_GATEWAY_ENDPOINT=http://host.docker.internal:17670
+      - OPENSHELL_GATEWAY_INSECURE=true
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+    group_add:
+      - "${DOCKER_GID}"            # host: getent group docker | cut -d: -f3  (or: stat -c %g /var/run/docker.sock)
+    extra_hosts:
+      - "host.docker.internal:host-gateway"   # resolves to the host (Linux)
+    # NO `ports:` under Coolify — its proxy owns the host ports (publishing
+    # 0.0.0.0:<port> here fails with "port is already allocated").
+```
+
+Set `DOCKER_GID` in the deployment env to the host's docker group GID. The agent
+`openshell-entrypoint.sh` ships with the image; it does NOT start a local gateway
+— it just verifies the remote one and starts the agent.
+
+## 3. Validation
+
+Agent boot log should print:
+
+```
+[openshell] using remote gateway http://host.docker.internal:17670
+[openshell] gateway connected — per-session sandbox ACTIVE.
+```
+
+instead of `[sandbox] SECURITY DEGRADED ...`. Then exercise a file-generating
+skill and confirm it runs (the shell is jailed; generated files still land in
+storage via the parent finalizer).
+
+## 4. Security
+
+- The gateway runs with `--disable-tls` and no auth. **Do NOT expose port 17670**
+  beyond the host/VPC — keep it out of the cloud security group / firewall. It is
+  reachable by the agent over the internal Docker network only. Anyone who can
+  reach `:17670` can create sandboxes (i.e. run code) through it.
+- For a hardened multi-host setup, use OpenShell's mTLS gateway (generate certs,
+  distribute the client cert to the agent) or its Helm chart for Kubernetes
+  instead of `--disable-tls`.
+
+## Troubleshooting (errors seen in practice)
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `--tls-cert is required when TLS is enabled` | gateway started with mTLS but no certs | run with `--disable-tls` |
+| `failed to bind to 172.16.x.1:17670: Cannot assign requested address` | gateway running *inside* a container can't bind the bridge IP | run the gateway on the **host** (this doc) |
+| `failed to query Docker daemon version: ... Connect` | the gateway process has no Docker socket access | run as a user in the `docker` group (no sudo at runtime); for the systemd `--user` unit, re-login so it inherits the group |
+| Agent log: `Docker not available` | the agent container can't reach Docker | mount `/var/run/docker.sock` + set `DOCKER_GID` to the host docker group GID |
+| `Bind for 0.0.0.0:<port> failed: port is already allocated` (Coolify) | a `ports:` publish collides with Coolify's proxy | remove `ports:` — Coolify routes the domain via its own proxy |
+| Agent log: `cannot reach …:17670` | gateway down, or `host.docker.internal` doesn't resolve | confirm the host gateway is up (`ss -ltnp | grep 17670`) and `extra_hosts: host.docker.internal:host-gateway` is set |
+| `error: invalid value '1' for '--gateway-insecure'` | `OPENSHELL_GATEWAY_INSECURE` set to `1`/`0` | the value must be `true`/`false` → `OPENSHELL_GATEWAY_INSECURE=true` |
+| `sandbox create failed: ... missing authorization header` | gateway has no auth mechanism, but rejects unauthenticated callers | add `[openshell.gateway.auth] allow_unauthenticated_users = true` to the gateway config |
+| `sandbox create failed: docker sandboxes require gateway JWT auth` | the gateway can't mint the sandbox supervisor's JWT | add `[openshell.gateway.gateway_jwt]` (signing/public/kid paths) to the gateway config |

{agent_framework_lib-0.8.8 → agent_framework_lib-0.8.8.post3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agent-framework-lib"
-version = "0.8.8"
+version = "0.8.8post3"
 description = "A comprehensive Python framework for building and serving conversational AI agents with FastAPI"
 readme = {file = "README.md", content-type = "text/markdown"}
 license = {text = "MIT"}