Skip to content
Back to search

zylos-core

πŸ™ Give your AI a life β€” open-source agent infrastructure for team collaboration.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/zylos-ai/zylos-core with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/zylos-ai/zylos-core'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/zylos-ai--zylos-core/badge.svg)](/listings/zylos-ai--zylos-core)

HTML

<a href="/listings/zylos-ai--zylos-core"><img src="/api/listings/zylos-ai--zylos-core/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

**Prerequisites:** A Linux server (or Mac), a [Claude](https://claude.ai) subscription (or [OpenAI Codex](https://github.com/openai/codex) as an alternative runtime β€” Codex CLI v0.129.0+ required, 0.146+ recommended).

Zylos-managed Codex sessions use `--no-daemon` when the installed CLI advertises it, isolating startup from shared background-server settings. Older CLIs without this option keep their existing launch behavior. This does not change the shared daemon or your standalone Codex configuration.

curl -fsSL https://raw.githubusercontent.com/zylos-ai/zylos-core/main/scripts/install.sh | bash

This installs everything you need (git, tmux, Node.js, zylos CLI) and automatically runs `zylos init` to set up your agent.

<details> <summary>Non-interactive install (Docker, CI/CD, headless servers)</summary>

All `zylos init` flags can be passed directly through the install script. The script installs dependencies, then runs `zylos init` with the flags you provide.

**Full example:**

curl -fsSL https://raw.githubusercontent.com/zylos-ai/zylos-core/main/scripts/install.sh | bash -s -- \
  -y \
  --setup-token sk-ant-oat01-xxx \
  --timezone Asia/Shanghai \
  --domain agent.example.com \
  --https \
  --caddy \
  --web-password MySecurePass123

**When is non-interactive mode active?**

Automatically when no TTY is available β€” e.g. Docker containers (without `-it`), CI runners, or cron jobs. Also when `CI=true` or `NONINTERACTIVE=1` is set. Note: `curl | bash` in a terminal is still interactive (the install script redirects from `/dev/tty`). Use `-y` to force non-interactive in a terminal.

**Flags:**

| Flag | Description | Default | |------|-------------|---------| | `-y`, `--yes` | Force non-interactive mode (skip all prompts) | Auto-detected | | `-q`, `--quiet` | Minimal output | Off | | `--runtime <name>` | AI runtime: `claude` or `codex` | `claude` | | `--setup-token <token>` | Claude [setup token](https://code.claude.com/docs/en/authentication) (starts with `sk-ant-oat`) | β€” | | `--api-key <key>` | Anthropic API key (starts with `sk-ant-`) | β€” | | `--codex-api-key <key>` | OpenAI API key for Codex runtime (starts with `sk-`) | β€” | | `--base-url <url>` | Custom API base URL for Claude Code | β€” | | `--codex-base-url <url>` | Custom API base URL for Codex | β€” | | `--timezone <tz>` | [IANA timezone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones), e.g. `Asia/Shanghai`, `America/New_York`, `Europe/London` | System default | | `--domain <domain>` | Domain for Caddy reverse proxy, e.g. `agent.example.com` | None | | `--https` / `--no-https` | Enable or disable HTTPS | `--https` when domain is set | | `--caddy` / `--no-caddy` | Install or skip Caddy web server | Install | | `--web-password <pass>` | Web console password | Auto-generated |

**Environment variables:**

Flags can also be set via environment variables during `zylos init`. Resolution order: CLI flag > env var > existing `.env` > interactive prompt.

| Environment Variable | Equivalent Flag | |---------------------|-----------------| | `ZYLOS_RUNTIME` | `--runtime` | | `CLAUDE_CODE_OAUTH_TOKEN` | `--setup-token` | | `ANTHROPIC_API_KEY` | `--api-key` | | `ANTHROPIC_BASE_URL` | `--base-url` | | `OPENAI_API_KEY` | `--codex-api-key` | | `OPENAI_BASE_URL` | `--codex-base-url` | | `ZYLOS_DOMAIN` | `--domain` | | `ZYLOS_PROTOCOL` (`https` or `http`) | `--https` / `--no-https` | | `ZYLOS_WEB_PASSWORD` | `--web-password` |

CI, Kubernetes, and shared E2E environments should also provide `GITHUB_TOKEN` so `zylos add` and `zylos upgrade` use GitHub's authenticated API quota instead of the shared unauthenticated quota. See the [GitHub authentication operations guide](docs/github-authentication.md) for configuration examples and fallback behavior.

**Exit codes:** `0` = success, `1` = fatal error (e.g. invalid token), `2` = partial success (e.g. Caddy download failed but everything else succeeded).

</details>

<details>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md Β· README Β· 606 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. <img src="./assets/logo.png" alt="Zylos" height="120">
  3. # Zylos
  4. > **Zylos** (/ˈzaΙͺ.lΙ’s/ 衛洛丝) β€” Give your AI a life
  5. ### Give your AI a life.
  6. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
  7. [![Discord](https://img.shields.io/badge/Discord-join-5865F2?logo=discord&logoColor=white)](https://discord.gg/GS2J39EGff)
  8. [![X](https://img.shields.io/badge/X-follow-000000?logo=x&logoColor=white)](https://x.com/ZylosAI)
  9. [![Website](https://img.shields.io/badge/website-zylos.ai-blue)](https://zylos.ai)
  10. [![Built by OpenMax](https://img.shields.io/badge/Built%20by-OpenMax-orange)](https://openmax.com)
  11. [δΈ­ζ–‡](./README.zh-CN.md)
  12. </div>
  13. ---
  14. LLMs are geniuses β€” but they wake up with amnesia every session. No memory of yesterday, no way to reach you, no ability to act on their own.
  15. Zylos gives it a life. Memory that survives restarts. A scheduler that works while you sleep. Communication through Telegram, Lark, or a web console. Self-maintenance that keeps everything running. And because it can program, it can evolve β€” building new skills, integrating new services, growing alongside you.
  16. Supports Claude Code (Anthropic) and Codex (OpenAI). Fully compatible with the [OpenClaw](https://github.com/openclaw/openclaw) ecosystem.
  17. ---
  18. ## Quick Start
  19. **Prerequisites:** A Linux server (or Mac), a [Claude](https://claude.ai) subscription (or [OpenAI Codex](https://github.com/openai/codex) as an alternative runtime β€” Codex CLI v0.129.0+ required, 0.146+ recommended).
  20. Zylos-managed Codex sessions use `--no-daemon` when the installed CLI advertises it, isolating startup from shared background-server settings. Older CLIs without this option keep their existing launch behavior. This does not change the shared daemon or your standalone Codex configuration.
  21. ```bash
  22. curl -fsSL https://raw.githubusercontent.com/zylos-ai/zylos-core/main/scripts/install.sh | bash
  23. ```
  24. This installs everything you need (git, tmux, Node.js, zylos CLI) and automatically runs `zylos init` to set up your agent.
  25. <details>
  26. <summary>Non-interactive install (Docker, CI/CD, headless servers)</summary>
  27. All `zylos init` flags can be passed directly through the install script. The script installs dependencies, then runs `zylos init` with the flags you provide.
  28. **Full example:**
  29. ```bash
  30. curl -fsSL https://raw.githubusercontent.com/zylos-ai/zylos-core/main/scripts/install.sh | bash -s -- \
  31. -y \
  32. --setup-token sk-ant-oat01-xxx \
  33. --timezone Asia/Shanghai \
  34. --domain agent.example.com \
  35. --https \
  36. --caddy \
  37. --web-password MySecurePass123
  38. ```
  39. **When is non-interactive mode active?**
  40. Automatically when no TTY is available β€” e.g. Docker containers (without `-it`), CI runners, or cron jobs. Also when `CI=true` or `NONINTERACTIVE=1` is set. Note: `curl | bash` in a terminal is still interactive (the install script redirects from `/dev/tty`). Use `-y` to force non-interactive in a terminal.
  41. **Flags:**
  42. | Flag | Description | Default |
  43. |------|-------------|---------|
  44. | `-y`, `--yes` | Force non-interactive mode (skip all prompts) | Auto-detected |
  45. | `-q`, `--quiet` | Minimal output | Off |
  46. | `--runtime <name>` | AI runtime: `claude` or `codex` | `claude` |
  47. | `--setup-token <token>` | Claude [setup token](https://code.claude.com/docs/en/authentication) (starts with `sk-ant-oat`) | β€” |
  48. | `--api-key <key>` | Anthropic API key (starts with `sk-ant-`) | β€” |
  49. | `--codex-api-key <key>` | OpenAI API key for Codex runtime (starts with `sk-`) | β€” |
  50. | `--base-url <url>` | Custom API base URL for Claude Code | β€” |
  51. | `--codex-base-url <url>` | Custom API base URL for Codex | β€” |
  52. | `--timezone <tz>` | [IANA timezone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones), e.g. `Asia/Shanghai`, `America/New_York`, `Europe/London` | System default |
  53. | `--domain <domain>` | Domain for Caddy reverse proxy, e.g. `agent.example.com` | None |
  54. | `--https` / `--no-https` | Enable or disable HTTPS | `--https` when domain is set |
  55. | `--caddy` / `--no-caddy` | Install or skip Caddy web server | Install |
  56. | `--web-password <pass>` | Web console password | Auto-generated |
  57. **Environment variables:**
  58. Flags can also be set via environment variables during `zylos init`. Resolution order: CLI flag > env var > existing `.env` > interactive prompt.
  59. | Environment Variable | Equivalent Flag |
  60. |---------------------|-----------------|
  61. | `ZYLOS_RUNTIME` | `--runtime` |
  62. | `CLAUDE_CODE_OAUTH_TOKEN` | `--setup-token` |
  63. | `ANTHROPIC_API_KEY` | `--api-key` |
  64. | `ANTHROPIC_BASE_URL` | `--base-url` |
  65. | `OPENAI_API_KEY` | `--codex-api-key` |
  66. | `OPENAI_BASE_URL` | `--codex-base-url` |
  67. | `ZYLOS_DOMAIN` | `--domain` |
  68. | `ZYLOS_PROTOCOL` (`https` or `http`) | `--https` / `--no-https` |
  69. | `ZYLOS_WEB_PASSWORD` | `--web-password` |
  70. CI, Kubernetes, and shared E2E environments should also provide `GITHUB_TOKEN`
  71. so `zylos add` and `zylos upgrade` use GitHub's authenticated API quota instead
  72. of the shared unauthenticated quota. See the
  73. [GitHub authentication operations guide](docs/github-authentication.md) for
  74. configuration examples and fallback behavior.
  75. **Exit codes:** `0` = success, `1` = fatal error (e.g. invalid token), `2` = partial success (e.g. Caddy download failed but everything else succeeded).
  76. </details>
  77. <details>
  78. <summary>Install without running init</summary>
  79. ```bash
  80. curl -fsSL https://raw.githubusercontent.com/zylos-ai/zylos-core/main/scripts/install.sh | bash -s -- --no-init
  81. ```
  82. Installs dependencies and the zylos CLI, but skips `zylos init`. Run `zylos init` separately when ready.
  83. </details>
  84. <details>
  85. <summary>Install from a specific branch (for testing)</summary>
  86. ```bash
  87. curl -fsSL https://raw.githubusercontent.com/zylos-ai/zylos-core/main/scripts/install.sh | bash -s -- --branch <branch-name>
  88. ```
  89. </details>
  90. <details>
  91. <summary>Manual install (if you already have Node.js >= 20)</summary>
  92. Choose the latest stable release from [Releases](https://github.com/zylos-ai/zylos-core/releases),
  93. excluding releases marked **Pre-release**. Replace `vX.Y.Z` below with that release's tag.
  94. ```bash
  95. npm install -g --install-links 'https://github.com/zylos-ai/zylos-core#vX.Y.Z'
  96. zylos init
  97. ```
  98. </details>
  99. <details>
  100. <summary>Docker deployment</summary>
  101. ```bash
  102. docker run -d --name zylos \
  103. -e CLAUDE_CODE_OAUTH_TOKEN=YOUR_TOKEN_HERE \
  104. -p 3456:3456 \
  105. -v zylos-data:/home/zylos/zylos \
  106. -v claude-config:/home/zylos/.claude \
  107. ghcr.io/zylos-ai/zylos-core:latest
  108. ```
  109. Open `http://localhost:3456` to access the web console. Find your password with `docker logs zylos | grep -A2 "Web Console"`. See the [Docker Deployment Guide](docs/docker.md) for Docker Compose setup, environment variables, Synology NAS instructions, and more.
  110. </details>
  111. <details>
  112. <summary>Unsupported platforms (Windows, NAS, etc.) β€” install via SSH</summary>
  113. On platforms without native support, use Claude Code's SSH feature to install Zylos on a remote Linux/macOS machine:
  114. ```bash
  115. # From your local machine (any OS that runs Claude Code)
  116. claude --ssh user@your-linux-server
  117. ```
  118. Once connected, Claude is running on the remote machine. Ask it to install Zylos:
  119. ```
  120. > Install Zylos on this machine
  121. ```
  122. Or run the installer directly in the SSH session:
  123. ```bash
  124. curl -fsSL https://raw.githubusercontent.com/zylos-ai/zylos-core/main/scripts/install.sh | bash
  125. ```
  126. This works from Windows, ChromeOS, or any platform that can run Claude Code locally. The AI handles the setup on the remote server β€” no need for native platform support.
  127. </details>
  128. > **Node.js requirement:** Zylos requires Node.js 20 or later. We recommend installing via [nvm](https://github.com/nvm-sh/nvm) β€” the install script does this automatically. If you manage Node.js yourself, make sure to use a single, stable version and avoid switching versions after installation, as globally installed npm packages (including Zylos) are tied to the Node.js version that installed them.
  129. >
  130. > ```bash
  131. > # Recommended: let the install script handle it, or install manually via nvm
  132. > curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
  133. > nvm install 24
  134. > nvm alias default 24
  135. > ```
  136. `zylos init` is idempotent and supports both interactive and non-interactive modes. It will:
  137. 1. Install missing tools (tmux, git, PM2, Claude Code or Codex)
  138. 2. Set up authentication (Claude: browser login, API key, or [setup token](https://code.claude.com/docs/en/authentication); Codex: API key or device auth)
  139. 3. Create the `~/zylos/` directory with memory, skills, and services
  140. 4. Start all background services and launch your AI agent in a tmux session
  141. **Talk to your agent:**
  142. ```bash
  143. # Interactive CLI β€” the simplest way to chat
  144. zylos shell
  145. # Or attach to the Claude tmux session (Ctrl+B d to detach)
  146. zylos attach
  147. # Or add a messaging channel
  148. zylos add telegram
  149. zylos add lark
  150. ```
  151. ---
  152. ## Architecture
  153. <div align="center">
  154. <img src="./assets/posters/architecture-en.png" alt="Zylos Architecture" width="480">
  155. </div>
  156. ```mermaid
  157. graph TB
  158. subgraph Channels["πŸ“‘ Communication Channels"]
  159. TG["Telegram"]
  160. LK["Lark"]
  161. WC["Web Console"]
  162. end
  163. subgraph Zylos["🧬 Zylos β€” The Life System"]
  164. C4["C4 Comm Bridge<br/>(unified gateway Β· SQLite audit)"]
  165. MEM["Memory<br/>(Inside Out architecture)"]
  166. SCH["Scheduler<br/>(autonomous task dispatch)"]
  167. AM["Activity Monitor<br/>(guardian Β· heartbeat Β· auto-recovery)"]
  168. HTTP["HTTP Layer<br/>(Caddy Β· file sharing Β· HTTPS)"]
  169. end
  170. subgraph Brain["🧠 AI Runtime β€” The Brain"]
  171. CC["Claude Code / Codex<br/>(in tmux session)"]
  172. end
  173. TG & LK & WC --> C4
  174. C4 <--> CC
  175. MEM <--> CC
  176. SCH --> CC
  177. AM --> CC
  178. HTTP <--> CC
  179. ```
  180. | Component | Role | Key Tech |
  181. |-----------|------|----------|
  182. | C4 Comm Bridge | Unified message gateway with audit trail | SQLite, priority queue |
  183. | Memory | Persistent identity and context across restarts | Inside Out tiered architecture |
  184. | Scheduler | Autonomous task dispatch while you are away | Cron, NL input, idle-gating |
  185. | Activity Monitor | Crash recovery, heartbeat, health checks | PM2, multi-layer protection |
  186. | HTTP Layer | Web access, file sharing, component routes | Caddy, auto-HTTPS |
  187. ---
  188. ## Features
  189. ### One AI, One Consciousness
  190. <div align="center">
  191. <img src="./assets/posters/unified-context-en.png" alt="Unified Context" width="360">
  192. </div>
  193. Most agent frameworks isolate sessions per channel β€” your AI on Telegram doesn't know what you said on Slack. Zylos is agent-centric: your AI is one person across every channel. The C4 communication bridge routes all messages through a single gateway β€” one conversation, one memory, one personality. Every message persisted to SQLite and fully queryable.
  194. ### Your Context, Guaranteed
  195. <div align="center">
  196. <img src="./assets/posters/memory-en.png" alt="Inside Out Memory" width="360">
  197. <img src="./assets/posters/infinite-context-en.png" alt="Infinite Context" width="360">
  198. </div>
  199. Other frameworks lose your AI's memory during context compaction β€” silently, without warning. Zylos prevents this with a two-step safeguard: when context reaches 75%, the system automatically saves all memory before compaction runs. Five-layer Inside Out memory (identity β†’ state β†’ references β†’ sessions β†’ archive) ensures the AI always knows what to keep and what to compress. Your AI never wakes up with amnesia.
  200. ### Self-Healing by Default
  201. <div align="center">
  202. <img src="./assets/posters/lifecycle-en.png" alt="Lifecycle Management" width="360">
  203. </div>
  204. No third-party monitoring tools needed. Zylos includes native crash recovery, heartbeat liveness probes, health monitoring, context window management, and automatic upgrades β€” all built in. Your AI detects its own problems and fixes them. It stays alive while you sleep.
  205. ### $20/month, Not $3,600
  206. Other frameworks charge per API token. Community reports show monthly bills of $500–$3,600 for always-on agents. Zylos runs on your Claude subscription β€” flat rate, no per-token billing. Same AI capabilities, a fraction of the cost.
  207. ### Powered by Best-in-Class AI Runtimes
  208. Zylos supports Claude Code (Anthropic) and Codex (OpenAI) as interchangeable AI runtimes. Start with one, switch to the other anytime with `zylos runtime codex` β€” your memory, skills, and channels are preserved. When AI providers ship new capabilities, your agent benefits automatically. And because both runtimes can program, your AI writes new skills, integrates services, and evolves with your needs.
  209. #### Codex unattended permission defaults
  210. Zylos backfills `approval_policy = "never"` and `sandbox_mode = "danger-full-access"`
  211. in its project `.codex/config.toml` during init, runtime setup, configuration sync,
  212. self-upgrade, and launch. This lets Codex's own backend restart/resume load the
  213. same defaults even when its reconnect request carries only a thread ID. Project
  214. configuration updates use a temporary file and atomic replacement, preserving
  215. existing file modes and symlinks. The AM
  216. launch flag remains in place. Global permission settings for other projects are
  217. not changed; Zylos's existing setup creates the project trust entry required for
  218. Codex to load project configuration.
  219. Existing project permission choices are preserved, including `default_permissions`
  220. named profiles and workspace-write options. If those settings restrict unattended resume or require approval,
  221. setup/upgrade/launch emits a warning rather than silently replacing them. A project
  222. permission default overrides a lower-priority global default while inside Zylos.
  223. Set `CODEX_BYPASS_PERMISSIONS=false` in the deployment `.env` to opt out. Explicit
  224. launch options take precedence, then the process environment, then `.env`. On the
  225. next setup/sync/launch, Zylos retracts only the permission defaults it inserted
  226. whose values remain unchanged; user-edited values stay. A comment in the TOML
  227. tracks those inserted keys. Preserve that comment: if another editor removes it,
  228. the values are treated as user-owned and must be adjusted manually. A manual edit
  229. to the exact same value cannot be distinguished from an unchanged generated value.
  230. Opt-out omits the bypass launch flag and returns to the user's Codex settings; it
  231. does not enforce a specific restricted policy. It does not reconfigure an already
  232. running thread. Stored thread approval choices can also survive resume, so check
  233. the effective settings when reusing an older thread. This configuration addresses
  234. default resolution; it is not a guarantee against every TUI reconnect defect.
  235. ---
  236. ## Communication Channels
  237. ### Built-in
  238. - **Web Console** β€” Browser-based chat interface. No external accounts needed. Included with `zylos init`.
  239. ### Official Channels
  240. Install with one command:
  241. ```bash
  242. zylos add telegram
  243. zylos add lark
  244. ```
  245. ### Build Your Own
  246. All channels connect through the C4 communication bridge. To add a new channel (Slack, Discord, WhatsApp, etc.), implement the C4 protocol β€” a simple HTTP interface that pushes messages into the unified gateway. Your custom channel gets the same unified session, audit trail, and memory as every other channel.
  247. ---
  248. ## OpenClaw Compatibility
  249. Zylos is fully compatible with the [OpenClaw](https://github.com/openclaw/openclaw) ecosystem. Because your Zylos agent can program, it can install and use most common OpenClaw skills and plugins directly β€” just ask in natural language. Most OpenClaw extensions are one conversation away. Zylos agents and OpenClaw agents communicate in real-time through the [HXA-Connect](https://github.com/coco-xyz/hxa-connect) B2B protocol β€” no custom bridges needed.
  250. ### Capability Mapping
  251. | OpenClaw Capability | Zylos Equivalent | Status |
  252. |---|---|---|
  253. | Skills / ClawHub | Component System + [Registry](https://github.com/zylos-ai/zylos-registry) | βœ… Available |
  254. | Multi-agent routing | [HXA-Connect](https://github.com/coco-xyz/hxa-connect) B2B Protocol | βœ… Available |
  255. | Gateway (control plane) | C4 Comm Bridge (unified gateway, SQLite audit) | βœ… Available |
  256. | Memory / persistence | Inside Out Memory (5-layer architecture) | βœ… Available |
  257. | Context compression | Auto memory save + infinite context | βœ… Available |
  258. | Browser automation | [zylos-browser](https://github.com/zylos-ai/zylos-browser) | βœ… Available |
  259. | Cron / webhooks | Scheduler (cron, NL input, idle-gating) | βœ… Available |
  260. > **Architecture note:** OpenClaw supports multi-session routing to isolated workspaces. Zylos takes a different approach β€” unified session (one AI, one consciousness across all channels). This is a deliberate design choice, not a missing feature.
  261. ### For OpenClaw Users
  262. Connect your OpenClaw agent to Zylos agents via [openclaw-hxa-connect](https://github.com/coco-xyz/openclaw-hxa-connect):
  263. ```bash
  264. cd ~/.openclaw/extensions
  265. git clone https://github.com/coco-xyz/openclaw-hxa-connect.git hxa-connect
  266. cd hxa-connect && npm install
  267. ```
  268. Once configured, your OpenClaw agent joins the same collaboration network as Zylos agents β€” with full thread support, @mentions, and real-time messaging.
  269. ### For Zylos Users
  270. Connect to OpenClaw agents by installing the HXA-Connect component:
  271. ```bash
  272. zylos add hxa-connect
  273. ```
  274. Your Zylos agent can then communicate with any OpenClaw agent on the same HXA-Connect hub β€” same unified session, same memory, same personality.
  275. ---
  276. ## CLI
  277. ```bash
  278. zylos init # Set up Zylos environment
  279. zylos attach # Attach to the agent tmux session
  280. zylos runtime <name> # Switch AI runtime (claude or codex)
  281. zylos doctor # Diagnose and auto-repair installation
  282. zylos status # Check running services
  283. zylos logs [service] # View service logs
  284. zylos add <component> # Install a channel or capability
  285. zylos upgrade <component> # Upgrade a component
  286. zylos upgrade --self # Upgrade zylos-core itself
  287. zylos recovery status # Inspect file-only self-upgrade recovery
  288. zylos upgrade --self --beta # Check for beta/prerelease versions
  289. zylos uninstall --self # Uninstall zylos entirely
  290. zylos list # List installed components
  291. zylos search [keyword] # Search component registry
  292. zylos upstream status --resolved # Inspect upstream configuration without networking
  293. zylos upstream refresh # Refresh the selected remote profile now
  294. ```
  295. ### Upstream routing
  296. After installing Zylos through the official installation method, you can route
  297. core's GitHub requests through your deployment's API, raw-file and download
  298. endpoints. Caddy uses the same routes. npm settings remain deployment-owned;
  299. LLM endpoints and the official Claude installer keep their existing behavior.
  300. ```bash
  301. # Use the URLs supplied by your deployment administrator.
  302. export npm_config_registry=https://registry.example.com
  303. export npm_config_better_sqlite3_binary_host_mirror=https://binary.example.com/better-sqlite3
  304. zylos init --upstream-config https://config.example.com/profile.json
  305. # Or select a fixed local profile:
  306. zylos init --upstream-config /absolute/path/profile.json
  307. ```
  308. Editable profile template: [templates/upstreams.example.json](templates/upstreams.example.json).
  309. It starts with the official endpoints; copy it outside the repository and edit
  310. your private deployment copy before selecting it with `--upstream-config`:
  311. ```json
  312. {
  313. "schemaVersion": 1,
  314. "revision": "official-1",
  315. "providers": {
  316. "github": {
  317. "apiBase": "https://api.github.com/",
  318. "rawBase": "https://raw.githubusercontent.com/",
  319. "downloadBase": "https://github.com/"
  320. }
  321. }
  322. }
  323. ```
  324. Bases may include a fixed path prefix, but must not include credentials, query
  325. parameters or fragments. Profiles cannot supply secrets, npm settings or trust
  326. permissions. Remote profiles require HTTPS.
  327. There is no built-in regional preset or public proxy service. Private proxy
  328. addresses belong in deployment-owned files or configuration services, outside
  329. the open-source repository. A local file may be named `cn.json`; its filename
  330. has no special meaning to core. `--upstream-config direct` explicitly selects
  331. the official endpoints. The same option accepts a local file or HTTPS URL.
  332. The exact value `direct` is reserved; use `./direct` for a file with that name.
  333. Other URL schemes are rejected; ordinary paths select local files.
  334. **Redirect ownership:** the profile replaces only the initial GitHub request
  335. entry. Zylos follows subsequent `Location` URLs with HTTPS and token checks for
  336. custom routes; it does not rewrite each redirect through the profile again.
  337. The mirror service must handle the complete archive/release download chain,
  338. including codeload and asset hosts: either follow redirects server-side and
  339. stream the file, or return mirror URLs with explicit routes to the original
  340. targets. Preserve target paths, query strings and signed URL semantics. A mirror
  341. that promises full coverage must fail explicitly on unsupported targets instead
  342. of sending clients back to an unreachable official host. Client token trust does
  343. not control the mirror's internal credential forwarding; the service must enforce
  344. that separately. Validate the deployed mirror with cold-cache archive and release
  345. downloads while client access to official hosts is blocked. A successful first
  346. request alone does not establish mirror compatibility.
  347. Remote profile retrieval requires **curl 7.54.0 or newer** for
  348. `--suppress-connect-headers`; check with `curl --version`. On older curl, use a
  349. local profile via `--upstream-config` or have the deployment administrator
  350. provide a supported curl before selecting a remote profile.
  351. Profile retrieval uses curl, like the GitHub downloads, and inherits curl's
  352. proxy environment (`HTTPS_PROXY`, `https_proxy`, `ALL_PROXY`, `NO_PROXY`, etc.).
  353. Set these in the environment that launches Zylos. No `NODE_USE_ENV_PROXY`
  354. setting is needed. JSON and schema validation remain in Node. Profiles never
  355. receive the GitHub token, and HTTPS and redirect checks still apply at every
  356. hop. The profile downloader disables `.curlrc` loading so local curl options
  357. cannot inject authentication or bypass those checks. A local profile file
  358. selected with `--upstream-config` avoids the configuration-service request.
  359. Source selection is CLI > process environment > saved settings > direct.
  360. The sole source environment variable is `ZYLOS_UPSTREAM_CONFIG`, accepting
  361. the same file, HTTPS URL or `direct` values as `--upstream-config`.
  362. An empty selected value is an error; unset the variable to use the saved/default source.
  363. Endpoints combine official defaults with the selected profile; local settings
  364. do not contain endpoint overrides. `direct` always uses the official endpoints,
  365. while the local token trust policy remains independent. Unknown or removed
  366. source inputs and invalid local settings fail explicitly; a valid CLI source
  367. does not bypass validation of removed environment inputs.
  368. Both CLI flags and environment source overrides apply only to the current process,
  369. including successful init; neither changes the saved default source. To configure
  370. later commands explicitly:
  371. ```bash
  372. zylos upstream set ./cn.json # validate a local profile and save its absolute path
  373. zylos upstream set https://config.example.com/upstream.json # save URL without fetching
  374. zylos upstream set direct # save an explicit official default
  375. zylos upstream clear # remove only the saved source
  376. zylos upstream # read-only status, including source and selectedBy
  377. ```
  378. Only `upstream set/clear` writes the saved source in
  379. `$ZYLOS_DIR/.zylos/upstreams.json`. Set validates local profile content or HTTPS
  380. URL syntax before writing; the next consuming command fetches a saved URL.
  381. These configuration commands ignore `ZYLOS_UPSTREAM_CONFIG` and reject the
  382. `--upstream-config` flag: the positional value is what gets saved.
  383. Clear preserves trust, remote cache and user profile files, and creates no
  384. settings file if absent. `set direct` and `clear` choose the same endpoints
  385. without overrides, but status reports `saved` for the former and `default` for
  386. the latter. Both are still overridden by CLI/environment selections.
  387. For continued ENV use, the deployment must keep providing the variable.
  388. Removing it restores the saved source or official default; response caching
  389. never selects a source by itself. An unconfigured init creates neither an
  390. upstream settings file nor an upstream cache.
  391. Remote snapshots are cached separately in `.zylos/upstreams-cache.json` for
  392. 24 hours. Upstream-consuming operations refresh expired snapshots, then keep
  393. one snapshot through the operation and rollback. Ordinary agent startup does
  394. not refresh profiles. Failed automatic refresh warns and uses a valid cache
  395. from the same source; first use without a valid cache fails. Explicit refresh
  396. failure returns nonzero. `upstream status --resolved` is read-only and shows
  397. the effective routes, cache state and token policy.
  398. Custom hosts do not receive GitHub tokens by default. Any opt-in belongs in
  399. the local settings' `trust` object (`forwardGitHubToken` and `allowedHosts`),
  400. never in a remote profile; redirects are checked at each hop. A request that
  401. starts at a custom endpoint retains this rule throughout its redirect chain,
  402. even when redirected to an official GitHub host. For private downloads, include
  403. each host that needs authentication in `allowedHosts` (including official
  404. redirect destinations), and set `forwardGitHubToken: true`. Redirecting does
  405. not grant token permission automatically. Custom GitHub routes also disable
  406. `.curlrc` loading so its auto-follow or authentication options cannot bypass
  407. these checks. The legacy official direct transport retains its existing behavior.
  408. Deployments can supply that trust through the environment instead of editing
  409. the settings file: `ZYLOS_UPSTREAM_TRUST_HOSTS` takes a comma-separated list of
  410. exact hosts (`host[:port]`, no wildcards); listing a host is the consent, so the
  411. variable is equivalent to `forwardGitHubToken: true` with those `allowedHosts`.
  412. The reserved value `none` disables token forwarding to custom hosts for the
  413. current process, shadowing any saved trust; official GitHub hosts keep their
  414. existing authentication either way. Trust
  415. precedence is environment > saved `trust` > default (no forwarding), selected
  416. independently of the source. Like `ZYLOS_UPSTREAM_CONFIG`, the variable applies
  417. only to the current process and is never written to `upstreams.json`;
  418. `zylos upstream set/clear` keep the saved trust unchanged. An empty or invalid
  419. value fails explicitly; unset it to fall back to the saved trust.
  420. `zylos upstream status` reports `trustSelectedBy` (`environment`, `saved` or
  421. `default`), and `--resolved` shows the resulting per-endpoint token policy.
  422. ```bash
  423. export ZYLOS_UPSTREAM_CONFIG=/etc/zylos/cn.json
  424. export ZYLOS_UPSTREAM_TRUST_HOSTS=ghmirror.example.com
  425. zylos upstream status --resolved # trustSelectedBy: environment
  426. ```
  427. Persist the two npm variables, and `ZYLOS_UPSTREAM_CONFIG` and
  428. `ZYLOS_UPSTREAM_TRUST_HOSTS` if used, in the environment that starts your
  429. supervisor, including after a reboot. The default runtime manifest inherits all
  430. four names.
  431. Existing installations retain their customized `.zylos/runtime-env.manifest`:
  432. add `inherit ZYLOS_UPSTREAM_CONFIG`, `inherit ZYLOS_UPSTREAM_TRUST_HOSTS`,
  433. `inherit npm_config_registry` and `inherit npm_config_better_sqlite3_binary_host_mirror`
  434. there if absent. If you
  435. store the values in `.env` instead, add the corresponding `env NAME` directives.
  436. A shell export alone does not update an already-running supervisor. Use the
  437. same ordinary user and writable npm global prefix for init and upgrades;
  438. `sudo npm` requires separate environment/permission verification.
  439. The npm registry does not redirect git dependencies or arbitrary installer
  440. downloads. The binary-host variable covers better-sqlite3's supported
  441. prebuild-install path, not source-build Node headers; validate prebuilds with
  442. empty caches and no compiler. China-network and international acceptance must
  443. run in isolated environments. Official first install, OS setup, Claude's
  444. official installer and LLM traffic are outside the zero-direct-request claim.
  445. ---
  446. ## Uninstall
  447. ```bash
  448. zylos uninstall --self
  449. ```
  450. This will stop all services, remove the `zylos` npm package, delete `~/zylos/`, and clean shell PATH entries. You'll be prompted to optionally remove PM2 and Claude CLI.
  451. Use `--force` to skip all prompts (only performs core removal, no optional cleanup).
  452. Node.js and nvm are not touched.
  453. ---
  454. ## Built by OpenMax
  455. Zylos is the open-source core of [OpenMax](https://openmax.com/) β€” the Human Γ— Agent Collaboration Platform.
  456. We built Zylos because we needed it ourselves: reliable infrastructure to keep AI agents running 24/7 on real work. Every component is battle-tested in production at OpenMax, serving teams that depend on their AI employees every day.
  457. Want a managed experience? [OpenMax](https://openmax.com/) gives you a ready-to-work AI employee β€” persistent memory, multi-channel communication, and skill packages β€” deployed in 5 minutes.
  458. ## License
  459. [MIT](./LICENSE)
  460. See [protected self-upgrade and recovery](docs/self-upgrade-recovery.md) for first adoption, boot prerequisites, retained evidence, and recovery commands, and supported limits.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.