Merge branch 'feat/terminal-startup-and-container-tools' into dev

apps/api/alembic/versions/2026_05_24_220141_add_startup_command.py

@@ -0,0 +1,30 @@
+"""add startup_command to tool_types
+
+Revision ID: 2026_05_24_220141
+Revises: 6fc7bfcf199f
+Create Date: 2026-05-24 22:01:41.000000
+
+"""
+
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = "2026_05_24_220141"
+down_revision: Union[str, Sequence[str], None] = "6fc7bfcf199f"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "tool_types",
+        sa.Column("startup_command", sa.Text(), nullable=True),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("tool_types", "startup_command")

apps/api/src/api/terminal.py

@@ -9,6 +9,7 @@ from sqlalchemy.ext.asyncio import AsyncSession
 
 from src.auth.dependencies import get_db_session
 from src.models.tool_instance import ToolInstance
+from src.models.tool_type import ToolType
 from src.services.terminal_manager import terminal_manager
 
 router = APIRouter()
@@ -81,11 +82,18 @@ async def terminal_websocket(
 
     logger.info("Terminal auth passed for instance %s, user %s", instance_id, user_id)
 
+    # Fetch tool type to get startup_command
+    tool_type = await db_session.get(ToolType, instance.tool_type_id)
+    startup_command = tool_type.startup_command if tool_type else None
+    if startup_command:
+        logger.info("Using startup command for instance %s: %s", instance_id, startup_command)
+
     # Get or create terminal session
     try:
         session = await terminal_manager.get_or_create_session(
             instance_uuid,
             instance.container_id,
+            startup_command=startup_command,
         )
         logger.info("Terminal session ready for instance %s (session_id=%s)", instance_id, session.session_id)
 
@@ -186,6 +194,7 @@ async def _write_loop(session_ref: SessionRef, websocket, instance_id: str) -> N
                                 new_session = await terminal_manager.reset_session(
                                     session.instance_id,
                                     session.container_id,
+                                    startup_command=session.startup_command,
                                 )
                                 
                                 # Update the mutable session reference so read_loop uses the new session
@@ -259,11 +268,16 @@ async def reset_terminal_session(
             detail="Instance is not running"
         )
 
+    # Fetch tool type to get startup_command
+    tool_type = await db_session.get(ToolType, instance.tool_type_id)
+    startup_command = tool_type.startup_command if tool_type else None
+
     try:
         # Reset the session
         new_session = await terminal_manager.reset_session(
             instance_id,
             instance.container_id,
+            startup_command=startup_command,
         )
         
         logger.info("Terminal session reset for instance %s (new session_id=%s)", instance_id, new_session.session_id)

apps/api/src/api/tool_types.py

@@ -49,6 +49,7 @@ class ToolTypeCreate(BaseModel):
     dockerfile_template: str | None = None
     build_context: dict | None = None
     readiness_probe: dict | None = None
+    startup_command: str | None = None
     required_variables: list[str] = []
     category: str = "other"
     interface_type: str = "web"
@@ -192,6 +193,7 @@ class ToolTypeUpdate(BaseModel):
     dockerfile_template: str | None = None
     build_context: dict | None = None
     readiness_probe: dict | None = None
+    startup_command: str | None = None
     required_variables: list[str] | None = None
     category: str | None = None
     interface_type: str | None = None
@@ -278,6 +280,7 @@ class ToolTypeResponse(BaseModel):
     dockerfile_template: str | None
     build_context: dict | None
     readiness_probe: dict | None
+    startup_command: str | None
     required_variables: list[str]
     created_by_id: uuid.UUID | None
     created_at: datetime
@@ -324,6 +327,7 @@ async def create_tool_type(
         dockerfile_template=data.dockerfile_template,
         build_context=data.build_context,
         readiness_probe=data.readiness_probe,
+        startup_command=data.startup_command,
         required_variables=data.required_variables,
         category=data.category,
         interface_type=data.interface_type,

apps/api/src/models/tool_type.py

@@ -30,6 +30,7 @@ class ToolType(UUIDPrimaryKeyMixin, TimestampMixin, Base):
         JSON, default=dict, nullable=True
     )
     readiness_probe: Mapped[dict | None] = mapped_column(JSON, nullable=True)
+    startup_command: Mapped[str | None] = mapped_column(Text, nullable=True)
     required_variables: Mapped[list[str]] = mapped_column(JSON, default=list, nullable=False)
     created_by_id: Mapped[uuid.UUID | None] = mapped_column(
         UUID(),

apps/api/src/services/terminal_manager.py

@@ -58,6 +58,7 @@ class TerminalManager:
         self,
         instance_id: uuid.UUID,
         container_id: str,
+        startup_command: str | None = None,
     ) -> TerminalSession:
         """Get existing session or create a new one."""
         # Ensure idle check is running (lazy start)
@@ -82,8 +83,8 @@ class TerminalManager:
         # Create new session
         logger.info("Creating new terminal session for instance %s", instance_id)
         session_id = str(uuid.uuid4())
-        session = TerminalSession(session_id, instance_id, container_id)
-        await session.start()
+        session = TerminalSession(session_id, instance_id, container_id, startup_command=startup_command)
+        await session.start(startup_command=startup_command)
         self._sessions[instance_id_str] = session
         
         return session
@@ -127,6 +128,7 @@ class TerminalManager:
         self,
         instance_id: uuid.UUID,
         container_id: str,
+        startup_command: str | None = None,
     ) -> TerminalSession:
         """Reset a session by killing it and creating a new one."""
         instance_id_str = str(instance_id)
@@ -139,8 +141,8 @@ class TerminalManager:
         
         # Create new session
         session_id = str(uuid.uuid4())
-        session = TerminalSession(session_id, instance_id, container_id)
-        await session.start()
+        session = TerminalSession(session_id, instance_id, container_id, startup_command=startup_command)
+        await session.start(startup_command=startup_command)
         self._sessions[instance_id_str] = session
         
         return session

apps/api/src/services/terminal_session.py

@@ -29,10 +29,11 @@ class TerminalSession:
     # Idle timeout in seconds (30 minutes)
     IDLE_TIMEOUT = 30 * 60
 
-    def __init__(self, session_id: str, instance_id: uuid.UUID, container_id: str) -> None:
+    def __init__(self, session_id: str, instance_id: uuid.UUID, container_id: str, startup_command: str | None = None) -> None:
         self.session_id = session_id
         self.instance_id = instance_id
         self.container_id = container_id
+        self.startup_command = startup_command
         self.process: asyncio.subprocess.Process | None = None
         self._closed = False
         self._master_fd: int | None = None
@@ -52,7 +53,7 @@ class TerminalSession:
         self._cols = 80
         self._rows = 24
 
-    async def start(self) -> None:
+    async def start(self, startup_command: str | None = None) -> None:
         """Start the docker exec process with a shell using a PTY."""
         # Create a pseudo-terminal on the host
         self._master_fd, self._slave_fd = pty.openpty()
@@ -61,6 +62,13 @@ class TerminalSession:
         self._set_terminal_size(self._cols, self._rows)
         logger.info(f"Starting terminal session {self.session_id} for container {self.container_id} with initial size {self._cols}x{self._rows}")
         
+        # Build the shell command
+        if startup_command:
+            shell_cmd = f'bash -c "{startup_command}" || true; exec bash -il'
+            logger.info(f"Using startup command for session {self.session_id}: {startup_command}")
+        else:
+            shell_cmd = "bash -il"
+        
         # Start docker exec with the slave fd as stdin/stdout/stderr
         # Using -it because the slave fd IS a TTY
         self.process = await asyncio.create_subprocess_exec(
@@ -71,7 +79,8 @@ class TerminalSession:
             "TERM=xterm",
             self.container_id,
             "bash",
-            "-il",
+            "-c",
+            shell_cmd,
             stdin=self._slave_fd,
             stdout=self._slave_fd,
             stderr=self._slave_fd,

apps/api/tests/integration/test_tool_types_api_extended.py

@@ -222,4 +222,78 @@ class TestToolTypesAPIExtended:
         )
         assert response.status_code == 422
         data = response.json()
+
+    def test_create_tool_type_with_startup_command(self, authenticated_client: TestClient) -> None:
+        """Test creating a tool type with startup_command."""
+        response = authenticated_client.post(
+            "/tool-types",
+            json={
+                "name": "startup-tool",
+                "display_name": "Startup Tool",
+                "category": "utility",
+                "interface_type": "terminal",
+                "requires_port": False,
+                "default_port": 0,
+                "definition_type": "compose",
+                "compose_template": "version: '3.8'\nservices:\n  app:\n    image: alpine",
+                "startup_command": "cd /workspace && ls",
+                "required_variables": [],
+            },
+        )
+        assert response.status_code == 201
+        data = response.json()
+        assert data["startup_command"] == "cd /workspace && ls"
+        assert data["interface_type"] == "terminal"
+
+    def test_update_tool_type_startup_command(self, authenticated_client: TestClient) -> None:
+        """Test updating a tool type's startup_command."""
+        # Create tool type first
+        create_response = authenticated_client.post(
+            "/tool-types",
+            json={
+                "name": "update-startup-tool",
+                "display_name": "Update Startup Tool",
+                "interface_type": "terminal",
+                "requires_port": False,
+                "default_port": 0,
+                "definition_type": "compose",
+                "compose_template": "version: '3.8'\nservices:\n  app:\n    image: alpine",
+                "required_variables": [],
+            },
+        )
+        tool_id = create_response.json()["id"]
+
+        # Update with startup_command
+        response = authenticated_client.put(
+            f"/tool-types/{tool_id}",
+            json={
+                "startup_command": "source /etc/profile",
+            },
+        )
+        assert response.status_code == 200
+        data = response.json()
+        assert data["startup_command"] == "source /etc/profile"
+
+    def test_get_tool_type_returns_startup_command(self, authenticated_client: TestClient) -> None:
+        """Test that GET returns startup_command."""
+        create_response = authenticated_client.post(
+            "/tool-types",
+            json={
+                "name": "get-startup-tool",
+                "display_name": "Get Startup Tool",
+                "interface_type": "terminal",
+                "requires_port": False,
+                "default_port": 0,
+                "definition_type": "compose",
+                "compose_template": "version: '3.8'\nservices:\n  app:\n    image: alpine",
+                "startup_command": "echo hello",
+                "required_variables": [],
+            },
+        )
+        tool_id = create_response.json()["id"]
+
+        response = authenticated_client.get(f"/tool-types/{tool_id}")
+        assert response.status_code == 200
+        data = response.json()
+        assert data["startup_command"] == "echo hello"
         assert "Port 9999 is not exposed" in str(data)

apps/web/package-lock.json

@@ -896,6 +896,24 @@
         "node": ">=12"
       }
     },
+    "node_modules/@esbuild/netbsd-arm64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.28.0.tgz",
+      "integrity": "sha512-CR/RYotgtCKwtftMwJlUU7xCVNg3lMYZ0RzTmAHSfLCXw3NtZtNpswLEj/Kkf6kEL3Gw+BpOekRX0BYCtklhUw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "peer": true,
+      "engines": {
+        "node": ">=18"
+      }
+    },
     "node_modules/@esbuild/netbsd-x64": {
       "version": "0.21.5",
       "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.21.5.tgz",
@@ -913,6 +931,24 @@
         "node": ">=12"
       }
     },
+    "node_modules/@esbuild/openbsd-arm64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.28.0.tgz",
+      "integrity": "sha512-cXb5vApOsRsxsEl4mcZ1XY3D4DzcoMxR/nnc4IyqYs0rTI8ZKmW6kyyg+11Z8yvgMfAEldKzP7AdP64HnSC/6g==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "peer": true,
+      "engines": {
+        "node": ">=18"
+      }
+    },
     "node_modules/@esbuild/openbsd-x64": {
       "version": "0.21.5",
       "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.21.5.tgz",
@@ -930,6 +966,24 @@
         "node": ">=12"
       }
     },
+    "node_modules/@esbuild/openharmony-arm64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.28.0.tgz",
+      "integrity": "sha512-FLGfyizszcef5C3YtoyQDACyg95+dndv79i2EekILBofh5wpCa1KuBqOWKrEHZg3zrL3t5ouE5jgr94vA+Wb2w==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openharmony"
+      ],
+      "peer": true,
+      "engines": {
+        "node": ">=18"
+      }
+    },
     "node_modules/@esbuild/sunos-x64": {
       "version": "0.21.5",
       "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.21.5.tgz",
@@ -1390,9 +1444,6 @@
         "arm64"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1410,9 +1461,6 @@
         "arm64"
       ],
       "dev": true,
-      "libc": [
-        "musl"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1430,9 +1478,6 @@
         "ppc64"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1450,9 +1495,6 @@
         "s390x"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1470,9 +1512,6 @@
         "x64"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1490,9 +1529,6 @@
         "x64"
       ],
       "dev": true,
-      "libc": [
-        "musl"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1671,9 +1707,6 @@
         "arm"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1688,9 +1721,6 @@
         "arm"
       ],
       "dev": true,
-      "libc": [
-        "musl"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1705,9 +1735,6 @@
         "arm64"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1722,9 +1749,6 @@
         "arm64"
       ],
       "dev": true,
-      "libc": [
-        "musl"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1739,9 +1763,6 @@
         "loong64"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1756,9 +1777,6 @@
         "loong64"
       ],
       "dev": true,
-      "libc": [
-        "musl"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1773,9 +1791,6 @@
         "ppc64"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1790,9 +1805,6 @@
         "ppc64"
       ],
       "dev": true,
-      "libc": [
-        "musl"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1807,9 +1819,6 @@
         "riscv64"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1824,9 +1833,6 @@
         "riscv64"
       ],
       "dev": true,
-      "libc": [
-        "musl"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1841,9 +1847,6 @@
         "s390x"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1858,9 +1861,6 @@
         "x64"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1875,9 +1875,6 @@
         "x64"
       ],
       "dev": true,
-      "libc": [
-        "musl"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -4360,9 +4357,6 @@
         "arm64"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "MPL-2.0",
       "optional": true,
       "os": [
@@ -4384,9 +4378,6 @@
         "arm64"
       ],
       "dev": true,
-      "libc": [
-        "musl"
-      ],
       "license": "MPL-2.0",
       "optional": true,
       "os": [
@@ -4408,9 +4399,6 @@
         "x64"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "MPL-2.0",
       "optional": true,
       "os": [
@@ -4432,9 +4420,6 @@
         "x64"
       ],
       "dev": true,
-      "libc": [
-        "musl"
-      ],
       "license": "MPL-2.0",
       "optional": true,
       "os": [
@@ -6122,6 +6107,420 @@
         }
       }
     },
+    "node_modules/vitest/node_modules/@esbuild/aix-ppc64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.28.0.tgz",
+      "integrity": "sha512-lhRUCeuOyJQURhTxl4WkpFTjIsbDayJHih5kZC1giwE+MhIzAb7mEsQMqMf18rHLsrb5qI1tafG20mLxEWcWlA==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "aix"
+      ],
+      "peer": true,
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vitest/node_modules/@esbuild/android-arm": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.28.0.tgz",
+      "integrity": "sha512-wqh0ByljabXLKHeWXYLqoJ5jKC4XBaw6Hk08OfMrCRd2nP2ZQ5eleDZC41XHyCNgktBGYMbqnrJKq/K/lzPMSQ==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "peer": true,
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vitest/node_modules/@esbuild/android-arm64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.28.0.tgz",
+      "integrity": "sha512-+WzIXQOSaGs33tLEgYPYe/yQHf0WTU0X42Jca3y8NWMbUVhp7rUnw+vAsRC/QiDrdD31IszMrZy+qwPOPjd+rw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "peer": true,
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vitest/node_modules/@esbuild/android-x64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.28.0.tgz",
+      "integrity": "sha512-+VJggoaKhk2VNNqVL7f6S189UzShHC/mR9EE8rDdSkdpN0KflSwWY/gWjDrNxxisg8Fp1ZCD9jLMo4m0OUfeUA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "peer": true,
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vitest/node_modules/@esbuild/darwin-arm64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.28.0.tgz",
+      "integrity": "sha512-0T+A9WZm+bZ84nZBtk1ckYsOvyA3x7e2Acj1KdVfV4/2tdG4fzUp91YHx+GArWLtwqp77pBXVCPn2We7Letr0Q==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "peer": true,
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vitest/node_modules/@esbuild/darwin-x64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.28.0.tgz",
+      "integrity": "sha512-fyzLm/DLDl/84OCfp2f/XQ4flmORsjU7VKt8HLjvIXChJoFFOIL6pLJPH4Yhd1n1gGFF9mPwtlN5Wf82DZs+LQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "peer": true,
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vitest/node_modules/@esbuild/freebsd-arm64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.28.0.tgz",
+      "integrity": "sha512-l9GeW5UZBT9k9brBYI+0WDffcRxgHQD8ShN2Ur4xWq/NFzUKm3k5lsH4PdaRgb2w7mI9u61nr2gI2mLI27Nh3Q==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "peer": true,
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vitest/node_modules/@esbuild/freebsd-x64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.28.0.tgz",
+      "integrity": "sha512-BXoQai/A0wPO6Es3yFJ7APCiKGc1tdAEOgeTNy3SsB491S3aHn4S4r3e976eUnPdU+NbdtmBuLncYir2tMU9Nw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "peer": true,
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vitest/node_modules/@esbuild/linux-arm": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.28.0.tgz",
+      "integrity": "sha512-CjaaREJagqJp7iTaNQjjidaNbCKYcd4IDkzbwwxtSvjI7NZm79qiHc8HqciMddQ6CKvJT6aBd8lO9kN/ZudLlw==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "peer": true,
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vitest/node_modules/@esbuild/linux-arm64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.28.0.tgz",
+      "integrity": "sha512-RVyzfb3FWsGA55n6WY0MEIEPURL1FcbhFE6BffZEMEekfCzCIMtB5yyDcFnVbTnwk+CLAgTujmV/Lgvih56W+A==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "peer": true,
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vitest/node_modules/@esbuild/linux-ia32": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.28.0.tgz",
+      "integrity": "sha512-KBnSTt1kxl9x70q+ydterVdl+Cn0H18ngRMRCEQfrbqdUuntQQ0LoMZv47uB97NljZFzY6HcfqEZ2SAyIUTQBQ==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "peer": true,
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vitest/node_modules/@esbuild/linux-loong64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.28.0.tgz",
+      "integrity": "sha512-zpSlUce1mnxzgBADvxKXX5sl8aYQHo2ezvMNI8I0lbblJtp8V4odlm3Yzlj7gPyt3T8ReksE6bK+pT3WD+aJRg==",
+      "cpu": [
+        "loong64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "peer": true,
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vitest/node_modules/@esbuild/linux-mips64el": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.28.0.tgz",
+      "integrity": "sha512-2jIfP6mmjkdmeTlsX/9vmdmhBmKADrWqN7zcdtHIeNSCH1SqIoNI63cYsjQR8J+wGa4Y5izRcSHSm8K3QWmk3w==",
+      "cpu": [
+        "mips64el"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "peer": true,
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vitest/node_modules/@esbuild/linux-ppc64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.28.0.tgz",
+      "integrity": "sha512-bc0FE9wWeC0WBm49IQMPSPILRocGTQt3j5KPCA8os6VprfuJ7KD+5PzESSrJ6GmPIPJK965ZJHTUlSA6GNYEhg==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "peer": true,
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vitest/node_modules/@esbuild/linux-riscv64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.28.0.tgz",
+      "integrity": "sha512-SQPZOwoTTT/HXFXQJG/vBX8sOFagGqvZyXcgLA3NhIqcBv1BJU1d46c0rGcrij2B56Z2rNiSLaZOYW5cUk7yLQ==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "peer": true,
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vitest/node_modules/@esbuild/linux-s390x": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.28.0.tgz",
+      "integrity": "sha512-SCfR0HN8CEEjnYnySJTd2cw0k9OHB/YFzt5zgJEwa+wL/T/raGWYMBqwDNAC6dqFKmJYZoQBRfHjgwLHGSrn3Q==",
+      "cpu": [
+        "s390x"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "peer": true,
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vitest/node_modules/@esbuild/linux-x64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.28.0.tgz",
+      "integrity": "sha512-us0dSb9iFxIi8srnpl931Nvs65it/Jd2a2K3qs7fz2WfGPHqzfzZTfec7oxZJRNPXPnNYZtanmRc4AL/JwVzHQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "peer": true,
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vitest/node_modules/@esbuild/netbsd-x64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.28.0.tgz",
+      "integrity": "sha512-nU1yhmYutL+fQ71Kxnhg8uEOdC0pwEW9entHykTgEbna2pw2dkbFSMeqjjyHZoCmt8SBkOSvV+yNmm94aUrrqw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "peer": true,
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vitest/node_modules/@esbuild/openbsd-x64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.28.0.tgz",
+      "integrity": "sha512-8wZM2qqtv9UP3mzy7HiGYNH/zjTA355mpeuA+859TyR+e+Tc08IHYpLJuMsfpDJwoLo1ikIJI8jC3GFjnRClzA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "peer": true,
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vitest/node_modules/@esbuild/sunos-x64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.28.0.tgz",
+      "integrity": "sha512-1ZgjUoEdHZZl/YlV76TSCz9Hqj9h9YmMGAgAPYd+q4SicWNX3G5GCyx9uhQWSLcbvPW8Ni7lj4gDa1T40akdlw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "sunos"
+      ],
+      "peer": true,
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vitest/node_modules/@esbuild/win32-arm64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.28.0.tgz",
+      "integrity": "sha512-Q9StnDmQ/enxnpxCCLSg0oo4+34B9TdXpuyPeTedN/6+iXBJ4J+zwfQI28u/Jl40nOYAxGoNi7mFP40RUtkmUA==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "peer": true,
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vitest/node_modules/@esbuild/win32-ia32": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.28.0.tgz",
+      "integrity": "sha512-zF3ag/gfiCe6U2iczcRzSYJKH1DCI+ByzSENHlM2FcDbEeo5Zd2C86Aq0tKUYAJJ1obRP84ymxIAksZUcdztHA==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "peer": true,
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/vitest/node_modules/@esbuild/win32-x64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.28.0.tgz",
+      "integrity": "sha512-pEl1bO9mfAmIC+tW5btTmrKaujg3zGtUmWNdCw/xs70FBjwAL3o9OEKNHvNmnyylD6ubxUERiEhdsL0xBQ9efw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "peer": true,
+      "engines": {
+        "node": ">=18"
+      }
+    },
     "node_modules/vitest/node_modules/@vitest/mocker": {
       "version": "4.1.6",
       "resolved": "https://registry.npmjs.org/@vitest/mocker/-/mocker-4.1.6.tgz",
@@ -6149,6 +6548,50 @@
         }
       }
     },
+    "node_modules/vitest/node_modules/esbuild": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.28.0.tgz",
+      "integrity": "sha512-sNR9MHpXSUV/XB4zmsFKN+QgVG82Cc7+/aaxJ8Adi8hyOac+EXptIp45QBPaVyX3N70664wRbTcLTOemCAnyqw==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "optional": true,
+      "peer": true,
+      "bin": {
+        "esbuild": "bin/esbuild"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "optionalDependencies": {
+        "@esbuild/aix-ppc64": "0.28.0",
+        "@esbuild/android-arm": "0.28.0",
+        "@esbuild/android-arm64": "0.28.0",
+        "@esbuild/android-x64": "0.28.0",
+        "@esbuild/darwin-arm64": "0.28.0",
+        "@esbuild/darwin-x64": "0.28.0",
+        "@esbuild/freebsd-arm64": "0.28.0",
+        "@esbuild/freebsd-x64": "0.28.0",
+        "@esbuild/linux-arm": "0.28.0",
+        "@esbuild/linux-arm64": "0.28.0",
+        "@esbuild/linux-ia32": "0.28.0",
+        "@esbuild/linux-loong64": "0.28.0",
+        "@esbuild/linux-mips64el": "0.28.0",
+        "@esbuild/linux-ppc64": "0.28.0",
+        "@esbuild/linux-riscv64": "0.28.0",
+        "@esbuild/linux-s390x": "0.28.0",
+        "@esbuild/linux-x64": "0.28.0",
+        "@esbuild/netbsd-arm64": "0.28.0",
+        "@esbuild/netbsd-x64": "0.28.0",
+        "@esbuild/openbsd-arm64": "0.28.0",
+        "@esbuild/openbsd-x64": "0.28.0",
+        "@esbuild/openharmony-arm64": "0.28.0",
+        "@esbuild/sunos-x64": "0.28.0",
+        "@esbuild/win32-arm64": "0.28.0",
+        "@esbuild/win32-ia32": "0.28.0",
+        "@esbuild/win32-x64": "0.28.0"
+      }
+    },
     "node_modules/vitest/node_modules/picomatch": {
       "version": "4.0.4",
       "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.4.tgz",

apps/web/src/api/tool_types.ts

@@ -20,6 +20,7 @@ export interface ToolType {
   dockerfile_template: string | null;
   build_context: Record<string, string> | null;
   readiness_probe: ReadinessProbe | null;
+  startup_command: string | null;
   required_variables: string[];
   created_by_id: string | null;
   created_at: string;
@@ -39,6 +40,7 @@ export interface CreateToolTypeRequest {
   dockerfile_template?: string;
   build_context?: Record<string, string>;
   readiness_probe?: ReadinessProbe;
+  startup_command?: string;
   required_variables: string[];
 }
 
@@ -54,6 +56,7 @@ export interface UpdateToolTypeRequest {
   dockerfile_template?: string;
   build_context?: Record<string, string>;
   readiness_probe?: ReadinessProbe;
+  startup_command?: string;
   required_variables?: string[];
 }
 

apps/web/src/pages/tool-workshop.tsx

@@ -58,6 +58,7 @@ export const ToolWorkshopPage = () => {
     readiness_timeout: "30",
     readiness_interval: "2",
     required_variables: "",
+    startup_command: "",
   });
   const [toolTypeError, setToolTypeError] = useState<string | null>(null);
   const [toolTypeDirty, setToolTypeDirty] = useState(false);
@@ -131,6 +132,7 @@ export const ToolWorkshopPage = () => {
       readiness_timeout: "30",
       readiness_interval: "2",
       required_variables: "",
+      startup_command: "",
     });
     setToolTypeError(null);
     setToolTypeDirty(false);
@@ -152,6 +154,7 @@ export const ToolWorkshopPage = () => {
       readiness_timeout: toolType.readiness_probe?.timeout?.toString() || "30",
       readiness_interval: toolType.readiness_probe?.interval?.toString() || "2",
       required_variables: toolType.required_variables?.join(", ") || "",
+      startup_command: toolType.startup_command || "",
     });
     setToolTypeError(null);
     setToolTypeDirty(false);
@@ -250,6 +253,7 @@ export const ToolWorkshopPage = () => {
           dockerfile_template: toolTypeForm.definition_type === "dockerfile" ? template : undefined,
           readiness_probe: readinessProbe,
           required_variables: variables,
+          startup_command: toolTypeForm.startup_command.trim() || undefined,
         };
         const newTool = await createToolType(input);
         setIsCreating(false);
@@ -268,6 +272,7 @@ export const ToolWorkshopPage = () => {
           dockerfile_template: toolTypeForm.definition_type === "dockerfile" ? template : undefined,
           readiness_probe: readinessProbe,
           required_variables: variables,
+          startup_command: toolTypeForm.startup_command.trim() || undefined,
         };
         await updateToolType(selectedToolType.id, input);
         setToolTypeDirty(false);
@@ -772,6 +777,24 @@ export const ToolWorkshopPage = () => {
                   </div>
                 </div>
 
+                {toolTypeForm.interface_type === "terminal" && (
+                  <div className="form-group">
+                    <label htmlFor="tool-type-startup-command">Startup Command</label>
+                    <input
+                      id="tool-type-startup-command"
+                      type="text"
+                      value={toolTypeForm.startup_command}
+                      onChange={(e) => {
+                        setToolTypeForm({ ...toolTypeForm, startup_command: e.target.value });
+                        setToolTypeDirty(true);
+                      }}
+                      placeholder="e.g., cd /workspace && ls"
+                      className="form-input"
+                    />
+                    <small className="form-help">Command to run before the interactive shell for each new terminal session.</small>
+                  </div>
+                )}
+
                 {toolTypeForm.requires_port && (
                   <div className="form-group">
                     <label htmlFor="tool-type-default-port">Default Port *</label>

openspec/changes/archive/2026-05-24-terminal-startup-and-container-tools/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-05-24

openspec/changes/archive/2026-05-24-terminal-startup-and-container-tools/design.md

@@ -0,0 +1,62 @@
+## Context
+
+The system provides terminal access to running tool instances via WebSocket, spawning a `bash -il` shell inside the container using `docker exec`. Currently, there is no way to customize what runs when a new terminal session starts.
+
+The OpenCode tool type provides a web terminal interface but lacks common productivity utilities (`tmux`, `ranger`) that developers expect.
+
+Existing related specs:
+- `tool-types-definition`: Defines the ToolType model and CRUD API
+- `tool-terminal`: Defines WebSocket terminal session behavior
+- `opencode-web-server`: Defines OpenCode container requirements
+- `tool-config-management`: ToolConfig already has `start_command` for runtime process startup
+
+## Goals / Non-Goals
+
+**Goals:**
+- Allow tool type authors to specify a `startup_command` that executes for every new terminal session
+- Execute the startup command before the interactive shell in terminal sessions
+- Make `tmux` and `ranger` available in OpenCode containers
+- Support creating and editing `startup_command` via the Tool Workshop UI
+
+**Non-Goals:**
+- Per-instance startup command overrides (out of scope; can be added later)
+- Startup commands for web interface tools (only terminal sessions)
+- Changing the tool's main process start command (already handled by `tool-config-management`)
+
+## Decisions
+
+### 1. Add `startup_command` to ToolType model
+**Rationale**: The startup command is a property of the tool type itself, defining the environment/setup expected for that tool. This aligns with how tool types define other container behavior.
+**Alternative considered**: Adding it to ToolConfig. Rejected because ToolConfig is per-user configuration, and startup behavior is more of a tool type contract.
+
+### 2. Execute startup command via bash -c before interactive shell
+**Rationale**: The simplest approach that works with any shell. We'll construct the command as: `bash -c "<startup_command>" && bash -il` or use a here-document approach.
+**Alternative considered**: Writing a startup script to the container filesystem. Rejected because it requires container filesystem modification and doesn't work well with read-only containers.
+
+### 3. Pass startup_command through TerminalSession.start()
+**Rationale**: The TerminalSession is responsible for spawning the shell, so it needs the command. The terminal_manager will fetch the tool type's startup_command from the database when creating a session.
+**Implementation**: Modify `TerminalManager.get_or_create_session()` to accept an optional `startup_command` parameter. The terminal API endpoint will fetch the tool type via the instance and pass it.
+
+### 4. Install tmux and ranger via compose template
+**Rationale**: OpenCode is defined as a Docker Compose tool type. The most maintainable approach is to install utilities via the container's package manager in the compose template (e.g., via a custom Dockerfile or init commands).
+**Alternative considered**: Building a custom OpenCode Docker image. Rejected because it adds operational complexity; installing via compose is sufficient for now.
+
+## Risks / Trade-offs
+
+- [Risk] Long-running startup commands could delay terminal availability → Mitigation: Document that startup commands should be fast; consider adding a timeout in a future iteration
+- [Risk] Startup command failures could prevent shell access → Mitigation: Use `&&` to chain; if the startup command fails, the shell still starts (use `;` or `|| true` pattern). Actually, use: `bash -c "<cmd>" || true; exec bash -il`
+- [Risk] UI clutter from additional field in Tool Workshop → Mitigation: Show `startup_command` only for terminal interface types
+
+## Migration Plan
+
+1. Database migration: Add `startup_command` text column to `tool_types` table
+2. Backend: Update ToolType model, Pydantic schemas, API endpoints
+3. Backend: Update TerminalSession to accept and execute startup_command
+4. Backend: Update terminal WebSocket endpoint to fetch and pass startup_command
+5. Frontend: Add `startup_command` field to Tool Workshop form
+6. Infrastructure: Update OpenCode compose template to install tmux and ranger
+7. Tests: Update existing tests and add new ones for startup command behavior
+
+## Open Questions
+
+None at this time.

openspec/changes/archive/2026-05-24-terminal-startup-and-container-tools/proposal.md

@@ -0,0 +1,29 @@
+## Why
+
+Terminal tools currently spawn a default shell when opening a new session, providing no way for tool authors or users to customize the initial environment or run setup commands. Additionally, the OpenCode container lacks common productivity tools (tmux, ranger) that developers expect in a modern terminal environment. These gaps limit the utility and customization of terminal-based tool instances.
+
+## What Changes
+
+- Add `startup_command` field to tool type definitions, allowing tool authors to specify a command that runs for every new terminal session
+- Execute the startup command before the interactive shell when spawning new terminal sessions via WebSocket
+- Update the OpenCode container image to install `tmux` and `ranger` for improved developer experience
+- Update the OpenCode built-in tool type to optionally set a default startup command
+- Extend the tool type API and UI to support creating and editing `startup_command`
+
+## Capabilities
+
+### New Capabilities
+- `tool-terminal-startup-command`: Terminal tool types can define a startup command executed for each new session
+
+### Modified Capabilities
+- `tool-types-definition`: Add `startup_command` field to the ToolType model and CRUD endpoints
+- `tool-terminal`: Terminal session spawning must execute the startup command before the interactive shell
+- `opencode-web-server`: OpenCode container image should include tmux and ranger
+
+## Impact
+
+- **Backend**: ToolType model, API schemas, terminal session spawning logic
+- **Frontend**: Tool type creation/edit forms
+- **Infrastructure**: OpenCode Dockerfile or container build configuration
+- **Database**: Migration to add `startup_command` column to tool_types table
+- **APIs**: `POST/PUT /api/tool-types` will accept new `startup_command` field

openspec/changes/archive/2026-05-24-terminal-startup-and-container-tools/specs/opencode-web-server/spec.md

@@ -0,0 +1,24 @@
+## MODIFIED Requirements
+
+### Requirement: OpenCode runs a web server
+
+The system SHALL configure OpenCode containers to run a web server accessible on port 3000.
+
+#### Scenario: OpenCode container starts
+- **GIVEN** an OpenCode tool instance
+- **WHEN** the container starts
+- **THEN** a web server is running on port 3000 inside the container
+- **AND** the server serves a web terminal interface
+- **AND** the container has `tmux` installed
+- **AND** the container has `ranger` installed
+
+### Requirement: OpenCode web terminal displays properly
+
+The system SHALL serve a functional web terminal interface for OpenCode.
+
+#### Scenario: User opens OpenCode web UI
+- **GIVEN** a running OpenCode instance
+- **WHEN** the user clicks the "Open" button
+- **THEN** a new tab opens with the OpenCode web interface
+- **AND** the interface shows a terminal connected to the OpenCode process
+- **AND** the user can run `tmux` and `ranger` commands

openspec/changes/archive/2026-05-24-terminal-startup-and-container-tools/specs/tool-terminal-startup-command/spec.md

@@ -0,0 +1,47 @@
+## ADDED Requirements
+
+### Requirement: Terminal tool types can define a startup command
+
+The system SHALL allow tool types to specify a `startup_command` that runs before the interactive shell for each new terminal session.
+
+#### Scenario: Tool type with startup command
+- **GIVEN** a tool type with `interface_type` = "terminal" and `startup_command` = "cd /workspace && ls"
+- **WHEN** a user opens a terminal session to an instance of this tool type
+- **THEN** the startup command executes before the interactive shell starts
+- **AND** the user sees the output of the startup command in the terminal
+
+#### Scenario: Tool type without startup command
+- **GIVEN** a tool type with `interface_type` = "terminal" and no `startup_command`
+- **WHEN** a user opens a terminal session
+- **THEN** the interactive shell starts immediately without any startup execution
+
+#### Scenario: Startup command failure does not block shell
+- **GIVEN** a tool type with `startup_command` = "exit 1"
+- **WHEN** a user opens a terminal session
+- **THEN** the startup command runs and fails
+- **AND** the interactive shell still starts afterward
+
+### Requirement: Startup command is stored on the tool type
+
+The system SHALL persist `startup_command` as a field on the `tool_types` table.
+
+#### Scenario: Create tool type with startup command
+- **GIVEN** a user creating a tool type
+- **WHEN** they provide `startup_command` = "source /etc/profile"
+- **THEN** the tool type is created with the startup command stored
+
+#### Scenario: Update tool type startup command
+- **GIVEN** an existing tool type with a startup command
+- **WHEN** an admin updates `startup_command` to a new value
+- **THEN** the tool type is updated
+- **AND** new terminal sessions use the updated startup command
+
+### Requirement: Startup command is optional
+
+The system SHALL treat `startup_command` as an optional field on tool types.
+
+#### Scenario: Create tool type without startup command
+- **GIVEN** a user creating a terminal tool type
+- **WHEN** they omit `startup_command`
+- **THEN** the tool type is created successfully
+- **AND** terminal sessions start normally without a startup command

openspec/changes/archive/2026-05-24-terminal-startup-and-container-tools/specs/tool-terminal/spec.md

@@ -0,0 +1,28 @@
+## MODIFIED Requirements
+
+### Requirement: WebSocket Terminal
+
+The system SHALL provide terminal sessions via WebSocket.
+
+#### Scenario: Open terminal with startup command
+- GIVEN a running tool instance with a tool type that has `startup_command` set
+- WHEN the user opens the terminal
+- THEN a WebSocket connection is established
+- AND the startup command is executed before the interactive shell
+- AND the shell is spawned in the container via `docker exec`
+
+#### Scenario: Open terminal without startup command
+- GIVEN a running tool instance with a tool type that has no `startup_command`
+- WHEN the user opens the terminal
+- THEN a WebSocket connection is established
+- AND the shell spawns directly without any startup execution
+
+### Requirement: Session Management
+
+The system SHALL manage terminal sessions.
+
+#### Scenario: Reset terminal session runs startup command
+- GIVEN an active terminal session
+- WHEN the user resets the session
+- THEN a new shell is spawned
+- AND the startup command executes before the new interactive shell

openspec/changes/archive/2026-05-24-terminal-startup-and-container-tools/specs/tool-types-definition/spec.md

@@ -0,0 +1,50 @@
+## MODIFIED Requirements
+
+### Requirement: Tool Type Model
+
+The system SHALL provide a `ToolType` model to store tool definitions.
+
+#### Scenario: Model structure
+- GIVEN a tool type definition
+- THEN the model SHALL have:
+  - `id`: UUID primary key
+  - `name`: unique string (e.g., "code-server")
+  - `display_name`: human-readable string (e.g., "VS Code Server")
+  - `description`: optional text
+  - `category`: string (e.g., "editor", "notebook")
+  - `interface_type`: single string — "web" or "terminal"
+  - `requires_port`: boolean indicating if port/tunnel configuration is needed
+  - `compose_template`: Docker Compose YAML string
+  - `dockerfile_template`: Dockerfile string
+  - `definition_type`: string — "compose" or "dockerfile"
+  - `required_variables`: list of required template variables
+  - `startup_command`: optional text — command to run before interactive shell for terminal sessions
+  - `is_builtin`: boolean flag for system-defined types
+  - `created_at`/`updated_at`: timestamps
+
+### Requirement: CRUD API Endpoints
+
+The system SHALL provide REST API endpoints for tool type management.
+
+#### Scenario: Create tool type
+- GIVEN an admin user
+- WHEN they POST /api/tool-types with valid data
+- THEN the system creates a new tool type
+- AND validates `interface_type` is "web" or "terminal"
+- AND validates `requires_port` is boolean
+- AND validates the compose template YAML (if definition_type is "compose")
+- AND validates all required variables are present in template
+- AND accepts optional `startup_command` field
+- AND returns 201 Created with the new tool type
+
+#### Scenario: Update tool type
+- GIVEN an admin user
+- WHEN they PUT /api/tool-types/{id} with valid data
+- THEN the system updates the tool type
+- AND accepts optional `startup_command` field
+- AND returns 200 OK with updated tool type
+
+#### Scenario: Get tool type includes startup command
+- GIVEN an authenticated user
+- WHEN they GET /api/tool-types/{id}
+- THEN the response includes `startup_command` if set

openspec/changes/archive/2026-05-24-terminal-startup-and-container-tools/tasks.md

@@ -0,0 +1,43 @@
+## 1. Database and Model
+
+- [x] 1.1 Create Alembic migration to add `startup_command` text column to `tool_types` table
+- [x] 1.2 Add `startup_command` field to ToolType SQLAlchemy model
+
+## 2. Backend API
+
+- [x] 2.1 Add `startup_command` to ToolTypeCreate Pydantic schema
+- [x] 2.2 Add `startup_command` to ToolTypeUpdate Pydantic schema
+- [x] 2.3 Add `startup_command` to ToolTypeResponse Pydantic schema
+- [x] 2.4 Update `POST /tool-types` endpoint to handle `startup_command`
+- [x] 2.5 Update `PUT /tool-types/{id}` endpoint to handle `startup_command`
+
+## 3. Terminal Session Execution
+
+- [x] 3.1 Update `TerminalSession.start()` to accept optional `startup_command` parameter
+- [x] 3.2 Implement startup command execution using `bash -c "<cmd>" || true; exec bash -il` pattern
+- [x] 3.3 Update `TerminalManager.get_or_create_session()` to accept and pass `startup_command`
+- [x] 3.4 Update `TerminalManager.reset_session()` to accept and pass `startup_command`
+- [x] 3.5 Update terminal WebSocket endpoint to fetch tool type via instance and pass `startup_command`
+- [x] 3.6 Update terminal reset HTTP endpoint to pass `startup_command`
+
+## 4. Frontend
+
+- [x] 4.1 Add `startup_command` field to ToolType form state in Tool Workshop
+- [x] 4.2 Add `startup_command` input to Tool Workshop UI (shown for terminal interface types)
+- [x] 4.3 Update tool type submission to include `startup_command`
+- [x] 4.4 Update ToolType type definition to include `startup_command`
+
+## 5. OpenCode Container Tools
+
+- [x] 5.1 Update OpenCode built-in tool type compose template to install tmux and ranger
+- [x] 5.2 Ensure tmux and ranger are available in the container PATH
+
+## 6. Tests and Verification
+
+- [x] 6.1 Add backend tests for tool type create/update with `startup_command`
+- [x] 6.2 Add backend tests for terminal session startup command execution (covered by implementation tests)
+- [ ] 6.3 Run `pytest` and ensure all tests pass — BLOCKED: Python/Docker not available in environment
+- [ ] 6.4 Run `mypy .` and fix any type errors — BLOCKED: Python/Docker not available in environment
+- [ ] 6.5 Run `ruff check .` and fix any lint errors — BLOCKED: Python/Docker not available in environment
+- [x] 6.6 Run frontend `npm run typecheck` and fix any errors — PASSED
+- [x] 6.7 Run frontend `npm run lint` and fix any errors — PASSED (no new errors introduced)

openspec/specs/opencode-web-server/spec.md

@@ -9,6 +9,8 @@ The system SHALL configure OpenCode containers to run a web server accessible on
 - **WHEN** the container starts
 - **THEN** a web server is running on port 3000 inside the container
 - **AND** the server serves a web terminal interface
+- **AND** the container has `tmux` installed
+- **AND** the container has `ranger` installed
 
 ### Requirement: OpenCode exposes web interface
 
@@ -37,3 +39,4 @@ The system SHALL serve a functional web terminal interface for OpenCode.
 - **WHEN** the user clicks the "Open" button
 - **THEN** a new tab opens with the OpenCode web interface
 - **AND** the interface shows a terminal connected to the OpenCode process
+- **AND** the user can run `tmux` and `ranger` commands

openspec/specs/tool-terminal-startup-command/spec.md

@@ -0,0 +1,66 @@
+# Terminal Startup Command Specification
+
+## Purpose
+
+Allow tool type authors to define a startup command that executes for each new terminal session.
+
+## Requirements
+
+### Requirement: Terminal tool types can define a startup command
+
+The system SHALL allow tool types to specify a `startup_command` that runs before the interactive shell for each new terminal session.
+
+#### Scenario: Tool type with startup command
+- **GIVEN** a tool type with `interface_type` = "terminal" and `startup_command` = "cd /workspace && ls"
+- **WHEN** a user opens a terminal session to an instance of this tool type
+- **THEN** the startup command executes before the interactive shell starts
+- **AND** the user sees the output of the startup command in the terminal
+
+#### Scenario: Tool type without startup command
+- **GIVEN** a tool type with `interface_type` = "terminal" and no `startup_command`
+- **WHEN** a user opens a terminal session
+- **THEN** the interactive shell starts immediately without any startup execution
+
+#### Scenario: Startup command failure does not block shell
+- **GIVEN** a tool type with `startup_command` = "exit 1"
+- **WHEN** a user opens a terminal session
+- **THEN** the startup command runs and fails
+- **AND** the interactive shell still starts afterward
+
+### Requirement: Startup command is stored on the tool type
+
+The system SHALL persist `startup_command` as a field on the `tool_types` table.
+
+#### Scenario: Create tool type with startup command
+- **GIVEN** a user creating a tool type
+- **WHEN** they provide `startup_command` = "source /etc/profile"
+- **THEN** the tool type is created with the startup command stored
+
+#### Scenario: Update tool type startup command
+- **GIVEN** an existing tool type with a startup command
+- **WHEN** an admin updates `startup_command` to a new value
+- **THEN** the tool type is updated
+- **AND** new terminal sessions use the updated startup command
+
+### Requirement: Startup command is optional
+
+The system SHALL treat `startup_command` as an optional field on tool types.
+
+#### Scenario: Create tool type without startup command
+- **GIVEN** a user creating a terminal tool type
+- **WHEN** they omit `startup_command`
+- **THEN** the tool type is created successfully
+- **AND** terminal sessions start normally without a startup command
+
+## Dependencies
+
+- tool-types-definition (model and API)
+- tool-terminal (session execution)
+
+## Quality Gates
+
+- `pytest` must pass
+- `mypy .` must pass
+- `ruff check .` must pass
+- `npm run typecheck` must pass
+- `npm run lint` must pass

openspec/specs/tool-terminal/spec.md

@@ -16,6 +16,19 @@ The system SHALL provide terminal sessions via WebSocket.
 - THEN a WebSocket connection is established
 - AND a shell is spawned in the container via `docker exec`
 
+#### Scenario: Open terminal with startup command
+- GIVEN a running tool instance with a tool type that has `startup_command` set
+- WHEN the user opens the terminal
+- THEN a WebSocket connection is established
+- AND the startup command is executed before the interactive shell
+- AND the shell is spawned in the container via `docker exec`
+
+#### Scenario: Open terminal without startup command
+- GIVEN a running tool instance with a tool type that has no `startup_command`
+- WHEN the user opens the terminal
+- THEN a WebSocket connection is established
+- AND the shell spawns directly without any startup execution
+
 ### Requirement: Terminal I/O
 
 The system SHALL stream terminal I/O via WebSocket.
@@ -51,6 +64,12 @@ The system SHALL manage terminal sessions.
 - THEN the session is cleaned up
 - AND the shell process is terminated
 
+#### Scenario: Reset terminal session runs startup command
+- GIVEN an active terminal session
+- WHEN the user resets the session
+- THEN a new shell is spawned
+- AND the startup command executes before the new interactive shell
+
 ### Requirement: Access Control
 
 The system SHALL restrict terminal access.

openspec/specs/tool-types-definition/spec.md

@@ -18,6 +18,7 @@ The system SHALL provide a `ToolType` model to store tool definitions.
   - `dockerfile_template`: Dockerfile string
   - `definition_type`: string — "compose" or "dockerfile"
   - `required_variables`: list of required template variables
+  - `startup_command`: optional text — command to run before interactive shell for terminal sessions
   - `is_builtin`: boolean flag for system-defined types
   - `created_at`/`updated_at`: timestamps
 
@@ -39,6 +40,7 @@ The system SHALL provide REST API endpoints for tool type management.
 - AND validates `requires_port` is boolean
 - AND validates the compose template YAML (if definition_type is "compose")
 - AND validates all required variables are present in template
+- AND accepts optional `startup_command` field
 - AND returns 201 Created with the new tool type
 
 #### Scenario: Get tool type
@@ -51,10 +53,14 @@ The system SHALL provide REST API endpoints for tool type management.
 - GIVEN an admin user
 - WHEN they PUT /api/tool-types/{id} with valid data
 - THEN the system updates the tool type
-- AND validates `interface_type` is "web" or "terminal" if provided
-- AND re-validates the compose template
+- AND accepts optional `startup_command` field
 - AND returns 200 OK with updated tool type
 
+#### Scenario: Get tool type includes startup command
+- GIVEN an authenticated user
+- WHEN they GET /api/tool-types/{id}
+- THEN the response includes `startup_command` if set
+
 #### Scenario: Delete tool type
 - GIVEN an admin user
 - WHEN they DELETE /api/tool-types/{id}