feat: support global .env file in AgentBox directory

[shrwnsan]

Summary

Support a global .env file in the AgentBox directory (e.g., ~/.agentbox/.env) that loads before project-specific .env files.

Use Case

Configure custom API endpoints and keys for 3rd party inference providers (e.g., non-Anthropic inference services) without needing to set credentials per-project.

Current Behavior

• Only PROJECT_DIR/.env is loaded
• Global configuration (API keys, custom endpoints, etc.) must be set per-project or via Claude auth volume
• Using 3rd party inference requires configuring ANTHROPIC_BASE_URL and ANTHROPIC_API_KEY in each project

Proposed Change

• Load SCRIPT_DIR/.env first (e.g., ~/.agentbox/.env)
• Then load PROJECT_DIR/.env if it exists
• Project env vars override global ones (Docker env-file behavior: last wins)

Security Considerations

• Low risk: Consistent with existing credential sharing via Claude auth volume
• Credential concentration: API keys shared across projects (already true for Claude auth)
• Override behavior: Project .env takes precedence (correct behavior)
• Mitigation: Add ~/.agentbox/.env to .gitignore

Rationale

Aligns with AgentBox's simplicity philosophy - provides convenient global configuration for 3rd party inference without prompts or complex setup.

---

🤖 Generated by Claude Code - GLM 4.7

[shrwnsan]

Feasibility & Pragmaticism Review

Summary

The issue proposes adding support for a global .env file in ~/.agentbox/.env that loads before project-specific .env files, enabling centralized configuration for API keys and custom inference endpoints.

---

Feasibility Assessment: HIGHLY FEASIBLE

Technical Implementation:

• Current code already loads project .env files (line 727-730 in agentbox)
• Docker's --env-file flag supports multiple files with last-wins precedence
• Minimal code changes required (~5-10 lines)
• No breaking changes to existing functionality

Implementation Complexity: LOW

# Current code (line 727-730):
if [[ -f "$PROJECT_DIR/.env" ]]; then
    env_file_args+=(--env-file "$PROJECT_DIR/.env")
fi

# Proposed change:
if [[ -f "$SCRIPT_DIR/.env" ]]; then
    env_file_args+=(--env-file "$SCRIPT_DIR/.env")  # Global first
fi
if [[ -f "$PROJECT_DIR/.env" ]]; then
    env_file_args+=(--env-file "$PROJECT_DIR/.env")  # Project overrides
fi

---

Pragmaticism Assessment: VERY PRAGMATIC

Strengths:

1. Solves Real Problem: Users configuring 3rd-party inference providers (e.g., OpenAI, local LLMs) currently need to set ANTHROPIC_BASE_URL/ANTHROPIC_API_KEY in every project
2. Aligns with Philosophy: AgentBox's core value is simplicity - this reduces repetitive configuration without adding complexity
3. Low Risk: Consistent with existing credential sharing via Claude auth volumes (already shared across projects)
4. Correct Behavior: Project .env overrides global .env (Docker's natural precedence)
5. Common Pattern: Similar to how .gitconfig, .ssh/config, and other tools handle global vs local config

Use Case Validation:

• Strong: API keys for inference providers, custom endpoints, development tools
• Weak: Project-specific settings (these belong in project .env anyway)

---

Security Considerations: ACCEPTABLE RISK

Current State:

• Claude auth volume already shares credentials across projects
• SSH keys shared across all projects (~/.agentbox/ssh/)
• Project .env files can contain secrets

Proposed Change:

• Global .env centralizes credentials (concentration risk)
• Mitigation: Add to .gitignore as suggested in issue
• Override: Project .env takes precedence, allowing per-project overrides

Risk Level: LOW - consistent with existing design

---

Recommendations

Implement with these considerations:

1. File Location: ~/.agentbox/.env (not SCRIPT_DIR/.env) - more intuitive for users
2. Documentation: Add example to README showing global .env usage
3. Error Handling: Warn if file exists but isn't readable (permissions)
4. Security: Auto-add .gitignore entry in ssh-init or create on first use
5. Validation: Check file exists before adding to Docker args (current code does this)

Suggested Enhancement:

# In ssh_setup() function, also create global .env template:
local agentbox_env="${HOME}/.agentbox/.env"
if [[ ! -f "$agentbox_env" ]]; then
    cat > "$agentbox_env" << 'EOF'
# AgentBox global environment variables
# These variables are loaded for ALL projects
# Project-specific .env files will override these values

# Example: Third-party inference provider
# ANTHROPIC_BASE_URL=https://api.example.com/v1
# ANTHROPIC_API_KEY=your-key-here
EOF
    chmod 600 "$agentbox_env"
    log_info "Created global .env template: $agentbox_env"
fi

---

Verdict

Implement - This is a pragmatic, low-risk enhancement that aligns perfectly with AgentBox's simplicity philosophy. The implementation cost is minimal (~10 lines of code) while providing significant user value for multi-project workflows using custom inference providers.

Priority: MEDIUM - Quality of life improvement, not critical functionality

---

Reviewed by: Droid - GLM 4.7

[shrwnsan]

Feasibility & Pragmatism Review

Feasibility: ✅ High

The implementation is straightforward. Currently only $PROJECT_DIR/.env is loaded via Docker's --env-file flag. Adding global support requires:

1. Check for ~/.agentbox/.env
2. Pass it first: --env-file ~/.agentbox/.env
3. Then pass project .env if exists
4. Docker handles the "last wins" precedence automatically

Pragmatism: ✅ Strong

• Aligns with design philosophy: Yes. AgentBox values simplicity and automatic behavior. A global .env in ~/.agentbox/ is intuitive (same location as ssh keys, caches, history) and eliminates per-project configuration boilerplate for shared credentials.
• Real use case: Valid for third-party inference providers. Users often need ANTHROPIC_BASE_URL + ANTHROPIC_API_KEY across multiple projects.
• Security: Appropriate. Project override behavior is correct, and adding to .gitignore is standard.
• Discoverability note: Users should see a log message at startup: "Global .env loaded from ~/.agentbox/.env" to aid debugging.

Recommendation: Implement. Low complexity, addresses a real pain point, follows project conventions.

---

Reviewed by: Amp Code

[shrwnsan]

✅ Implementation Complete

This issue has been resolved via PR #8 (merged to dev branch).

What Was Implemented

Global .env file support at ~/.agentbox/.env that loads before project-specific .env files.

Example use case:

# ~/.agentbox/.env
ANTHROPIC_BASE_URL=https://api.example.com/v1
ANTHROPIC_API_KEY=your-shared-key-here

Loading order:

1. Global .env (~/.agentbox/.env) - if exists
2. Project .env (PROJECT_DIR/.env) - if exists, overrides global

---

🤖 Generated by Claude Code - GLM 4.7