Skip to content

feature implementation: gateway daemon commands#737

Closed
vvr3ddy wants to merge 4 commits intosipeed:mainfrom
vvr3ddy:feat/gateway-daemon-commands
Closed

feature implementation: gateway daemon commands#737
vvr3ddy wants to merge 4 commits intosipeed:mainfrom
vvr3ddy:feat/gateway-daemon-commands

Conversation

@vvr3ddy
Copy link

@vvr3ddy vvr3ddy commented Feb 24, 2026

Add start, stop, restart, and status commands for running the gateway as a background daemon with automatic crash recovery.

This allows the gateway to run without occupying a terminal, making it suitable for production deployments on resource-constrained hardware like Raspberry Pi.

Features:

  • Daemon mode with PID file management
  • Auto-restart with exponential backoff (3 attempts, 5-min window)
  • File logging with automatic rotation (100MB, 3 backups)
  • Status tracking (PID, uptime, restart count)
  • Graceful shutdown with SIGTERM handling

New commands:

  • picoclaw gateway start # Start as daemon
  • picoclaw gateway stop # Stop daemon
  • picoclaw gateway restart # Restart with auto-recovery
  • picoclaw gateway status # Show daemon status

Architecture:

  • New pkg/daemon package following existing service patterns
  • Atomic state persistence (temp file + rename)
  • Thread-safe operations with mutex protection
  • Cross-platform support (Linux, macOS, ARM64, x86_64)

📝 Description

🗣️ Type of Change

  • 🐞 Bug fix (non-breaking change which fixes an issue)
  • ✨ New feature (non-breaking change which adds functionality)
  • 📖 Documentation update
  • ⚡ Code refactoring (no functional changes, no api changes)

🤖 AI Code Generation

  • 🤖 Fully AI-generated (100% AI, 0% Human)
  • 🛠️ Mostly AI-generated (AI draft, Human verified/modified)
  • 👨‍💻 Mostly Human-written (Human lead, AI assisted or none)

🔗 Related Issue

📚 Technical Context (Skip for Docs)

  • Reference URL:
  • Reasoning:

🧪 Test Environment

  • Hardware: Raspberry 4b 8GB
  • OS: RaspberryOS Lite Bookworm 64-bit (arm64)
  • Model/Provider:
  • Channels:

📸 Evidence (Optional)

Click to view Logs/Screenshots

Logs Here

make install
Run generate...
Run generate complete
Building picoclaw for linux/arm64...
github.com/sipeed/picoclaw/pkg/daemon
github.com/sipeed/picoclaw/cmd/picoclaw
Build complete: build/picoclaw-linux-arm64
Installing picoclaw...
# Copy binary with temporary suffix to ensure atomic update
Installed binary to /home/vvr3ddy/.local/bin/picoclaw
Installation complete!
vvr3ddy@reggie:~/picoclaw $ picoclaw gateway status
🦞 PicoClaw Gateway Status
Version: v0.1.2-225-g072c4f9 (git: 072c4f9a)

Status: Stopped

Use 'picoclaw gateway start' to start the gateway
vvr3ddy@reggie:~/picoclaw $ picoclaw status
🦞 picoclaw Status
Version: v0.1.2-225-g072c4f9 (git: 072c4f9a)
Build: 2026-02-24T18:35:33+0000

Config: /home/vvr3ddy/.picoclaw/config.json ✓
Workspace: /home/vvr3ddy/.picoclaw/workspace ✓
Model: gemini-flash
OpenRouter API: not set
Anthropic API: not set
OpenAI API: not set
Gemini API: not set
Zhipu API: not set
Qwen API: not set
Groq API: not set
Moonshot API: not set
DeepSeek API: not set
VolcEngine API: not set
Nvidia API: not set
vLLM/Local: not set
Ollama: not set

OAuth/Token Auth:
  google-antigravity (oauth): authenticated
vvr3ddy@reggie:~/picoclaw $ picoclaw gateway start
🦞 Starting PicoClaw Gateway...
2026/02/24 18:35:51 [2026-02-24T18:35:51Z] [INFO] daemon: Starting gateway daemon {version=v0.1.2-225-g072c4f9 (git: 072c4f9a), binary=/home/vvr3ddy/.local/bin/picoclaw}
2026/02/24 18:35:51 [2026-02-24T18:35:51Z] [INFO] daemon: Gateway daemon started {pid=2530, version=v0.1.2-225-g072c4f9 (git: 072c4f9a)}
✓ Gateway started successfully
  PID: 2530
  Log: /home/vvr3ddy/.picoclaw/gateway.log

Use 'picoclaw gateway status' to check the gateway status
Use 'picoclaw gateway stop' to stop the gateway
vvr3ddy@reggie:~/picoclaw $ picoclaw gateway restart
🦞 Restarting PicoClaw Gateway...
2026/02/24 18:35:58 [2026-02-24T18:35:58Z] [INFO] daemon: Restarting gateway daemon
2026/02/24 18:35:58 [2026-02-24T18:35:58Z] [INFO] daemon: Stopping gateway daemon
2026/02/24 18:35:58 [2026-02-24T18:35:58Z] [INFO] daemon: Gateway daemon stopped {pid=2530}
2026/02/24 18:35:58 [2026-02-24T18:35:58Z] [INFO] daemon: Gateway daemon started {pid=2545, version=v0.1.2-225-g072c4f9 (git: 072c4f9a)}
2026/02/24 18:35:58 [2026-02-24T18:35:58Z] [INFO] daemon: Gateway daemon restarted successfully
✓ Gateway restarted successfully
  PID: 2545
  Restart count: 0
  Log: /home/vvr3ddy/.picoclaw/gateway.log
vvr3ddy@reggie:~/picoclaw $ picoclaw gateway start
🦞 Starting PicoClaw Gateway...
2026/02/24 18:36:03 [2026-02-24T18:36:03Z] [INFO] daemon: Starting gateway daemon {version=v0.1.2-225-g072c4f9 (git: 072c4f9a), binary=/home/vvr3ddy/.local/bin/picoclaw}
✗ Gateway is already running with PID 2545

Use 'picoclaw gateway status' for more information
vvr3ddy@reggie:~/picoclaw $ picoclaw gateway status
🦞 PicoClaw Gateway Status
Version: v0.1.2-225-g072c4f9 (git: 072c4f9a)

Status: Running
  PID: 2545
  Started: 2026-02-24 18:35:58
  Uptime: 10.915233419s
  Version: v0.1.2-225-g072c4f9 (git: 072c4f9a)

Log file: /home/vvr3ddy/.picoclaw/gateway.log

☑️ Checklist

  • My code/docs follow the style of this project.
  • I have performed a self-review of my own changes.
  • I have updated the documentation accordingly.

Add start, stop, restart, and status commands for running the gateway
as a background daemon with automatic crash recovery.

This allows the gateway to run without occupying a terminal, making
it suitable for production deployments on resource-constrained
hardware like Raspberry Pi.

Features:
- Daemon mode with PID file management
- Auto-restart with exponential backoff (3 attempts, 5-min window)
- File logging with automatic rotation (100MB, 3 backups)
- Status tracking (PID, uptime, restart count)
- Graceful shutdown with SIGTERM handling

New commands:
- picoclaw gateway start    # Start as daemon
- picoclaw gateway stop     # Stop daemon
- picoclaw gateway restart  # Restart with auto-recovery
- picoclaw gateway status   # Show daemon status

Architecture:
- New pkg/daemon package following existing service patterns
- Atomic state persistence (temp file + rename)
- Thread-safe operations with mutex protection
- Cross-platform support (Linux, macOS, ARM64, x86_64)
The Write() method was using os.Getpid() which writes the parent's PID
instead of the spawned child process PID. Added WritePID() method to
explicitly write a specific PID and added process verification after spawn.
The Restart() method was acquiring a lock then calling Stop() which
tried to acquire the same lock, causing a deadlock.

Fixed by creating stopLocked() method that assumes lock is already held,
and having Restart() call stopLocked() directly.
The Restart() method was calling startInternal() which waits for
the gateway to exit. This is wrong for manual restart commands.

Fixed by:
- Creating startLocked() that starts and returns immediately
- Having Restart() call startLocked() for immediate return
- Adding RunWithAutoRestart() for crash monitoring with retry

Now manual 'picoclaw gateway restart' works as expected:
stops the gateway, starts it, and returns immediately.
@vvr3ddy vvr3ddy changed the title Feat/gateway daemon commands feature implementation: gateway daemon commands Feb 24, 2026
@vvr3ddy vvr3ddy mentioned this pull request Feb 24, 2026
@vvr3ddy vvr3ddy force-pushed the feat/gateway-daemon-commands branch 2 times, most recently from bf8fac0 to 072c4f9 Compare February 24, 2026 19:06
@keithy
Copy link

keithy commented Feb 25, 2026

Suggestion, in the context of a fully featured linux host.

  1. picoclaw can be installed using mise-en-place
mise use github:sipeed/picoclaw@latest
  1. Is the daemon/service installation an OS dependency, rather than a picoclaw one?
  2. If the OS supports it the daemon can be managed by systemd.
  3. Perhaps mise-en-place can be configured with some tasks for installing the daemon.

@xiaket xiaket added the type: enhancement New feature or request label Feb 25, 2026
@xiaket
Copy link
Collaborator

xiaket commented Feb 25, 2026

Thanks for your contribution! With #429 merged in, this may need a big change. :(

@vvr3ddy
Copy link
Author

vvr3ddy commented Feb 26, 2026

I will reference this in a new PR then :)

@vvr3ddy
Copy link
Author

vvr3ddy commented Feb 26, 2026

Thanks for your contribution! With #429 merged in, this may need a big change. :(

Here is the new PR: #810

Closing this one down

@vvr3ddy vvr3ddy closed this Feb 26, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

type: enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants