Skip to content

README.md

Latest commit

 

History

History
94 lines (76 loc) · 7.1 KB

README.md

File metadata and controls

94 lines (76 loc) · 7.1 KB
Raw

Cybros

Cybros is a self-hosted agent platform: a managed agent kernel you run on your own machines, with an agent that is useful on day one.

  • Nexus, the kernel, keeps one account of human and agent members, durable conversations and runs, a model gateway across providers, tool delivery to your machines, approvals, schedules, memory, usage accounting and retention.
  • rho, the default agent, is an always-on personal assistant you talk to in a browser, in Telegram or from your editor, and a coding agent that works on your projects through a runner. It is built only on Nexus's public APIs, so it is also the reference for building your own agent.
  • Runners execute tools where the files are — a workstation, a server, a container — and only ever dial out to Nexus.

It is built for professional users and small teams: install it on a laptop, a LAN server or a public host, and bring your own model providers — API keys, a supported subscription authorization, or a local server.

Quick start

You need Docker with Compose v2 running, and curl. Linux amd64 and arm64 and Docker Desktop on macOS are supported; no host Ruby or JavaScript runtime is needed.

curl -fsSL https://raw.githubusercontent.com/jasl/cybros.ai/main/install/stack/install.sh | sh

The installer asks for an installation directory (default ~/.local/share/cybros), whether this is your own computer or a home server reached from your LAN, and the ports (Nexus 3300, rho 7777). It pulls the images, starts PostgreSQL, Nexus and rho, and prints rho's URL.

  1. Open the rho URL and choose Connect to Nexus.
  2. Create the first owner account. Nexus signs you in and continues the authorization; no setup secret is needed.
  3. Approve rho. This connects its agent and its private runner and returns you to rho.
  4. rho opens Agents › rho while a model is still missing. Follow the link to Nexus administration, add a provider with an API key, a subscription authorization or a local endpoint, and make a model visible.
  5. Back in rho, create a conversation, choose the model and the stack's runner, use /home/runner as the working directory, and ask it to list the files there.

From the installation directory, ./cybros status shows service health, ./cybros instructions repeats the URLs and setup steps, and ./cybros logs shows recent output. To let a coding agent do the installation for you, give it the prompt in Install with an agent.

Documentation

The documentation site's source is under guides/.

Section Start with
Overview What is Cybros?, core concepts, architecture, coming from managed agents, roadmap
Get started Install the stack, your first conversation, connect a host installation, build your own agent
Use rho Conversations, approvals and questions, schedules, sub-agents, Telegram, editors, plugins and code mode, troubleshooting
Operate Deployment layouts, models and providers, members, workspaces and access, retention, usage and budgets, upgrades, backup and restore, cmctl
Build agents Overview, quickstart, credentials and planes, agents and configuration, conversations and inputs, events and streaming, orchestration, approvals and rules, errors and recovery, SDKs
Runners Overview, quickstart, deploy a runner, claims and results, tool providers, security model
Reference Agent API, Platform API, OAuth, events, statuses, rate limits, kernel tools, command line, glossary

Development

Directory What it is Verify with
nexus/ The Rails kernel, model gateway and administration UI bin/setup, bin/dev; bin/ci for the full local pipeline
agents/rho/ rho: the daemon and CLI, the runner, the browser page, Telegram, ACP, MCP, browser tools, code mode bundle exec rake in each gem
sdks/ruby/ cybros_agent, the Ruby SDK and agent framework bundle exec rake
cmctl/ The human operator CLI for Nexus settings bundle exec rake
install/ The host installer, Docker images and the combined stack
e2e/ Cross-project journeys and evaluation tooling bundle exec rake
guides/ The documentation site (VitePress, built with Bun) bun install, bun run dev, bun run build
docs/ The internal development manual

Prerequisites for working on the Ruby projects: Ruby 4.0 (see .ruby-version), PostgreSQL 18 and libvips for Nexus, and Bun for its JavaScript and for the documentation site. nexus/bin/setup installs dependencies and prepares the databases; nexus/bin/dev runs the web server, the job workers and the asset watchers. Agent instructions for this repository are in AGENTS.md.

Cybros follows a rolling release: source installations follow main, and the Docker stack uses the published latest images. Interfaces and database schemas can still change incompatibly; back up an installation before upgrading. See Release and compatibility.

License

The repository defaults to MIT. Nexus has its own O'Saasy license; subdirectory and third-party licenses take precedence for their contents.