harivansh-afk/sandbox-agent
1
0
Fork 0
mirror of https://github.com/harivansh-afk/sandbox-agent.git synced 2026-04-15 07:04:48 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

chore: fix bad merge

Browse source
This commit is contained in:
Nathan Flurry 2026-02-11 07:52:48 -08:00
parent 1dd45908a3
commit 94353f7696
205 changed files with 19244 additions and 14866 deletions
Download patch file Download diff file Expand all files Collapse all files

71
docs/daemon.mdx
View file

@ -1,96 +1,69 @@
---
title: "Daemon"
description: "Background daemon lifecycle, auto-upgrade, and management."
icon: "microchip"
description: "Background daemon lifecycle and management."
---
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.
The sandbox-agent daemon is a background server process. Commands like `sandbox-agent opencode` and `gigacode` can ensure it is running.
## 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.
1. A daemon-aware command checks for a healthy daemon at host/port.
2. If missing, it starts one in the background and records PID/version files.
3. Subsequent checks can compare build/version and restart when required.
## Auto-upgrade
## Auto-upgrade behavior
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.
- `sandbox-agent opencode` and `gigacode` use ensure-running behavior with upgrade checks.
- `sandbox-agent daemon start` uses direct start by default.
- `sandbox-agent daemon start --upgrade` uses ensure-running behavior (including version check/restart).
## 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 |
| `-H, --host <HOST>` | `127.0.0.1` | Host |
| `-p, --port <PORT>` | `2468` | Port |
| `--upgrade` | false | Use ensure-running + upgrade behavior |
```bash
sandbox-agent daemon start --no-token
sandbox-agent daemon start
sandbox-agent daemon start --upgrade
```
### 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
```
| `-H, --host <HOST>` | `127.0.0.1` | Host |
| `-p, --port <PORT>` | `2468` | Port |
### 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.
| `-H, --host <HOST>` | `127.0.0.1` | Host |
| `-p, --port <PORT>` | `2468` | Port |
## Files
All daemon state files live under the sandbox-agent data directory (typically `~/.local/share/sandbox-agent/daemon/`):
Daemon state is stored under the sandbox-agent data directory (for example `~/.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.
| `daemon-{host}-{port}.pid` | PID of running daemon |
| `daemon-{host}-{port}.version` | Build/version marker |
| `daemon-{host}-{port}.log` | Daemon stdout/stderr log |