feat: add --detach and --log-file support for agentcore launch --local

README.md

@@ -35,6 +35,8 @@ Amazon Bedrock AgentCore includes the following modular Services that you can us
 ## 🚀 Amazon Bedrock AgentCore Runtime
 AgentCore Runtime is a secure, serverless runtime purpose-built for deploying and scaling dynamic AI agents and tools using any open-source framework including LangGraph, CrewAI, and Strands Agents, any protocol, and any model. Runtime was built to work for agentic workloads with industry-leading extended runtime support, fast cold starts, true session isolation, built-in identity, and support for multi-modal payloads. Developers can focus on innovation while Amazon Bedrock AgentCore Runtime handles infrastructure and security -- accelerating time-to-market
 
+**Key Features**: Zero-infrastructure deployment, local development with background mode for AI IDEs, streaming support, session management, and comprehensive observability.
+
 **[Runtime Quick Start](documentation/docs/user-guide/runtime/quickstart.md)**
 
 ## 🧠 Amazon Bedrock AgentCore Memory

documentation/docs/api-reference/cli.md

@@ -58,6 +58,10 @@ Options:
 
 - `--local, -l`: Run locally
 
+- `--detach, -d`: Run in detached mode (background) - only works with --local
+
+- `--log-file TEXT`: Redirect logs to file (implies --detach) - only works with --local
+
 - `--push-ecr, -p`: Build and push to ECR only (no deployment)
 
 - `--env, -env TEXT`: Environment variables for agent (format: KEY=VALUE)
@@ -177,6 +181,13 @@ agentcore launch
 # Run locally
 agentcore launch --local
 
+# Run locally in background (detached mode)
+agentcore launch --local --detach
+agentcore launch --local -d
+
+# Run locally with custom log file (auto-detaches)
+agentcore launch --local --log-file my-agent.log
+
 # Launch with environment variables
 agentcore launch --env API_KEY=abc123 --env DEBUG=true
 ```
@@ -239,3 +250,58 @@ agentcore import-agent \
 # AgentCore Primitive Opt-out
 agentcore import-agent --disable-gateway --disable-memory --disable-code-interpreter --disable-observability
 ```
+
+## Common Issues and Solutions
+
+### Detach Mode Validation Errors
+
+**Error**: `--detach can only be used with --local`
+```bash
+# ❌ Invalid - detach without local
+agentcore launch --detach
+
+# ✅ Correct - detach with local
+agentcore launch --local --detach
+```
+
+**Error**: `--log-file can only be used with --local`
+```bash
+# ❌ Invalid - log-file without local
+agentcore launch --log-file agent.log
+
+# ✅ Correct - log-file with local
+agentcore launch --local --log-file agent.log
+```
+
+### Terminal Blocking Issues
+
+**Problem**: Agent blocks terminal, can't run other commands
+
+**Solution**: Use detach mode
+```bash
+# Instead of this (blocks terminal)
+agentcore launch --local
+
+# Use this (runs in background)
+agentcore launch --local --detach
+```
+
+### Background Process Management
+
+**Check if agent is running**:
+```bash
+# Look for Python processes running your agent
+ps aux | grep "my_agent.py"
+
+# Check port 8080 usage
+lsof -i :8080
+```
+
+**Stop background agent**:
+```bash
+# Find and stop the process
+pkill -f "my_agent.py"
+
+# Or kill by port
+lsof -ti:8080 | xargs kill
+```

documentation/docs/user-guide/runtime/overview.md

@@ -53,9 +53,13 @@ agentcore launch                    # Uses CodeBuild - no Docker needed
 
 ### 💻 Local Development
 ```bash
-agentcore launch --local           # Build and run locally
+agentcore launch --local           # Build and run locally (foreground)
+agentcore launch --local --detach  # Build and run in background
+agentcore launch --local -d        # Short form for detach mode
 ```
 - **Fast iteration** - immediate feedback and debugging
+- **Background mode** - run agents without blocking terminal (perfect for AI IDEs)
+- **Custom logging** - redirect logs to files for debugging
 - **Requires:** Docker, Finch, or Podman
 
 ### 🔧 Hybrid Build
@@ -252,7 +256,8 @@ if __name__ == "__main__":
 agentcore configure --entrypoint my_agent.py
 
 # 2. Develop locally
-agentcore launch --local
+agentcore launch --local           # Foreground mode for debugging
+agentcore launch --local --detach  # Background mode for AI IDEs
 
 # 3. Test
 agentcore invoke '{"prompt": "Hello"}'
@@ -265,4 +270,28 @@ agentcore launch
 agentcore status
 ```
 
+### Local Development Best Practices
+
+**For Interactive Development:**
+```bash
+# Use foreground mode for debugging and immediate feedback
+agentcore launch --local
+```
+
+**For AI IDEs and Terminal Reuse:**
+```bash
+# Use detach mode to free up terminal for other tasks
+agentcore launch --local --detach
+
+# Or with custom log file for debugging
+agentcore launch --local --log-file debug.log
+```
+
+**For Continuous Development:**
+```bash
+# Start agent in background, continue development work
+agentcore launch --local -d
+# Terminal is now free for git, testing, etc.
+```
+
 The AgentCore Runtime SDK provides everything needed to build, test, and deploy production-ready AI agents with minimal setup and maximum flexibility.

documentation/docs/user-guide/runtime/quickstart.md

@@ -98,6 +98,15 @@ agentcore invoke '{"prompt": "tell me a joke"}'
 lsof -ti:8080 | xargs kill -9
 ```
 
+**"Terminal blocked by local agent"**
+```bash
+# Use detach mode to run agent in background
+agentcore launch --local --detach
+
+# Or redirect logs to file (auto-detaches)
+agentcore launch --local --log-file agent.log
+```
+
 **"Permission denied" errors**
 - Verify AWS credentials: `aws sts get-caller-identity`
 - Check you have the required managed policies attached
@@ -141,8 +150,15 @@ Perfect for production, managed environments, teams without Docker
 **💻 Local Development**
 ```bash
 agentcore launch --local  # Build and run locally (requires Docker/Finch/Podman)
+
+# NEW: Background mode for AI IDEs and terminal reuse
+agentcore launch --local --detach  # Run in background (Docker-style)
+agentcore launch --local -d        # Short form
+
+# NEW: Custom log files
+agentcore launch --local --log-file my-agent.log  # Redirect logs (implies --detach)
 ```
-Perfect for development, rapid iteration, debugging
+Perfect for development, rapid iteration, debugging, AI IDE integration
 
 **🔧 Hybrid: Local Build + Cloud Runtime**
 ```bash

src/bedrock_agentcore_starter_toolkit/cli/cli.py

@@ -19,6 +19,8 @@
 app.command("import-agent")(import_agent)
 app.add_typer(configure_app)
 
+# Note: Process management commands (ps, stop, logs) will be added in future PRs
+
 # gateway
 app.command("create_mcp_gateway")(create_mcp_gateway)
 app.command("create_mcp_gateway_target")(create_mcp_gateway_target)

src/bedrock_agentcore_starter_toolkit/cli/runtime/commands.py

@@ -20,6 +20,7 @@
     validate_agent_name,
 )
 from ...utils.runtime.entrypoint import parse_entrypoint
+from ...utils.runtime.local_process_manager import LocalProcessManager
 from ..common import _handle_error, _print_success, console
 from .configuration_manager import ConfigurationManager
 
@@ -271,6 +272,17 @@ def launch(
         "-lb",
         help="Build locally and deploy to cloud runtime - requires Docker/Finch/Podman",
     ),
+    detach: bool = typer.Option(
+        False,
+        "--detach",
+        "-d",
+        help="Run in detached mode (background) - only works with --local",
+    ),
+    log_file: Optional[str] = typer.Option(
+        None,
+        "--log-file",
+        help="Redirect logs to file (implies --detach for --local mode)",
+    ),
     auto_update_on_conflict: bool = typer.Option(
         False,
         "--auto-update-on-conflict",
@@ -287,7 +299,7 @@ def launch(
         hidden=True,
     ),
 ):
-    """Launch Bedrock AgentCore with three deployment modes.
+    """Launch Bedrock AgentCore with multiple deployment modes.
 
     🚀 DEFAULT (no flags): CodeBuild + cloud runtime (RECOMMENDED)
        - Build ARM64 containers in the cloud with CodeBuild
@@ -306,10 +318,16 @@ def launch(
        - requires Docker/Finch/Podman
        - Use when you need custom build control but want cloud deployment
 
+    🐳 --local --detach: Docker-style detached mode (NEW!)
+       - Run local agent in background (detached mode)
+       - Agent runs independently of terminal session
+       - Use --log-file to redirect output to file
+
     MIGRATION GUIDE:
     - OLD: agentcore launch --code-build  →  NEW: agentcore launch
     - OLD: agentcore launch --local       →  NEW: agentcore launch --local (unchanged)
     - NEW: agentcore launch --local-build (build locally + deploy to cloud)
+    - NEW: agentcore launch --local --detach (Docker-style background mode)
     """
     # Handle deprecated --code-build flag
     if code_build:
@@ -321,6 +339,17 @@ def launch(
     # Validate mutually exclusive options
     if sum([local, local_build, code_build]) > 1:
         _handle_error("Error: --local, --local-build, and --code-build cannot be used together")
+
+    # Validate detach and log-file options
+    if detach and not local:
+        _handle_error("Error: --detach can only be used with --local")
+
+    if log_file and not local:
+        _handle_error("Error: --log-file can only be used with --local")
+
+    # If log_file is specified, imply detach mode
+    if log_file and local:
+        detach = True
 
     config_path = Path.cwd() / ".bedrock_agentcore.yaml"
 
@@ -385,16 +414,53 @@ def launch(
         if result.mode == "local":
             _print_success(f"Docker image built: {result.tag}")
             _print_success("Ready to run locally")
-            console.print("Starting server at http://localhost:8080")
-            console.print("[yellow]Press Ctrl+C to stop[/yellow]\n")
 
             if result.runtime is None or result.port is None:
                 _handle_error("Unable to launch locally")
 
-            try:
-                result.runtime.run_local(result.tag, result.port, result.env_vars)
-            except KeyboardInterrupt:
-                console.print("\n[yellow]Stopped[/yellow]")
+            if detach:
+                # Run in detached mode
+                process_manager = LocalProcessManager()
+
+                # Determine agent name
+                from ...utils.runtime.config import load_config
+                project_config = load_config(config_path)
+                agent_config = project_config.get_agent_config(agent)
+                agent_name = agent_config.name
+
+                try:
+                    local_agent = process_manager.start_agent(
+                        name=agent_name,
+                        runtime=result.runtime,
+                        tag=result.tag,
+                        port=result.port,
+                        env_vars=result.env_vars,
+                        log_file=log_file,
+                        config_path=str(config_path),
+                    )
+
+                    console.print(f"[green]✅ Agent started in detached mode[/green]")
+                    console.print(f"[cyan]Agent Name:[/cyan] {local_agent.name}")
+                    console.print(f"[cyan]PID:[/cyan] {local_agent.pid}")
+                    console.print(f"[cyan]Port:[/cyan] {local_agent.port}")
+                    console.print(f"[cyan]Server:[/cyan] http://localhost:{local_agent.port}")
+                    if local_agent.log_file:
+                        console.print(f"[cyan]Logs:[/cyan] {local_agent.log_file}")
+
+                    console.print(f"\n[dim]Agent is running in background (PID: {local_agent.pid})[/dim]")
+                    console.print(f"[dim]Process management commands will be added in future releases[/dim]")
+
+                except RuntimeError as e:
+                    _handle_error(str(e))
+            else:
+                # Run in foreground mode (existing behavior)
+                console.print("Starting server at http://localhost:8080")
+                console.print("[yellow]Press Ctrl+C to stop[/yellow]\n")
+
+                try:
+                    result.runtime.run_local(result.tag, result.port, result.env_vars)
+                except KeyboardInterrupt:
+                    console.print("\n[yellow]Stopped[/yellow]")
 
         elif result.mode == "codebuild":
             _print_success(f"CodeBuild completed: [cyan]{result.codebuild_id}[/cyan]")