avizmarlon/local-service-autostart

Principle: Remediate offline local services programmatically

When an AI agent depends on a local service (Ollama, Docker, PostgreSQL, Redis, etc.) and the service is offline or unreachable, the agent should start the service programmatically and retry the operation. This is operational work (typically one command), not a blocking issue requiring human intervention.

Do not report offline services as blockers or ask the user to start them manually. That violates the agent-as-operator principle: the agent is responsible for keeping operational dependencies running, within scope of already-installed services.

Detection

Common error patterns indicating an offline service:

• ConnectionError, Connection refused, Connection timeout
• Failed to connect to <service>, Cannot connect to daemon
• Port <N> is not listening, Service unavailable
• Daemon not running, Service offline
• ECONNREFUSED, EHOSTUNREACH, ENETUNREACH

Remediation pattern

Step 1: Detect — catch the connection error or verify service is offline via a health check (e.g., curl, nc, or language-specific client library).

Step 2: Start — invoke the service startup command appropriate to your OS and environment. Examples:

| Service | OS | Startup command | Health check | |---|---|---|---| | Ollama | macOS | open /Applications/Ollama.app | curl -s http://localhost:11434/api/tags | | Ollama | Linux | systemctl start ollama or ollama serve (foreground) | curl -s http://localhost:11434/api/tags | | Ollama | Windows | cmd.exe /c start "" "C:\Program Files\Ollama\ollama app.exe" | curl -s http://localhost:11434/api/tags | | Docker Desktop | macOS | open /Applications/Docker.app | docker version | | Docker Desktop | Windows | cmd.exe /c start "" "C:\Program Files\Docker\Docker\Docker Desktop.exe" | docker version | | PostgreSQL (local) | Linux | systemctl start postgresql or pg_ctl start | pg_isready -h localhost | | PostgreSQL (local) | macOS | brew services start postgresql | pg_isready -h localhost | | Redis | Linux/macOS | redis-server (foreground) or systemctl start redis | redis-cli ping |

Step 3: Wait — allow the service time to initialize. Typical values:

• Ollama: ~5 seconds
• Docker Desktop: ~30 seconds
• PostgreSQL: ~2–5 seconds
• Redis: ~1 second

Step 4: Verify — run the health check command and confirm the service is responding.

Step 5: Retry — attempt the original operation again.

Implementation approach

try:
    result = client.call(service_endpoint)
except ConnectionError as e:
    log("Service offline: {e}")
    start_service(service_name)
    wait(service_startup_time)
    verify_service_health()
    result = client.call(service_endpoint)  # retry

Anti-patterns (prohibited)

• "Service is offline, I cannot proceed" → prohibited. Start the service and continue.
• "User should start the service manually" → prohibited. This is agent work, not user work.
• Infinite retry loop without attempting startup → prohibited. Attempt startup once, wait, health-check once, then fail if the service does not respond.
• Treating service startup as a user prompt / decision → prohibited. Service startup is a given operational fact, not a choice to present.

Scope boundaries

In scope:

• Starting services that are already installed on the user's machine.
• Restarting crashed or hung services.
• Health checking and waiting for service readiness.
• Retrying the operation after successful startup.

Out of scope:

• Installing the service if it is not present (ask the user or fail with clear installation instructions).
• Fixing configuration errors unrelated to the service being down.
• Diagnosing why the service crashed (log that, but still start it).
• Making decisions about whether a service should be running (assume it should).

Applies to

All AI agent implementations (Claude, Codex, Cursor, Gemini, etc.) across all projects. This is a standard operational pattern, not project-specific.