Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/wuxxin/agents-shared

Sandboxed local AI (openclaw compatible) assistants and inference orchestrator
https://github.com/wuxxin/agents-shared

ai-agents bubblewrap llama-cpp local-llm openclaw orchestration sandboxing signal-cli systemd whisper-cpp

Last synced: 20 days ago
JSON representation

Sandboxed local AI (openclaw compatible) assistants and inference orchestrator

Awesome Lists containing this project

README 

          
# Local Agent Ecosystem & Assistant Orchestrator



This repository is a centralized orchestration hub for deploying, sandboxing, and monitoring local AI assistants, speech-to-text engines, local inference models, and communication integrations. It provides systemd-confinement configurations, bubblewrap (`bwrap`) isolation wrappers, and standardized daemon control utilities (`*-ctl` scripts) to ensure secure and isolated agent execution on Linux while facilitating structured inter-agent collaboration.



## Assistant Software covered in this repository



| Assistant | Language & Runtime | Embedding | Reranking | Search & Retrieval | Signal | STT |

| :--- | :--- | :--- | :--- | :--- | :--- | :--- |

| **[LibreFang](#librefang)** | Rust (Source) 
 Rust Backend + Web GUI | Remote & Local | Native & Local | SQLite & Vector / MCP | Native | Local |

| **[Moltis](#moltis)** | Rust (Source) 
 Rust Backend + Web GUI | Remote, Local & QMD | Native (QMD) & Local | SQLite FTS5 / Vector / Hybrid (QMD) | Native | Local |

| **[ZeroClaw](#zeroclaw)** | Rust (Source) 
 Rust Backend | Remote & Local | Hybrid & Local | SQLite Hybrid (Vector & FTS5) | Native | Local |

| **[IronClaw](#ironclaw)** | Rust (Source) 
 Rust Backend + Web Gateway | Remote & Local | Native (RRF) | PostgreSQL + pgvector / Hybrid (FTS + Vector) | Native | Local |



also covered, but currently not point of interest:



| Assistant | Language & Runtime | Embedding | Reranking | Search & Retrieval | Signal | STT |

| :--- | :--- | :--- | :--- | :--- | :--- | :--- |

| **[Hermes](#hermes)** | Python (Source) 
 frozen Python Backend + Web GUI | Remote & Local | Native & Local | SQLite FTS5 / Vector / RAG | Native | Local |

| **[NanoBot](#nanobot)** | Python (Source) 
 Python CLI (via `uv`) | Remote & Local | Via MCP Tool | RAG / Document Store / MCP | Native | Local |

| **[NanoClaw](#nanoclaw)** | TypeScript (Source) 
 Node.js Webhook Backend | Remote & Local via Tools | Via Custom Skills/MCP | SQLite state / Custom Tools / MCP | No | Via Custom Tools |

| **[PicoClaw](#picoclaw)** | Go (Source) 
 Go Backend + Web GUI | Remote & Local via MCP | Via MCP | JSON state / MCP | No | Via MCP |



## Integrations



### Local LLM and Reranking Services

- **Description**: Manages persistent `llama-server` instances for text completions/embeddings (`local-llm-ggml.sh`) and document reranking (`local-rerank.sh`). Optimized for AMD ROCm hardware (tested on Radeon Pro W6800).

- **Sandboxing**: Requires `PrivateDevices=no` to access `/dev/dri` and `/dev/kfd`. Enforces `ProtectSystem=strict` while bind-mounting the user's home configuration and granting read-write access to `/data/public/machine-learning`.

- **Features**: Flash Attention, layer GPU offloading, combined chat and embeddings (`50080`) running with 3 parallel slots (80,000 tokens context size each, total 240,000 tokens), and separate rerank (`50086`) services.

- Documentation: [local-llm-ggml.md](assistants/local-llm-ggml.md) / [local-rerank.md](assistants/local-rerank.md)



### Local Speech-to-Text

- **Description**: Manages a persistent `whisper-server` instance for speech-to-text (STT) transcription. Serves an OpenAI-compatible audio transcription API on port 50090.

- **Sandboxing**: Requires `PrivateDevices=no` to access `/dev/dri` and `/dev/kfd` for GPU-accelerated transcription. Enforces `ProtectSystem=strict` while allowing read-write access to the home directory (for temporary ffmpeg transcoded files) and read-only access to `/data/public/machine-learning`.

- **Features**: Flash Attention, GPU offloading, audio transcoding using `ffmpeg`.

- Documentation: [local-speech-to-text.md](assistants/local-speech-to-text.md)



### Local Text-to-Speech

- **Description**: Manages a persistent `qwen3-tts-server` instance for text-to-speech (TTS) synthesis. Serves an OpenAI-compatible audio synthesis API on port 50095.

- **Sandboxing**: Requires `PrivateDevices=no` to access `/dev/dri` and `/dev/kfd` for GPU-accelerated synthesis (unless run in `cpu-only` mode). Enforces `ProtectSystem=strict` while restricting filesystem access to the home directory and read-only system files.

- **Features**: Dynamic performance tuning modes (`gpu+max-throughput`, `gpu+min.vram`, `cpu-only`), fully parallelized CPU threading, and streaming/batch PCM generation.

- Documentation: [local-text-to-speech.md](assistants/local-text-to-speech.md)



### Signal Integration

- **Description**: Connects agents to Signal. Runs a `signal-cli` daemon exposing both TCP and HTTP JSON-RPC interfaces. It also provides an optional Go-based REST API wrapper for robust, HTTP-based polling/webhook integrations (like linking LibreFang).

- **Sandboxing**: Standard filesystem hardening, but disables `MemoryDenyWriteExecute` because the underlying JVM (Java) requires it for JIT compilation. 

- **Features**: Account linking via QR code, dual daemon interfaces, and isolated home directory execution to prevent contamination.

- Documentation: [signal-ctl.md](assistants/signal-ctl.md)



The following assistants have native Signal channel integration available in their source code:

- [LibreFang](assistants/librefang-ctl.md)

- [Moltis](assistants/moltis-ctl.md)

- [ZeroClaw](assistants/zeroclaw-ctl.md)

- [IronClaw](assistants/ironclaw-ctl.md)

- [Hermes](assistants/hermes-ctl.md)

- [NanoBot](assistants/nanobot-ctl.md)



To configure them, refer to their specific configuration sections in their respective control guides.



## Default Ports



The following default ports are used by various agent systems and services to avoid conflicts. When integrating new agents, ensure their configured `PORT` or `WEBHOOK_PORT` does not overlap with existing infrastructure.



| Agent/Service | Default Port(s) | Description / Protocol |

|---------------|-----------------|------------------------|

| **Local-LLM** | [50080](http://localhost:50080) | Llama-server serving Chat/Vision LLM & Text Embeddings |

| **Local-Rerank** | [50086](http://localhost:50086) | Llama-server serving Document Reranking |

| **Local-Speech-To-Text** | [50090](http://localhost:50090) | Whisper-server audio transcription API (HTTP) |

| **Local-Text-to-Speech** | [50095](http://localhost:50095) | Qwen3-tts-server audio synthesis API (HTTP) |

| **Signal-CLI** | [50889](http://localhost:50889) (optional: `50887`, `50888`) | REST API (TCP/HTTP JSON-RPC disabled by default in favor of secure UNIX socket) |

| **LibreFang** | [4545](http://localhost:4545) | LibreFang daemon API (HTTP) |

| **Moltis** | [13131](https://localhost:13131) | Moltis agent server Web UI/API (HTTPS) |

| **ZeroClaw** | [42617](http://localhost:42617) | ZeroClaw Gateway |

| **IronClaw** | [8080](http://localhost:8080) | IronClaw Web Gateway & HTTP Webhooks |

| **Hermes** | [8000](http://localhost:8000), [8642](http://localhost:8642), [9119](http://localhost:9119) | Hermes Messaging Gateway (API: 8642, UI: 9119) |

| **NanoBot** | [8790](http://localhost:8790) | NanoBot Gateway API |

| **NanoClaw** | [3000](http://localhost:3000) | Webhook Server |

| **PicoClaw** | [18790](http://localhost:18790), [18800](http://localhost:18800) | Gateway (HTTP/Webhook) & Launcher Web UI |



## Sandboxing Architecture



Agent runtimes in this repository operate under strict, layered sandboxing configurations via systemd user services to protect the host system while allowing agents to execute their tools securely. 



Two primary isolation profiles are used across all assistants:



### Strict Confinement Profile

Used by agents that execute tools directly or do not require creating new user namespaces for their internal sandboxing.

- `ProtectProc=invisible` and `ProcSubset=pid`: Hides other system processes.

- `RestrictNamespaces=yes`: Prevents the creation of new namespaces.

- `MemoryDenyWriteExecute=yes`: Prevents W^X memory mappings (unless specifically required by an interpreter).

- `PrivateTmp=yes`, `ProtectSystem=strict`, `PrivateDevices=yes`: Standard filesystem hardening.



### Relaxed Namespaces Profile

Used by agents that orchestrate sub-agents or use tools like Bubblewrap (`bwrap`), Rootless Podman, or Docker for internal sandboxing.

- `RestrictNamespaces=yes` is **omitted** to allow `bwrap` or Podman to create `CLONE_NEWUSER` and `CLONE_NEWNS` unprivileged namespaces.

- `ProtectProc=invisible` and `ProcSubset=pid` are **omitted** so `bwrap` can securely bind its own `/proc` filesystem.

- `NoNewPrivileges=yes` is maintained for modern `bwrap` compatibility.

- `PrivateDevices` may be disabled (`no`) if access to the container daemon or GPU devices is required.



---



## Assistants



### LibreFang

- **Major Features**: Hardened Agent OS daemon providing isolated execution environments and coordinating complex multi-agent workflows. It is a community fork of the former OpenFang project (which had 17,623 stars and 2,252 forks before going stale).

- **Language/Runtime**: Rust (Source) / Compiled binary (Rust Backend + Web-based Dashboard GUI).

- **Signal Support**: Yes — Native integration (interfaces with the Go REST API wrapper).

- **Coding Agent Support**: Yes — Supports Claude Code, Aider, Qwen Code, Gemini CLI, and Codex CLI (spawned as subprocesses; No OpenCode support).

- **LLM Inference via Agent Proxy**: None.

- **Requirements**: `~/.local/sandbox/librefang` and `~/agent-shared`.

- **Sandboxing**: **Relaxed Namespaces Profile** to support bubblewrap (`bwrap`) nested sandboxing for sub-agents. Read-only system paths and strict filesystem protection for the host.

- **Search & Retrieval**: Native integration of SQLite and vector storage for persistent agent memories and knowledge retrieval. Built-in scheduling and task memory, which allows agents to run 24/7 and store OSINT/research search results in the native database. Can connect to external databases via MCP (Model Context Protocol).

- **Embedding Options**: Supports embedding generation via 27 supported LLM/embedding providers (OpenAI-compatible, Cohere, Anthropic, etc.). Can leverage system-wide local embeddings via the `local-llm-ggml` server.

- **Reranking Support**: None. Reranking is not supported by the LibreFang daemon.

- **STT/TTS Support**: Hardcoded to cloud APIs by default. Custom local STT (whisper-server on port 50090) and local TTS endpoints are supported only via a patched package (such as `librefang-git` with `feature-local-stt-tts`).

- **Detailed Guide & Onboarding**: [librefang-ctl.md](assistants/librefang-ctl.md)



### Moltis

- **Major Features**: Agent server featuring web-based configuration, persistent plugin/provider support, native SQLite hybrid retrieval, optional QMD sidecar integration for hybrid BM25 and vector search, and support for privileged port binding.

- **Language/Runtime**: Rust (Source) / Compiled binary (Rust Backend + Web-based Config GUI).

- **Signal Support**: Yes — Native integration (connects to local `signal-cli` HTTP daemon).

- **Coding Agent Support**: Yes — Supports Alibaba Coding Plan (`acp`), Claude Code, Codex, and **OpenCode** via tmux/PTY-based external runtimes.

- **LLM Inference via Agent Proxy**: None.

- **Requirements**: Needs a setup code on initial run to unlock the web UI. Uses `~/.local/sandbox/moltis` for data.

- **Sandboxing**: Uses a mostly strict configuration but relies on specific network capability bounding (`CAP_NET_BIND_SERVICE`) and `PrivateDevices=no` if hardware-backed plugins are used. Isolated `HOME`.

- **Search & Retrieval**: Built-in SQLite database with Full-Text Search (FTS5) for keyword search. Direct vector embedding storage inside SQLite. Supports an optional **QMD** sidecar that adds high-performance **BM25** keyword search, vector similarity search, and hybrid retrieval with LLM reranking. Automatically extracts facts and summarizes history when approaching context limits.

- **Embedding Options**: Remote OpenAI-compatible embedding API endpoints. Local vector search using local GGUF models served via local inference servers or Ollama, or built-in QMD model processing.

- **Reranking Support**: Native — QMD sidecar provides LLM reranking with `qwen3-reranker-0.6b` by default. Can also route to local-rerank endpoint.

- **STT/TTS Support**: Natively supports local STT via `local-speech-to-text` on port 50090. Local TTS is not supported (falls back to cloud speech APIs).

- **Detailed Guide & Onboarding**: [moltis-ctl.md](assistants/moltis-ctl.md)



### ZeroClaw

- **Major Features**: Rust-based agent gateway and runtime featuring built-in SQLite hybrid memory (vector + keyword FTS5) and native Landlock/Bubblewrap sandbox backends.

- **Language/Runtime**: Rust (Source) / Compiled binary (Rust Backend, no Web GUI).

- **Signal Support**: Yes — Native integration (communicates via the Go REST API wrapper).

- **Coding Agent Support**: Yes — Supports **OpenCode** as a coding worker tool (`opencode_cli`).

- **LLM Inference via Agent Proxy**: None.

- **Requirements**: Support for Linux namespace isolation or Landlock.

- **Sandboxing**: **Relaxed Namespaces Profile** is enforced via the systemd unit so that ZeroClaw can spawn secure nested sub-sandboxes via `bwrap` internally.

- **Search & Retrieval**: Native SQLite-based hybrid memory system. Integrates vector search and Full-Text Search (FTS) directly into SQLite. No external database infrastructure (like Pinecone or Elasticsearch) is required, keeping the runtime completely self-contained. Persistent memory handles context compression, conversation history, and user preferences.

- **Embedding Options**: Supports OpenAI-compatible embedding APIs. Can route to local embedding models using system-wide local LLM service (`local-llm-ggml`) or Ollama.

- **Reranking Support**: Native — built-in weighted hybrid search (0.7 vector / 0.3 keyword). Can integrate external reranker via configuration pointing to `http://localhost:50086/v1/rerank`.

- **STT/TTS Support**: Natively supports local STT by routing voice uploads to `local-speech-to-text` on port 50090. Local TTS is not supported.

- **Detailed Guide & Onboarding**: [zeroclaw-ctl.md](assistants/zeroclaw-ctl.md)



### IronClaw

- **Major Features**: Security-focused Agent OS providing WASM-sandboxed tool execution, credential protection with leak detection, prompt injection defense, and endpoint allowlisting. Built as a Rust reimplementation of OpenClaw with a focus on privacy, zero-trust architecture, and self-expanding capabilities via dynamic WASM tool building.

- **Language/Runtime**: Rust (Source) / Compiled binary (Rust Backend + Web Gateway GUI).

- **Signal Support**: Yes — Native integration (communicates via `signal-cli` HTTP daemon).

- **Coding Agent Support**: Yes — Agent Client Protocol (ACP) support with configurable external coding agents (e.g. `ironclaw acp add goose`).

- **LLM Inference via Agent Proxy**: Yes — Supports NEAR AI (default), Ollama (local), and OpenAI-compatible endpoints (OpenRouter, Together, Fireworks, vLLM, LiteLLM, LM Studio).

- **Requirements**: PostgreSQL 15+ with [pgvector](https://github.com/pgvector/pgvector) extension. Rust 1.92+ for source builds. NEAR AI account for default authentication.

- **Sandboxing**: **Relaxed Namespaces Profile** to support WASM sandbox execution (wasmtime) and optional Docker sandbox orchestrator/worker pattern. `MemoryDenyWriteExecute=no` required for WASM JIT compilation.

- **Search & Retrieval**: Hybrid search combining full-text search and vector similarity via Reciprocal Rank Fusion (RRF) backed by PostgreSQL with pgvector. Workspace filesystem provides flexible path-based storage for notes, logs, and context. Identity files maintain consistent personality and preferences across sessions.

- **Embedding Options**: Supports embedding generation via multiple built-in providers (NEAR AI, OpenAI, Anthropic, Ollama). Can leverage system-wide local embeddings via `local-llm-ggml` or Ollama servers using `LLM_BACKEND=ollama` or `LLM_BACKEND=openai_compatible`.

- **Reranking Support**: Native — built-in Reciprocal Rank Fusion (RRF) for hybrid search result merging. No external reranker required.

- **STT/TTS Support**: Supports local STT via OpenAI-compatible transcription endpoints (`TRANSCRIPTION_ENABLED=true`, `TRANSCRIPTION_BASE_URL=http://localhost:50090/v1`). Includes SILK audio decoder for WeChat voice messages. No native TTS support.

- **Detailed Guide & Onboarding**: [ironclaw-ctl.md](assistants/ironclaw-ctl.md)



### Hermes

- **Major Features**: Messaging Gateway designed for agent-to-agent and agent-to-human integration. Features an OpenAI-compatible API and a Dashboard Web UI. Supports graceful shutdowns and nested container execution.

- **Language/Runtime**: Python (Source) / private 3.11 Python Runtime /opt ( Web-based Dashboard GUI).

- **Signal Support**: Yes — Native integration with local `signal-cli` daemon.

- **Coding Agent Support**: Yes — Supports Claude Code, Codex, and **OpenCode** via bundled skills.

- **LLM Inference via Agent Proxy**: None.

- **Requirements**: `~/.local/sandbox/hermes` for persistent state, `~/agent-shared` for integration. Can integrate with podman/docker backend.

- **Sandboxing**: Utilizes the **Relaxed Namespaces Profile** to support nested `bwrap` orchestration. Isolated `HOME` directory redirection.

- **Search & Retrieval**: Built-in SQLite-based SessionDB and State management. Full-text search (FTS5) for keyword-based search. Built-in `sqlite-vec` extension support for vector search. Native integration with external vector/RAG databases (Qdrant, Chroma) and memory frameworks (Mem0, Honcho, Supermemory, RetainDB). Maintains localized context via `MEMORY.md` and `USER.md` prompt injections.

- **Embedding Options**: Supports remote embedding API providers (OpenAI, Cohere, Jina, Voyage AI) and local embedding models served via `llama.cpp` (`local-llm-ggml`) or Ollama.

- **Reranking Support**: Native — via auxiliary model slots and QMD hybrid engine. Can route to local reranker at `http://localhost:50086/v1/rerank`.

- **STT/TTS Support**: Natively supports local STT via `local-speech-to-text` on port 50090 for voice messages. Local TTS is not supported.

- **Detailed Guide & Onboarding**: [hermes-ctl.md](assistants/hermes-ctl.md)



### NanoBot

- **Major Features**: Lightweight python service built with `uv` featuring an onboarding setup wizard, a structured two-stage memory system ("Dream"), and Bubblewrap tool confinement.

- **Language/Runtime**: Python (Source) / Python runtime managed by `uv` (Python CLI + Setup Wizard, no Web GUI).

- **Signal Support**: Yes — Native integration (interfaces via HTTP Server-Sent Events).

- **Coding Agent Support**: None (No OpenCode support).

- **LLM Inference via Agent Proxy**: None.

- **Requirements**: `uv` package manager installed.

- **Sandboxing**: Relies on the **Relaxed Namespaces Profile** because it natively spawns agent code wrapped in nested `bwrap` isolation. Isolated `HOME`.

- **Search & Retrieval**: Structured two-stage memory system ("Dream") that separates active conversation buffers from long-term memory. Long-term memory store uses vector similarity search (RAG) to remember facts across sessions. Built-in Document Store allows indexing, chunking, and retrieving context from local files (PDFs, TXT, markdown). Model Context Protocol (MCP) integrations can execute external search tools (e.g. Brave Search) dynamically.

- **Embedding Options**: OpenAI-compatible embedding endpoints or local embeddings. Integrates with local embedding models via Ollama or `llama.cpp` / `local-llm-ggml` instances.

- **Reranking Support**: Via MCP — no native reranking; requires a custom MCP tool wrapping the local `/v1/rerank` endpoint.

- **STT/TTS Support**: Natively supports local STT via `local-speech-to-text` on port 50090. No native local TTS; can be added via custom MCP tools.

- **Detailed Guide & Onboarding**: [nanobot-ctl.md](assistants/nanobot-ctl.md)



### NanoClaw

- **Major Features**: Node.js webhook server designed for securely executing containerized runtime tools and managing agent workspaces.

- **Language/Runtime**: TypeScript/Node.js (Source) / Node.js containerized (Node.js Webhook Backend, no Web GUI).

- **Signal Support**: No — Not natively supported.

- **Coding Agent Support**: None (No OpenCode support).

- **LLM Inference via Agent Proxy**: Yes — Supports OpenCode (local inference via optional `add-opencode` skill).

- **Requirements**: Requires Docker/Podman running locally to spawn tool environments.

- **Sandboxing**: **Relaxed Namespaces Profile** with `PrivateDevices=no`. Strict profiles are dropped to allow the agent to launch local Docker/Podman containers successfully.

- **Search & Retrieval**: Uses SQLite databases within the Node.js process to maintain state. Maintains `CLAUDE.md` and related markdown files in isolated agent group directories. RAG or vector retrieval is typically handled by custom agent tools or external MCP databases.

- **Embedding Options**: Uses APIs (e.g. Anthropic, OpenAI) for remote embeddings. Local embeddings can be fetched via tools querying `local-llm-ggml` or Ollama servers.

- **Reranking Support**: Via custom skills — no native reranking; requires a custom skill or MCP tool wrapping the local `/v1/rerank` endpoint.

- **STT/TTS Support**: No native STT/TTS in the core daemon, but easily integrated via custom tools/skills calling `local-speech-to-text` (port 50090) and `local-text-to-speech` (port 50095).

- **Detailed Guide & Onboarding**: [nanoclaw-ctl.md](assistants/nanoclaw-ctl.md)



### PicoClaw

- **Major Features**: Ultra-lightweight gateway (<10MB memory) with built-in web console and CLI integration, leveraging Model Context Protocol (MCP) for tools/memory.

- **Language/Runtime**: Go (Source) / Compiled binary (Go Backend + Web-based Console GUI).

- **Signal Support**: No — Not natively supported.

- **Coding Agent Support**: Yes — Supports Claude Code, Codex, and GitHub Copilot CLI via provider-wrapped CLI execution (No OpenCode support).

- **LLM Inference via Agent Proxy**: Yes — Natively supports Google Antigravity.

- **Requirements**: `~/.local/sandbox/picoclaw` for persistent configuration.

- **Sandboxing**: **Relaxed Namespaces Profile**. Uses standard agent isolation with redirected `HOME` and strict filesystem protection. Isolated `HOME`.

- **Search & Retrieval**: No native built-in vector database or complex memory engine due to its ultra-lightweight design (<10MB memory). Local state and conversation histories are stored in simple JSON files. Supports the Model Context Protocol (MCP) to delegate search and retrieval tasks to external databases or RAG servers (e.g. SQLite-vec MCP, Qdrant MCP, Chroma MCP).

- **Embedding Options**: No native embedding models. Leverages external embedding API endpoints (OpenAI, Anthropic) or local embedding models via Ollama/llama-server via MCP tools or API routing.

- **Reranking Support**: Via MCP — no native reranking; delegates via MCP reranker tool wrapping the local `/v1/rerank` endpoint.

- **STT/TTS Support**: Natively supports local STT by defining an ASR provider pointing to the local whisper-server on port 50090. No native TTS engine; requires an external MCP TTS tool.

- **Detailed Guide & Onboarding**: [picoclaw-ctl.md](assistants/picoclaw-ctl.md)



---



## Standard Control Wrappers (assistant-ctl)



Each assistant in this repository is managed by a dedicated shell wrapper script (`assistants/-ctl`) adhering to standard design and lifecycle management guidelines.



### Common Commands



| Command | Action | Description |

|---|---|---|

| `install` | Install | Set up local directory structures under `~/.local/sandbox/`, generate environment file `.env` if missing, and create/register the systemd user unit. |

| `install --no-start` | Install | Same as install, but do not start (or stop it if already running) the service after installation for further configuration (e.g. editing `.env`). |

| `install --new-config` | Install | Same as install, but force overwrite any existing environment and configuration files with their default templates (useful for resetting to defaults). |

| `uninstall` | Uninstall | Stop and disable the systemd service, and clean up the systemd service files. (Data is preserved). |

| `start` / `stop` / `restart` | Lifecycle | Standard controls to start, stop, or restart the systemd user service. |

| `status` | Status | Show the current runtime status of the systemd service. |

| `logs [args...]` | Logs | View the daemon stdout/stderr output. Pass `-f` to tail/follow (e.g. `-ctl logs -f`). Supports passing any additional `journalctl` options. |

| `edit` | Edit Environment | Open the assistant's `.env` environment file in your `$EDITOR` and automatically restart the service upon exit to apply changes. |

| `exec ` | Sandbox Execute | Run the assistant's CLI binary or command line inside a transient systemd user service inheriting the same sandboxing and environment. |

| `shell` | Sandbox Shell | Spawn an interactive shell inside the assistant's systemd user sandbox for debugging. |



### Common Paths & Redirections



- **Service File**: `~/.config/systemd/user/.service` (or `hermes-gateway.service`)

- **Environment File**: `~/.config/systemd/user/.env` (or `hermes-gateway.env`)

- **Data Home**: `~/.local/sandbox/` (the service forces an isolated `HOME` environment variable to this location to keep configurations and cached libraries contained).

- **Shared Space (`agent-shared`)**: `~/agent-shared` is bind-mounted in read-write mode to the sandbox of all assistants by default. This enables cross-assistant sharing of outputs, databases, and logs.

- **Private Submounts (`agent-private`)**: To easily share specific directories from your host's private workspace (`~/agent-private/*`) to an assistant's sandbox without exposing the entire home directory, configure the `AGENT_PRIVATE_MOUNTS` environment variable inside the assistant's `.env` environment file.

  - **Syntax**: `AGENT_PRIVATE_MOUNTS="health diary"`

  - **Behavior**: The control wrapper will dynamically parse this list, ensure that the target directories (e.g. `~/agent-private/health` and `~/agent-private/diary`) exist on the host, inject the corresponding `BindPaths=` rules into the systemd service file, reload the user daemon, and dynamically mount them in all `start`, `restart`, `exec`, and `shell` wrapper commands.