Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -20,3 +20,5 @@ jobs:
run: cargo test
- if: ${{ !cancelled() }}
run: tests/wrappers/run.sh
- if: ${{ !cancelled() }}
run: tests/service/run.sh
42 changes: 35 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,16 +56,16 @@ Open a new shell, start the proxy on the wrappers' port (`soze --port 48731 ...`
- **Known limit:** the proxy address is fixed when the agent starts. If soze stops mid-session, that session loses its connection; start a new one.
- `agent` (Cursor) gets the proxy only: its host is tunnelled, so nothing is parsed from it.

## The always-on service (macOS)
## The always-on service (macOS and Linux)

A launchd user agent keeps one `soze` running on port 48731, the port the wrappers use. `task dev` listens on 48732, so both can run at once.
A launchd user agent (macOS) or a `systemd --user` unit (Linux) keeps one `soze` running on port 48731, the port the wrappers use. `task dev` listens on 48732, so both can run at once. Linux requires systemd 240 or newer, a reachable user manager/session bus and `/bin/kill` for reload (`procps` on Debian); no root access is needed. Other Linux supervisors are not managed by these tasks.

```sh
task service:install # build the debug binary, copy it into place, rotate the log, (re)start
task service:status # state, pid, and the sha, branch, dirty flag and time of the install
task service:logs # tail -F soze.log
task service:reload # SIGHUP: re-read the live logging settings
task service:restart # kickstart the service
task service:restart # restart the service, cutting in-flight streams
task service:uninstall # stop and remove the service and binary
```

Expand All @@ -74,18 +74,45 @@ Layout, all under your home directory:
| Path | Holds |
| --- | --- |
| `~/Library/LaunchAgents/com.killallgit.soze.plist` | the launchd job, label `com.killallgit.soze` |
| `~/.config/systemd/user/soze.service` | the Linux user unit (`$XDG_CONFIG_HOME/systemd/user/` if set) |
| `~/.local/share/soze/bin/soze`, `bin/install.json` | the installed binary and what it was built from |
| `~/.local/share/soze/logs/soze.log`, `soze.log.1` | the service's stdout and stderr, and the previous generation |
| `~/.local/share/soze/tap.jsonl`, `shapes.jsonl`, `debug.jsonl` | the tap, shape and debug files |
| `~/.config/soze/config.toml` | settings; written on first install with `log_format = "human"` and `live = true`, never overwritten |

- **Update the service** by re-running `task service:install`. It rebuilds the debug binary, copies it over the installed one, moves `soze.log` to `soze.log.1`, and restarts the service.
- **Linux startup and recovery.** Installation enables `soze.service` for user-manager startup, normally at login. It runs continuously, without socket activation, and restarts on failure after five seconds. To run from boot and after logout, explicitly opt into lingering with `loginctl enable-linger "$USER"` (authorization depends on your system). The installer never enables lingering or changes system proxy/certificate trust settings.
- **Linux unit paths.** The unit directory must be in the running user manager's search path. Install and uninstall reject caller-only overrides and a different same-named loaded definition before changing the installation.
- **Restart is abrupt.** In-flight streams are cut and agents must reconnect. The new process has a new `run_id`, which marks the restart in the tap.
- **Logs.** `task service:logs` tails `soze.log` only. It never reads the tap, because message content must not reach a terminal.
- **Uninstall** removes the plist, binary and `install.json`, and keeps captures, logs and config. `task service:uninstall -- --purge` also lists every path under `~/.local/share/soze/`, then deletes the directory; `~/.config/soze` stays.
- **Uninstall** stops and removes the supervisor definition, binary and `install.json` (and disables the Linux unit), keeping captures, logs and config. `task service:uninstall -- --purge` also lists every path under `~/.local/share/soze/`, then deletes the directory; `~/.config/soze` stays. Linux uninstall requires a reachable user manager when the unit is installed. It does not change lingering, which may support other user services.
- **`live = true` in `config.toml`** applies to `task dev` too, so `LIVE=0 task dev` no longer turns live lines off. Pass `-- --live=false`, or edit the file.
- **Smoke test.** `task test:smoke` checks that the installed service is running, accepts connections, proxies one `claude -p` call and captures it in the tap without new `connect_failed` lines; it needs the installed service and a logged-in `claude`, and prints counts and ids only.
- **Tests.** The service tests in `tests/service/` are local shell tests with a fake `launchctl`. `task check` runs them; CI does not.
- **Tests.** `tests/service/` exercises both platforms with fake `launchctl`, `systemctl` and throwaway homes, without changing the installed service. `task check` and Linux CI run them.

### Test real systemd with Docker

```sh
docker context show # check which Docker host will run the privileged test container
task test:systemd
```

This is a **test image, not a deployment image**. Production Soze remains a native host
service. The target builds the actual debug Linux binary, boots systemd as PID 1, starts a
non-root user manager and tests installation, enablement, status, synthetic proxy traffic,
SIGHUP reload, restart, crash recovery, update, uninstall and purge.

Use a trusted, rootful Linux Docker daemon with cgroup v2. The container runs with
`--privileged` and a private cgroup namespace so systemd can manage its hierarchy; this is
not a security sandbox. No host directories or Docker socket are mounted, no ports are
published, and runtime networking is disabled except for container loopback. A Dockerfile-specific
allowlist excludes captures, credentials, Git/Beads state and agent folders from the build context.

Each invocation tests its own immutable image, even when builds run concurrently. Commands
are bounded, and cleanup removes the container on success, failure or interruption, including
its scratch captures and CA. Failed cleanup is reported. The test image/build cache remains available
for subsequent runs. This opt-in target is separate from `task check` and the mocked service
tests in CI.

## Configuration

Expand Down Expand Up @@ -134,7 +161,7 @@ Terminal stream detail has a budget of 20 records per one-second window; summari

Every dev task also writes `target/dev/debug.jsonl` through a separate logger transport. It resets when the service starts, always selects debug metadata (even with terminal logging off), and does not apply the terminal rate filter. It includes full run/exchange ids, role counts, status/timing/loss counters, and adapter `decision` reasons. `endpoint` is a known API route or `other`; arbitrary paths and query values are excluded. New files are created with mode `0600`. The binary enables this transport with `--log-file <path>`; its parent directory must already exist. Starting a second service on an occupied port leaves the active debug file intact. A debug file cannot alias the tap or shape file, including through dangling symbolic links.

The debug file stops accepting records at 16 MiB per run and reports `debug_file_limit` on stderr; it resumes after the next start resets the file. Open/write/flush failures also report safe diagnostics on stderr while the proxy keeps running. Its independent 256-record queue can drop under load, and abrupt shutdown may lose queued records. This is a disposable debug log, not a durable audit trail. The tap and shape files are bounded separately (see [The tap file](#the-tap-file)); the debug file and `soze.log` (launchd stderr, rotated one generation by the service install) are excluded from that retention.
The debug file stops accepting records at 16 MiB per run and reports `debug_file_limit` on stderr; it resumes after the next start resets the file. Open/write/flush failures also report safe diagnostics on stderr while the proxy keeps running. Its independent 256-record queue can drop under load, and abrupt shutdown may lose queued records. This is a disposable debug log, not a durable audit trail. The tap and shape files are bounded separately (see [The tap file](#the-tap-file)); the debug file and `soze.log` (supervised stdout/stderr, rotated one generation by the service install) are excluded from that retention.

```sh
tail -f target/dev/debug.jsonl # metadata only; safe to inspect while developing
Expand Down Expand Up @@ -183,7 +210,8 @@ Run `task --list`. Tasks run from any directory in the repo.
- `task dev:stream:json`: real-time metadata as JSON logs.
- `task test:smoke`: one real `claude` call through the installed always-on service; local only, not part of `task check`.
- `task test:wrappers`: shell tests for the wrappers and their installer, run under every shell installed. `task check` runs them too.
- `task service:install`, `service:status`, `service:logs`, `service:reload`, `service:restart`, `service:uninstall`: the always-on macOS service, see above.
- `task test:systemd`: build and exercise the native Linux user service under real systemd in a disposable privileged Docker container; opt-in, see above.
- `task service:install`, `service:status`, `service:logs`, `service:reload`, `service:restart`, `service:uninstall`: the always-on macOS or Linux user service, see above.

## Build disk use

Expand Down
7 changes: 6 additions & 1 deletion Taskfile.yml
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,11 @@ tasks:
cmds:
- tests/wrappers/run.sh

test:systemd:
desc: Build a debug Linux binary and test its real systemd user service in a disposable privileged Docker container
cmds:
- sh tests/systemd/run.sh

test:smoke:
desc: Check the installed always-on service with one real claude call; needs the service and a logged-in claude
cmds:
Expand Down Expand Up @@ -57,7 +62,7 @@ tasks:
- scripts/dev.sh --stream --log-format json {{.CLI_ARGS}}

service:install:
desc: Build the debug binary, install it as the always-on macOS service on port 48731, and restart it
desc: Build the debug binary, install it as a macOS or Linux user service on port 48731, and restart it
vars:
BINARY:
sh: cargo metadata --format-version 1 --no-deps | jq -r '.target_directory + "/debug/soze"'
Expand Down
63 changes: 52 additions & 11 deletions docs/architecture/service-lifecycle.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,16 +7,20 @@ architecture diagram and capture pipeline.

## Platform support

**macOS service management is implemented. Linux service management is proposed, not
implemented.** The current installer calls `launchctl` directly; `task service:*` is not a
cross-platform service interface.

| Concern | Current macOS behavior | Proposed Linux equivalent |
`task service:*` manages a macOS LaunchAgent or a Linux systemd user unit. Linux requires
systemd 240 or newer (for file-log append support), a reachable user manager/session bus
and `/bin/kill` for reload (`procps` on Debian).
The installer checks manager access, unit-directory visibility and any loaded definition's
identity before changing installed files. A custom `XDG_CONFIG_HOME` must agree with the
running user manager's unit search path and cannot select a shadowed, same-named unit.
The effective definition is checked again before restart. No root access is needed.

| Concern | macOS | Linux |
| --- | --- | --- |
| Supervisor | `launchd` user LaunchAgent | `systemd --user` service |
| Definition | `~/Library/LaunchAgents/com.killallgit.soze.plist` | `~/.config/systemd/user/soze.service` |
| Definition | `~/Library/LaunchAgents/com.killallgit.soze.plist` | `${XDG_CONFIG_HOME:-$HOME/.config}/systemd/user/soze.service` |
| Startup | GUI user login; job uses `RunAtLoad` | User-manager startup, normally login |
| Automatic recovery | `KeepAlive` | `Restart=on-failure` with a restart delay |
| Automatic recovery | `KeepAlive` | `Restart=on-failure`, five-second delay |
| Run without a login session | Not supplied by the current GUI-domain installer | Explicitly enable user lingering |
| Logging reload | SIGHUP | SIGHUP through `ExecReload` |

Expand All @@ -27,9 +31,9 @@ service backend is implemented; the foreground binary can be managed by another
One service per user avoids sharing CA private keys and captured conversations across users.
The default port is still shared by the machine: two users cannot both bind
`127.0.0.1:48731`. Multi-user deployment would need distinct ports and matching wrapper
settings; the macOS installer currently fixes its service port at 48731.
settings; both installers currently fix the service port at 48731.

## macOS operations
## Service operations

Run these commands from a checkout with Task installed:

Expand All @@ -42,6 +46,17 @@ task service:restart # abruptly restart the process
task service:uninstall # remove the job and binary; keep captures, logs and config
```

Linux installation writes `soze.service`, reloads the user manager, enables the unit for
`default.target` and restarts it. It runs the foreground binary continuously, not through
socket activation. stdout and stderr append to the same `soze.log` used on macOS; the logs
command does not read journald or capture output. New Linux directories and non-executable
files are private to the user, and the unit applies `UMask=0077` to runtime files.

To keep the Linux user manager running from boot and after logout, explicitly enable
lingering with `loginctl enable-linger "$USER"`; authorization depends on local policy.
Installation and removal never change lingering, which can also support other user services.
Without it, service lifetime follows the system's user-manager/session policy.

Installation copies the binary to `~/.local/share/soze/bin/soze`, so changing checkout branches
or rebuilding a development binary does not replace the running installation. Re-running
`task service:install` updates the installed binary and restarts the service. It records the
Expand All @@ -64,6 +79,7 @@ Use `SOZE_PORT=48732` when launching a wrapped agent against the development pro
| Path | Contents |
| --- | --- |
| `~/Library/LaunchAgents/com.killallgit.soze.plist` | macOS supervisor definition |
| `~/.config/systemd/user/soze.service` | Linux supervisor definition; follows `XDG_CONFIG_HOME` if set |
| `~/.local/share/soze/bin/soze` | Installed executable |
| `~/.local/share/soze/bin/install.json` | Installed-build provenance |
| `~/.local/share/soze/tap.jsonl` and numbered segments | Captured events, content, records and graph edges |
Expand All @@ -77,7 +93,10 @@ The first install creates `config.toml` with `log_format = "human"` and `live =
file is absent. Later installs preserve it. The CA is made on the binary's first run, not
installed into a trust store.

Normal uninstall keeps captures, logs, configuration and CA material.
Normal uninstall keeps captures, logs, configuration and CA material. On Linux it first
verifies that the caller's unit path matches the manager's loaded definition, then disables
and stops the unit before deleting it and reloading the manager. A mismatched path or stop
failure aborts removal, so files are not deleted from underneath a possibly running service.
`task service:uninstall -- --purge` additionally lists and deletes the entire
`~/.local/share/soze/` directory. It still keeps `~/.config/soze/`.

Expand Down Expand Up @@ -109,7 +128,7 @@ subcommands and exposes no management or health API.

| Information | Available interface |
| --- | --- |
| Supervisor state and PID | `task service:status`, macOS only |
| Supervisor state and PID | `task service:status`, macOS and Linux |
| Installed source SHA, branch, dirty flag and installation time | Same command, from `bin/install.json` |
| Content-free operational activity | `task service:logs` |
| Capture and log disk usage | Filesystem tools; no built-in aggregate report |
Expand All @@ -119,6 +138,28 @@ Supervisor state and a listening TCP port do not prove successful upstream reque
complete capture. The existing status command reports the supervisor and installation, not
an application-level health assessment.

Linux status maps systemd's service substate to `state` (for example, `running`, `dead` or
`failed`), reports an empty PID when no process is running, and uses `not loaded` for a missing
unit. An unreachable user manager fails the command rather than looking like an absent unit.

## Testing supervision

`task check` and Linux CI run isolated shell tests of both service backends using fake OS
commands. `task test:systemd` separately builds a debug Linux binary and boots a disposable
systemd Docker image, exercising the real installer and proxy under a non-root user manager.
It checks enablement, state/PID, proxy forwarding, reload, restart, automatic recovery,
update and retained data after uninstall, followed by purge.

Docker is only the integration-test environment; it does not replace native host supervision.
The test needs a trusted rootful Linux Docker daemon with cgroup v2 and uses a privileged
container with a private cgroup namespace. No host directories or sockets are mounted, no
ports are published and runtime networking is loopback-only. The container and its generated
capture/CA files are removed after the test. See the [Docker test
instructions](../../README.md#test-real-systemd-with-docker) before running against a local or
remote Docker context.

## Inspecting disk usage

These commands report disk usage without printing captured content:

```sh
Expand Down
17 changes: 7 additions & 10 deletions docs/architecture/system-overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,8 @@ Soze is a local, per-user HTTPS proxy with a non-blocking capture pipeline. Codi
communicate with their providers through it; a separate tap converts copied traffic into the
[common event format](../common-format.md).

This document describes the current implementation. The Linux service supervisor in the
diagram is a proposal, not an implemented service backend. See [service lifecycle and
storage](service-lifecycle.md) for platform behavior, commands and retention.
This document describes the current implementation. See [service lifecycle and
storage](service-lifecycle.md) for macOS and Linux platform behavior, commands and retention.

## Architecture diagram

Expand Down Expand Up @@ -35,7 +34,7 @@ flowchart TB
ShapeFiles[("Shape files<br/>shapes.jsonl + rotated segments")]
LogFiles[("Operational and debug logs<br/>soze.log · debug.jsonl")]
Mac["macOS launchd LaunchAgent<br/>Implemented"]
Linux["Linux systemd user service<br/>Proposed, not implemented"]
Linux["Linux systemd user service<br/>Implemented"]

Wrappers -->|"Launch with environment settings"| Agents
Agents <-->|"HTTPS CONNECT"| Listener
Expand All @@ -55,20 +54,18 @@ flowchart TB
Config --> Service
CA --> Intercept
Mac -->|"Start and supervise"| Service
Linux -.->|"Proposed supervision"| Service
Linux -->|"Start and supervise"| Service
end

Models["Model APIs<br/>Anthropic · OpenAI / ChatGPT"]
Other["Other destinations<br/>Including Cursor servers"]
Intercept <-->|"Upstream TLS"| Models
Tunnel <-->|"Encrypted traffic"| Other

classDef proposed fill:#fff4d6,stroke:#9a6700,stroke-dasharray:5 5;
class Linux proposed;
```

Dashed data-path arrows show copied traffic, observations or metadata, not forwarding
dependencies. The separately styled Linux supervisor is the only proposed component.
dependencies.
The diagram groups related responsibilities; it is not a task-by-task execution graph.

## Agent integration
Expand Down Expand Up @@ -137,10 +134,10 @@ the proxy from starting.

Soze is one Rust crate and one binary. It does not own the agent's tool-execution loop or run
the model. The intended service deployment is one proxy per user, without root privileges;
the current installer implements that on macOS only.
the installer implements that on macOS and Linux with systemd.

The CLI starts the proxy and accepts configuration flags, but has no status, storage-usage or
session-listing subcommands. The macOS task commands query the supervisor separately; see
session-listing subcommands. The service task commands query the supervisor separately; see
[management and visibility](service-lifecycle.md#management-and-visibility).

How other applications receive the common format remains undecided. This architecture assumes
Expand Down
Loading
Loading