Add support for .openhands/setup.sh script

docs/modules/usage/customization/repository.md

@@ -0,0 +1,24 @@
+# Repository Customization
+
+You can customize how OpenHands works with your repository by creating a
+`.openhands` directory at the root level.
+
+## Microagents
+You can use microagents to extend the OpenHands prompts with information
+about your project and how you want OpenHands to work. See
+[Repository Microagents](../prompting/microagents-repo) for more information.
+
+
+## Setup Script
+You can add `.openhands/setup.sh`, which will be run every time OpenHands begins
+working with your repository. This is a good place to install dependencies, set
+environment variables, etc.
+
+For example:
+```bash
+#!/bin/bash
+export MY_ENV_VAR="my value"
+sudo apt-get update
+sudo apt-get install -y lsof
+cd frontend && npm install ; cd ..
+```

docs/sidebars.ts

@@ -45,6 +45,17 @@ const sidebars: SidebarsConfig = {
         }
       ],
     },
+    {
+      type: 'category',
+      label: 'Customization',
+      items: [
+        {
+          type: 'doc',
+          label: 'Repository Customization',
+          id: 'usage/customization/repository',
+        },
+      ],
+    },
     {
       type: 'category',
       label: 'Usage Methods',

openhands/runtime/base.py

@@ -234,12 +234,23 @@ def clone_repo(self, github_token: str, selected_repository: str) -> str:
         self.run_action(action)
         return dir_name
 
+    def maybe_run_setup_script(self):
+        """Run .openhands/setup.sh if it exists in the workspace or repository."""
+        setup_script = '.openhands/setup.sh'
+        read_obs = self.read(FileReadAction(path=setup_script))
+        if isinstance(read_obs, ErrorObservation):
+            return
+
+        action = CmdRunAction(f'chmod +x {setup_script} && source {setup_script}')
+        obs = self.run_action(action)
+        if isinstance(obs, CmdOutputObservation) and obs.exit_code != 0:
+            self.log('error', f'Setup script failed: {obs.content}')
+
     def get_microagents_from_selected_repo(
         self, selected_repository: str | None
     ) -> list[BaseMicroAgent]:
         """Load microagents from the selected repository.
         If selected_repository is None, load microagents from the current workspace.
-
         This is the main entry point for loading microagents.
         """
 

openhands/server/session/agent_session.py

@@ -119,7 +119,7 @@ async def start(
             self.event_stream.add_event(
                 MessageAction(content=initial_user_msg), EventSource.USER
             )
-            
+
         self._starting = False
 
     async def close(self):
@@ -223,6 +223,7 @@ async def _create_runtime(
             repo_directory = await call_sync_from_async(
                 self.runtime.clone_repo, github_token, selected_repository
             )
+            await call_sync_from_async(self.runtime.maybe_run_setup_script)
 
         if agent.prompt_manager:
             agent.prompt_manager.set_runtime_info(self.runtime)