[Enhancement] Add background/daemon mode for `agentcore launch --local`

[pahud]

Summary

Add --detach and --log-file options to agentcore launch --local to enable background execution and log redirection, improving compatibility with AI IDEs like Kiro that need to reuse terminal sessions.

Problem Description

Currently, agentcore launch --local always runs in the foreground, blocking the terminal until manually stopped with Ctrl+C. This creates usability issues for:

• AI IDEs like Kiro: Need to reuse the same terminal for multiple operations
• Development workflows: Developers want to run the agent locally while continuing to use the terminal
• CI/CD pipelines: Automated testing scenarios that need background agent execution
• Multi-agent development: Running multiple agents simultaneously in different terminals

Current behavior:

$ agentcore launch --local
Starting server at http://localhost:8080
Press Ctrl+C to stop

# Terminal is blocked here - cannot run other commands

Proposed Solution

1. Add --detach/-d flag (Docker-style)

# Run in background (detached mode) - follows Docker convention
agentcore launch --local --detach
agentcore launch --local -d

# Output:
# Agent started in detached mode (PID: 12345)
# Server running at http://localhost:8080
# Agent running in background...

2. Add --log-file option (Docker-style)

# Redirect logs to file (like docker run --log-driver)
agentcore launch --local --detach --log-file agent.log

# Or with custom path
agentcore launch --local -d --log-file /tmp/my-agent.log

3. Process Management (Future Enhancement)

Process management commands will be added in future PRs:

# Future: List running local agents
agentcore ps --local

# Future: Stop local agents  
agentcore stop --local AGENT_NAME
agentcore stop --local --all

# Future: View local agent logs
agentcore logs --local AGENT_NAME
agentcore logs --local -f AGENT_NAME

Implementation Details

Command Line Interface Changes

def launch(
    # ... existing parameters ...
    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)"
    ),
):

Process Management

• Use Python's subprocess.Popen for background process spawning
• Store PID in a state file (e.g., .agentcore/local_agents.json)
• Implement proper signal handling for graceful shutdown
• Basic process lifecycle management

Log Management

• Default log location: .agentcore/logs/{agent_name}.log
• Custom log file paths supported via --log-file
• Structured logging with timestamps
• Log file creation and directory management

State Tracking (Basic)

Store running agent information in .agentcore/local_agents.json:

{
  "agents": [
    {
      "name": "my-agent",
      "pid": 12345,
      "port": 8080,
      "log_file": "/path/to/agent.log",
      "started_at": "2025-08-29T20:00:00Z"
    }
  ]
}

Usage Examples

Basic detached mode

# Start agent in background (detached)
agentcore launch --local --detach

# Continue using terminal for other tasks
agentcore invoke '{"message": "Hello"}'

# Agent runs in background until manually stopped

Development workflow with custom logs

# Start agent with custom log file
agentcore launch --local --detach --log-file dev.log

# Or just specify log file (auto-detaches)
agentcore launch --local --log-file my-agent.log

# Continue development work in same terminal
agentcore invoke '{"message": "test"}'

AI IDE Integration

# Perfect for IDEs like Kiro - no terminal blocking
agentcore launch --local --detach

# IDE can continue using terminal for other operations
# Agent runs independently in background

Benefits

For AI IDEs (Kiro, Cursor, etc.)

• Terminal reuse: Can run agent in background and continue using terminal
• Automation: Can start/stop agents programmatically
• Multi-agent workflows: Support multiple agents for complex scenarios

For Developers

• Improved DX: No need to open multiple terminals
• Persistent agents: Agents survive terminal sessions
• Better debugging: Centralized log management
• CI/CD friendly: Scriptable background execution

For Production-like Testing

• Service simulation: Run agents like system services
• Load testing: Multiple concurrent agents
• Integration testing: Background agents for test suites

Alternative Solutions Considered

1. Manual backgrounding with &

agentcore launch --local &

Issues:

• No process management
• Logs mixed with terminal output
• No clean shutdown mechanism
• PID tracking is manual

2. External process managers (systemd, pm2)

Issues:

• Additional dependencies
• Platform-specific solutions
• Complex setup for simple use case

3. Docker Compose

Issues:

• Overkill for single agent development
• Additional configuration files
• Not integrated with agentcore CLI

Docker Consistency

This proposal follows Docker's established conventions:

Docker Command	AgentCore Equivalent	Purpose	Status
docker run -d nginx	agentcore launch --local -d	Run in background	This PR
docker ps	agentcore ps --local	List running containers/agents	Future PR
docker logs container	agentcore logs --local agent	View logs	Future PR
docker logs -f container	agentcore logs --local -f agent	Follow logs	Future PR
docker stop container	agentcore stop --local agent	Stop container/agent	Future PR
docker stop $(docker ps -q)	agentcore stop --local --all	Stop all	Future PR

Why Docker-style is Better

• Familiar: Developers already know Docker conventions
• Consistent: Same patterns across container tools
• Standard: -d/--detach is the industry standard
• Intuitive: ps, logs, stop are universally understood

Implementation Priority

This PR (Core Detach Mode)

• --detach/-d flag for agentcore launch --local
• --log-file option with automatic detach
• Basic PID tracking and state file
• Process spawning and background execution
• Validation and error handling
• Backward compatibility

Compatibility

• Backward compatible: Existing agentcore launch --local behavior unchanged
• Cross-platform: Works on macOS, Linux, and Windows
• Docker agnostic: Works with Docker, Finch, and Podman
• IDE integration: Designed for AI IDE workflows
• Docker-consistent: Follows established container management patterns

Related Issues

• Improves developer experience for local agent development
• Enables better integration with AI IDEs like Kiro
• Supports advanced testing scenarios with multiple agents
• Aligns with modern development tool expectations (similar to npm start, docker-compose up -d)

---

Impact: This enhancement would significantly improve the developer experience for local AgentCore development, especially for users of AI IDEs who need flexible terminal management and background process execution.

[siwachabhi]

I think this is significant complexity added into toolkit, which can be achieved with existing shell or docker commands, we discussed this internally and don't think right now its a good idea to bring this complexity