mirror of
https://github.com/harivansh-afk/sandbox-agent.git
synced 2026-04-15 16:04:06 +00:00
96 lines
3.4 KiB
Text
96 lines
3.4 KiB
Text
---
|
|
title: "Daemon"
|
|
description: "Background daemon lifecycle, auto-upgrade, and management."
|
|
icon: "microchip"
|
|
---
|
|
|
|
The sandbox-agent daemon is a background server process that stays running between sessions. Commands like `sandbox-agent opencode` and `gigacode` automatically start it when needed and restart it when the binary is updated.
|
|
|
|
## How it works
|
|
|
|
1. When you run `sandbox-agent opencode`, `sandbox-agent daemon start`, or `gigacode`, the CLI checks if a daemon is already healthy at the configured host and port.
|
|
2. If no daemon is running, one is spawned in the background with stdout/stderr redirected to a log file.
|
|
3. The CLI writes a PID file and a build ID file to track the running process and its version.
|
|
4. On subsequent invocations, if the daemon is still running but was built from a different commit, the CLI automatically stops the old daemon and starts a new one.
|
|
|
|
## Auto-upgrade
|
|
|
|
Each build of sandbox-agent embeds a unique **build ID** (the git short hash, or a version-timestamp fallback). When a daemon is started, this build ID is written to a version file alongside the PID file.
|
|
|
|
On every invocation of `ensure_running` (called by `opencode`, `gigacode`, and `daemon start`), the CLI compares the stored build ID against the current binary's build ID. If they differ, the running daemon is stopped and replaced automatically:
|
|
|
|
```
|
|
daemon outdated (build a1b2c3d -> f4e5d6c), restarting...
|
|
```
|
|
|
|
This means installing a new version of sandbox-agent and running any daemon-aware command is enough to upgrade — no manual restart needed.
|
|
|
|
## Managing the daemon
|
|
|
|
### Start
|
|
|
|
Start a daemon in the background. If one is already running and healthy, this is a no-op.
|
|
|
|
```bash
|
|
sandbox-agent daemon start [OPTIONS]
|
|
```
|
|
|
|
| Option | Default | Description |
|
|
|--------|---------|-------------|
|
|
| `-H, --host <HOST>` | `127.0.0.1` | Host to bind to |
|
|
| `-p, --port <PORT>` | `2468` | Port to bind to |
|
|
| `-t, --token <TOKEN>` | - | Authentication token |
|
|
| `-n, --no-token` | - | Disable authentication |
|
|
|
|
```bash
|
|
sandbox-agent daemon start --no-token
|
|
```
|
|
|
|
### Stop
|
|
|
|
Stop a running daemon. Sends SIGTERM and waits up to 5 seconds for a graceful shutdown before falling back to SIGKILL.
|
|
|
|
```bash
|
|
sandbox-agent daemon stop [OPTIONS]
|
|
```
|
|
|
|
| Option | Default | Description |
|
|
|--------|---------|-------------|
|
|
| `-H, --host <HOST>` | `127.0.0.1` | Host of the daemon |
|
|
| `-p, --port <PORT>` | `2468` | Port of the daemon |
|
|
|
|
```bash
|
|
sandbox-agent daemon stop
|
|
```
|
|
|
|
### Status
|
|
|
|
Show whether the daemon is running, its PID, build ID, and log path.
|
|
|
|
```bash
|
|
sandbox-agent daemon status [OPTIONS]
|
|
```
|
|
|
|
| Option | Default | Description |
|
|
|--------|---------|-------------|
|
|
| `-H, --host <HOST>` | `127.0.0.1` | Host of the daemon |
|
|
| `-p, --port <PORT>` | `2468` | Port of the daemon |
|
|
|
|
```bash
|
|
sandbox-agent daemon status
|
|
# Daemon running (PID 12345, build a1b2c3d, logs: ~/.local/share/sandbox-agent/daemon/daemon-127-0-0-1-2468.log)
|
|
```
|
|
|
|
If the daemon was started with an older binary, the status includes an `[outdated, restart recommended]` notice.
|
|
|
|
## Files
|
|
|
|
All daemon state files live under the sandbox-agent data directory (typically `~/.local/share/sandbox-agent/daemon/`):
|
|
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `daemon-{host}-{port}.pid` | PID of the running daemon process |
|
|
| `daemon-{host}-{port}.version` | Build ID of the running daemon |
|
|
| `daemon-{host}-{port}.log` | Daemon stdout/stderr log output |
|
|
|
|
Multiple daemons can run on different host/port combinations without conflicting.
|