chore: refactor server structure

.github/workflows/real-e2e.yml

@@ -7,7 +7,7 @@ on:
   pull_request:
     branches: [ main ]
     paths:
-      - 'server/src/**'
+      - 'server/opensandbox_server/**'
       - 'components/execd/**'
       - 'components/egress/**'
       - 'sdks/code-interpreter/**'
@@ -92,7 +92,7 @@ jobs:
         run: |
           docker ps -aq --filter "label=opensandbox" | xargs -r docker rm -f || true
           docker run --rm -v /tmp:/host_tmp alpine rm -rf /host_tmp/opensandbox-e2e || true
-          pkill -f "python -m src.main" || true
+          pkill -f "python -m opensandbox_server.main" || true
 
   java-e2e:
     name: Java E2E (docker bridge)
@@ -184,7 +184,7 @@ jobs:
         run: |
           docker ps -aq --filter "label=opensandbox" | xargs -r docker rm -f || true
           docker run --rm -v /tmp:/host_tmp alpine rm -rf /host_tmp/opensandbox-e2e || true
-          pkill -f "python -m src.main" || true
+          pkill -f "python -m opensandbox_server.main" || true
 
   javascript-e2e:
     name: JavaScript E2E (docker bridge)
@@ -277,7 +277,7 @@ jobs:
         run: |
           docker ps -aq --filter "label=opensandbox" | xargs -r docker rm -f || true
           docker run --rm -v /tmp:/host_tmp alpine rm -rf /host_tmp/opensandbox-e2e || true
-          pkill -f "python -m src.main" || true
+          pkill -f "python -m opensandbox_server.main" || true
 
   csharp-e2e:
     name: C# E2E (docker bridge)
@@ -359,4 +359,4 @@ jobs:
         run: |
           docker ps -aq --filter "label=opensandbox" | xargs -r docker rm -f || true
           docker run --rm -v /tmp:/host_tmp alpine rm -rf /host_tmp/opensandbox-e2e || true
-          pkill -f "python -m src.main" || true
+          pkill -f "python -m opensandbox_server.main" || true

.github/workflows/server-test.yml

@@ -4,7 +4,7 @@ on:
   pull_request:
     branches: [ main ]
     paths:
-      - 'server/src/**'
+      - 'server/opensandbox_server/**'
       - 'server/tests/**'
 
 permissions:
@@ -91,7 +91,7 @@ jobs:
           EOF
 
           # Start server in background
-          uv run python -m src.main > app.log 2>&1 &
+          uv run python -m opensandbox_server.main > app.log 2>&1 &
 
           # Wait for server to start
           sleep 10

AGENTS.md

@@ -13,8 +13,8 @@
 ## Build, Test, and Development Commands
 - Server (Python):
   - `cd server && uv sync` installs deps.
-  - `cp server/example.config.toml ~/.sandbox.toml` sets local config.
-  - `cd server && uv run python -m src.main` runs the API server.
+  - `cp server/opensandbox_server/examples/example.config.toml ~/.sandbox.toml` sets local config.
+  - `cd server && uv run python -m opensandbox_server.main` runs the API server.
 - execd (Go):
   - `cd components/execd && go build -o bin/execd .` builds the daemon.
   - `cd components/execd && make fmt` formats Go sources.

CONTRIBUTING.md

@@ -73,15 +73,15 @@ cd server
 # Install dependencies
 uv sync
 
-# Copy example configuration
-cp example.config.toml ~/.sandbox.toml
+# Copy example configuration from the source tree
+cp server/opensandbox_server/examples/example.config.toml ~/.sandbox.toml
 
 # Edit configuration for development
 # Set log_level = "DEBUG" and api_key
 nano ~/.sandbox.toml
 
 # Run server
-uv run python -m src.main
+uv run python -m opensandbox_server.main
 ```
 
 See [server/DEVELOPMENT.md](server/DEVELOPMENT.md) for detailed server development guide.

README.md

@@ -79,8 +79,8 @@ opensandbox-server init-config ~/.sandbox.toml --example docker
 > git clone https://github.com/alibaba/OpenSandbox.git
 > cd OpenSandbox/server
 > uv sync
-> cp example.config.toml ~/.sandbox.toml # Copy configuration file
-> uv run python -m src.main # Start the service
+> cp opensandbox_server/examples/example.config.toml ~/.sandbox.toml # Copy configuration file from the source tree
+> uv run python -m opensandbox_server.main # Start the service
 > ```
 
 #### 2. Start the Sandbox Server

docs/README_zh.md

@@ -73,8 +73,8 @@ opensandbox-server init-config ~/.sandbox.toml --example docker-zh
 > git clone https://github.com/alibaba/OpenSandbox.git
 > cd OpenSandbox/server
 > uv sync
-> cp example.config.toml ~/.sandbox.toml # Copy configuration file
-> uv run python -m src.main # Start the service
+> cp opensandbox_server/examples/example.config.zh.toml ~/.sandbox.toml # 从源码目录复制配置文件
+> uv run python -m opensandbox_server.main # Start the service
 > ```
 
 #### 2. 启动沙箱 Server

docs/manual-cleanup-refactor-guide.md

@@ -85,7 +85,7 @@ TTL is currently mandatory.
 
 Relevant files:
 
-- `server/src/api/schema.py`
+- `server/opensandbox_server/api/schema.py`
 - `specs/sandbox-lifecycle.yml`
 
 Current constraints:
@@ -99,7 +99,7 @@ Current constraints:
 
 Relevant file:
 
-- `server/src/services/docker.py`
+- `server/opensandbox_server/services/docker.py`
 
 Current behavior:
 
@@ -113,9 +113,9 @@ Current behavior:
 
 Relevant files:
 
-- `server/src/services/k8s/kubernetes_service.py`
-- `server/src/services/k8s/batchsandbox_provider.py`
-- `server/src/services/k8s/agent_sandbox_provider.py`
+- `server/opensandbox_server/services/k8s/kubernetes_service.py`
+- `server/opensandbox_server/services/k8s/batchsandbox_provider.py`
+- `server/opensandbox_server/services/k8s/agent_sandbox_provider.py`
 
 Current behavior:
 
@@ -197,7 +197,7 @@ Recommended error message:
 
 Files to update:
 
-- `server/src/api/schema.py`
+- `server/opensandbox_server/api/schema.py`
 - `specs/sandbox-lifecycle.yml`
 
 Required changes:
@@ -217,7 +217,7 @@ Recommended validation rule:
 
 File to update:
 
-- `server/src/services/docker.py`
+- `server/opensandbox_server/services/docker.py`
 
 ### Target behavior
 
@@ -302,10 +302,10 @@ Target logic:
 
 Files to update:
 
-- `server/src/services/k8s/kubernetes_service.py`
-- `server/src/services/k8s/workload_provider.py`
-- `server/src/services/k8s/batchsandbox_provider.py`
-- `server/src/services/k8s/agent_sandbox_provider.py`
+- `server/opensandbox_server/services/k8s/kubernetes_service.py`
+- `server/opensandbox_server/services/k8s/workload_provider.py`
+- `server/opensandbox_server/services/k8s/batchsandbox_provider.py`
+- `server/opensandbox_server/services/k8s/agent_sandbox_provider.py`
 
 ### Key risk
 
@@ -378,8 +378,8 @@ If not supported by the CRD:
 
 Files likely affected:
 
-- `server/src/services/sandbox_service.py`
-- `server/src/services/k8s/workload_provider.py`
+- `server/opensandbox_server/services/sandbox_service.py`
+- `server/opensandbox_server/services/k8s/workload_provider.py`
 
 Required updates:
 
@@ -500,7 +500,7 @@ Follow-up checks:
 
 ## Suggested Implementation Order
 
-1. Update schema models in `server/src/api/schema.py`
+1. Update schema models in `server/opensandbox_server/api/schema.py`
 2. Update OpenAPI spec in `specs/sandbox-lifecycle.yml`
 3. Refactor Docker runtime to support `expires_at: Optional[datetime]`
 4. Add Kubernetes provider capability plumbing

examples/host-volume-mount/README.md

@@ -17,8 +17,8 @@ This example demonstrates how to mount host directories into sandbox containers
 ```shell
 git clone git@github.com:alibaba/OpenSandbox.git
 cd OpenSandbox/server
-cp example.config.toml ~/.sandbox.toml
-uv sync && uv run python -m src.main
+cp opensandbox_server/examples/example.config.toml ~/.sandbox.toml
+uv sync && uv run python -m opensandbox_server.main
 ```
 
 ### 2. Configure Allowed Host Paths

examples/host-volume-mount/README_zh.md

@@ -17,8 +17,8 @@
 ```shell
 git clone git@github.com:alibaba/OpenSandbox.git
 cd OpenSandbox/server
-cp example.config.zh.toml ~/.sandbox.toml
-uv sync && uv run python -m src.main
+cp opensandbox_server/examples/example.config.zh.toml ~/.sandbox.toml
+uv sync && uv run python -m opensandbox_server.main
 ```
 
 ### 2. 配置允许的宿主机路径

oseps/0001-fqdn-based-egress-control.md

@@ -1118,17 +1118,17 @@ The key insight is that `CAP_NET_ADMIN` grants permission to modify network conf
 
 #### 1. Server (`server/`)
 
-**`server/src/api/schema.py`**: Add `NetworkPolicy` schema classes.
+**`server/opensandbox_server/api/schema.py`**: Add `NetworkPolicy` schema classes.
 
-**`server/src/services/docker.py`** (sidecar pattern):
+**`server/opensandbox_server/services/docker.py`** (sidecar pattern):
 - Create an egress sidecar container when `network_policy` is present.
 - Add `CAP_NET_ADMIN` only to the sidecar.
 - Set `OPENSANDBOX_EGRESS_TOKEN` env (random per-sandbox) and optionally `OPENSANDBOX_EGRESS_HTTP_ADDR`.
 - Run the application container with `network_mode: "container:<sidecar>"` (shared netns), no extra caps.
 - Wait for sidecar `/healthz` 200, then POST `networkPolicy` to `/policy` with header `OPENSANDBOX-EGRESS-AUTH: <token>`.
 - Reject `--network host` when `network_policy` is set (hostNetwork not supported).
 
-**`server/src/services/k8s/batchsandbox_provider.py`** (Pod pattern):
+**`server/opensandbox_server/services/k8s/batchsandbox_provider.py`** (Pod pattern):
 - Pod spec includes `egress-sidecar` with `capabilities.add: [NET_ADMIN]` and the application container without extra caps.
 - Sidecar env includes `OPENSANDBOX_EGRESS_TOKEN` (and `OPENSANDBOX_EGRESS_HTTP_ADDR` if non-default); may optionally seed `OPENSANDBOX_EGRESS_RULES`.
 - Server (inside cluster) waits for `/healthz` on the Pod IP, then POSTs `networkPolicy` to `/policy` with header `OPENSANDBOX-EGRESS-AUTH`.

oseps/0004-secure-container-runtime.md

@@ -559,7 +559,7 @@ def validate_secure_runtime_on_startup(config: AppConfig, docker_client=None, k8
 
 ### Docker Mode Implementation
 
-Changes to `server/src/services/docker.py`. The runtime is read from server config, not from the request:
+Changes to `server/opensandbox_server/services/docker.py`. The runtime is read from server config, not from the request:
 
 ```python
 class DockerSandboxService(SandboxService):
@@ -585,7 +585,7 @@ Both Kubernetes workload providers inject `runtimeClassName` from server config.
 
 #### BatchSandboxProvider
 
-Changes to `server/src/services/k8s/batchsandbox_provider.py`:
+Changes to `server/opensandbox_server/services/k8s/batchsandbox_provider.py`:
 
 - **CRD**: `sandbox.opensandbox.io/v1alpha1` BatchSandbox
 - **Pod spec path**: `spec.template.spec`
@@ -608,7 +608,7 @@ class BatchSandboxProvider:
 
 #### AgentSandboxProvider
 
-Changes to `server/src/services/k8s/agent_sandbox_provider.py`:
+Changes to `server/opensandbox_server/services/k8s/agent_sandbox_provider.py`:
 
 - **CRD**: `agents.x-k8s.io/v1alpha1` Sandbox
 - **Pod spec path**: `spec.podTemplate.spec`

oseps/0006-developer-console.md

@@ -49,8 +49,8 @@ OIDC JWT validation, PostgreSQL RBAC bindings, and durable audit logs.
 
 Today OpenSandbox exposes lifecycle APIs and Swagger docs, but developers/operators still need to manage sandbox resources via APIs. This creates friction for common workflows (search/create/renew/delete), weakens governance in multi-user environments, and raises onboarding cost for teams that are not API-first.
 
-- Server auth today is global API key only (`server/src/middleware/auth.py` with `OPEN-SANDBOX-API-KEY`).
-- Lifecycle operations already exist and are stable (`server/src/api/lifecycle.py`, `specs/sandbox-lifecycle.yml`).
+- Server auth today is global API key only (`server/opensandbox_server/middleware/auth.py` with `OPEN-SANDBOX-API-KEY`).
+- Lifecycle operations already exist and are stable (`server/opensandbox_server/api/lifecycle.py`, `specs/sandbox-lifecycle.yml`).
 - Filtering by state/metadata already exists (`GET /sandboxes` and `matches_filter`).
 - Sandbox metadata already maps to labels in Docker/Kubernetes services and is returned in list/get responses.
 
@@ -152,9 +152,9 @@ flowchart LR
 
 Quick summary of the relevant server code as it stands today:
 
-- Auth middleware: API key only (`server/src/middleware/auth.py`, header `OPEN-SANDBOX-API-KEY`).
-- Lifecycle routes: `server/src/api/lifecycle.py`.
-- Service implementations: `server/src/services/docker.py` (Docker), `server/src/services/k8s/kubernetes_service.py` (Kubernetes).
+- Auth middleware: API key only (`server/opensandbox_server/middleware/auth.py`, header `OPEN-SANDBOX-API-KEY`).
+- Lifecycle routes: `server/opensandbox_server/api/lifecycle.py`.
+- Service implementations: `server/opensandbox_server/services/docker.py` (Docker), `server/opensandbox_server/services/k8s/kubernetes_service.py` (Kubernetes).
 - Filtering: `state` and `metadata` filters in route parsing, `matches_filter` helper.
 - Metadata: already stored as Docker/Kubernetes labels.
 
@@ -219,7 +219,7 @@ Canonicalization:
 
 #### 1. Configuration
 
-Extend `server/src/config.py` with auth/authz sections.
+Extend `server/opensandbox_server/config.py` with auth/authz sections.
 
 `auth.mode` controls high-level authentication behavior:
 
@@ -274,7 +274,7 @@ jwks_url = "https://www.googleapis.com/oauth2/v3/certs"
 
 #### 2. Authentication Middleware
 
-Changes to `server/src/middleware/auth.py`:
+Changes to `server/opensandbox_server/middleware/auth.py`:
 
 1. Preserve current API key path exactly.
 2. Add user principal extraction path (phase-gated by config).
@@ -284,12 +284,12 @@ Changes to `server/src/middleware/auth.py`:
 
 #### 3. Authorization Enforcement
 
-New module `server/src/middleware/authorization.py` with a single entry point:
+New module `server/opensandbox_server/middleware/authorization.py` with a single entry point:
 
 - `authorize_action(principal, action, sandbox=None)`.
 - Scope checks for owner/team.
 
-Integrate into `server/src/api/lifecycle.py` per route before invoking mutating service operations.
+Integrate into `server/opensandbox_server/api/lifecycle.py` per route before invoking mutating service operations.
 
 For list operations:
 Apply server-side scope filter in addition to client-provided filters.

oseps/0007-fast-sandbox-runtime-support.md

@@ -572,7 +572,7 @@ To handle these cases, fast-sandbox provides a **Node Janitor DaemonSet** that r
 
 ### Configuration Extension
 
-Add `FastSandboxRuntimeConfig` to `server/src/config.py`:
+Add `FastSandboxRuntimeConfig` to `server/opensandbox_server/config.py`:
 
 ```python
 class FastSandboxRuntimeConfig(BaseModel):
@@ -627,7 +627,7 @@ execd_port = 44772
 ### New Code Structure
 
 ```
-server/src/services/k8s/
+server/opensandbox_server/services/k8s/
 ├── fastsandbox_provider.py      # New: FastSandboxProvider WorkloadProvider implementation
 ├── fastsandbox_client.py        # New: gRPC client wrapper for fast-sandbox Controller
 ├── provider_factory.py          # Modified: Register "fast-sandbox" provider

scripts/csharp-e2e.sh

@@ -45,7 +45,7 @@ echo "-------- CSHARP E2E test logs for execd --------" > /tmp/opensandbox-e2e/l
 # setup server
 cd server
 : > server.log
-(uv sync && uv run python -m src.main) > server.log 2>&1 &
+(uv sync && uv run python -m opensandbox_server.main) > server.log 2>&1 &
 cd ..
 
 # wait for server

scripts/java-e2e.sh

@@ -45,7 +45,7 @@ echo "-------- JAVA E2E test logs for execd --------" > /tmp/opensandbox-e2e/log
 
 # setup server
 cd server
-uv sync && uv run python -m src.main > server.log 2>&1 &
+uv sync && uv run python -m opensandbox_server.main > server.log 2>&1 &
 cd ..
 
 # wait for server

scripts/javascript-e2e.sh

@@ -45,7 +45,7 @@ echo "-------- JAVASCRIPT E2E test logs for execd --------" > /tmp/opensandbox-e
 
 # setup server
 cd server
-uv sync && uv run python -m src.main > server.log 2>&1 &
+uv sync && uv run python -m opensandbox_server.main > server.log 2>&1 &
 cd ..
 
 # wait for server
@@ -69,4 +69,3 @@ export OPENSANDBOX_TEST_API_KEY=""
 export OPENSANDBOX_SANDBOX_DEFAULT_IMAGE="opensandbox/code-interpreter:${TAG}"
 
 pnpm test:ci
-

scripts/python-e2e.sh

@@ -49,7 +49,7 @@ echo "-------- PYTHON E2E test logs for execd --------" > /tmp/opensandbox-e2e/l
 
 # setup server
 cd server
-uv sync && uv run python -m src.main > server.log 2>&1 &
+uv sync && uv run python -m opensandbox_server.main > server.log 2>&1 &
 cd ..
 
 # wait for server