Skip to content

README.md

Latest commit

 

History

History
237 lines (166 loc) · 10.9 KB

README.md

File metadata and controls

237 lines (166 loc) · 10.9 KB

license build telegram

an agent that ships as a product

the choices are made. sandboxed by default. lives in telegram. runs on one subscription, shared across agents.

Right Agent in Telegram

the problem · what we picked for you · quick start · what you get · how it stays safe · how it compares · roadmap

the problem

in most agent setups, the agent runs as your user. it can read every file you can read — ssh keys, aws credentials, mcp tokens, every .env under your home.

docker helps with the filesystem. it doesn't help with mcp credentials — they get forwarded into the container as environment variables. the agent, and any bash command it runs, can read them.

getting a working setup also costs a weekend: chat backend, memory store, tunnel, sandbox layer — pick them, wire them.

right agent fixes both. the pieces are picked, the wiring is done, telegram is your only console.

what we picked for you

every agent inside its own sandbox. security first; usability never sacrificed for it. nothing else gets a vote.

we make the choices for you and polish what we ship. the box is closed:

  • chat surface. telegram. dm, groups, topics — polished, with attachments both ways, media groups, voice notes. not a matrix of telegram + slack + discord + web ui.
  • memory. hindsight cloud (semantic recall, recommended) or local MEMORY.md (no cloud dependency). picked at agent init.
  • model provider. your claude subscription. claude -p, no api keys per agent. anthropic has been restricting third-party wrappers — claude -p is first-party, unaffected.
  • tunnel. cloudflared. free, secure, production-grade.
  • sandbox. nvidia openshell, on by default. the only opt-out is for agents that need host access (e.g. computer-use, browser automation), and that's set explicitly per-agent.

the consequence: features arrive slowly. we polish what's here before adding what's next. if a knob isn't exposed, we haven't found a way to add it without making the product worse for everyone already using it.

quick start

prerequisites:

curl -LsSf https://raw.githubusercontent.com/onsails/right-agent/master/install.sh | sh
right init
right up

full install guide: docs/INSTALL.md.

what you get

multiple agents on one subscription

each agent is a separate claude code session in its own sandbox: separate identity, separate memory, separate telegram thread. no per-agent api key. all of them run on your one claude subscription.

memory that survives restarts

two memory backends, picked at agent init.

hindsight cloud stores every turn append-only and recalls what's relevant on the next turn, scoped per-chat. the agent remembers who you are, what you were working on yesterday, and which stack you run, without replaying the whole transcript.

MEMORY.md is a local file the agent maintains itself. no cloud, no semantic recall, simpler.

identity that writes itself

the first session with a fresh agent is a bootstrap, not a chat. the agent answers questions about who it wants to be (name, tone, boundaries, relationship with you) and writes IDENTITY.md, SOUL.md, USER.md itself. those files load into every system prompt afterwards. on restart, on model swap, on upgrade, the agent stays itself.

one place to run it from

after right up, the terminal is done. claude login, mcp authorization, file attachments, cron notifications, /doctor, /reset. all in telegram.

how it stays safe

an agent you leave running long-term will eventually fetch a poisoned webpage, install a hostile skill, or accept a malicious memory through an mcp tool. the design assumes this. what matters is what the agent can reach when it does.

on a typical agent setup, the agent has direct access to:

  • every mcp token in .mcp.json: linear, notion, gmail, sentry, github
  • your claude oauth refresh token
  • your ~/.ssh and dotfiles
  • your source tree
  • your ~/.aws, ~/.config/gcloud, kubectl configs
  • any .env file under your home directory
  • the workspace and memory of every other agent on the host

one compromised turn, and an attacker has all of it.

the sandbox boundary

every claude code session runs inside an nvidia openshell sandbox. the agent reads and writes only inside its own workspace. nothing in ~/.ssh, ~/.aws, ~/.config/gcloud, or your source tree is reachable. no other agent's files are reachable. no escape route.

openshell is purpose-built for ai agents, not a container runtime stretched to fit. tls inspection, domain allowlists, and request logging are per-sandbox primitives.

credentials live outside the sandbox

mcp tokens, oauth refresh tokens, and claude auth live on the host inside a single aggregator process. the sandbox sees a proxy endpoint, never the raw token. four auth patterns are detected and refreshed automatically: oauth, bearer, custom header, query string.

worst case for a compromised agent: it misuses a tool while it's running. it cannot exfiltrate the credential.

the topology

show diagram 
flowchart TB
  U[You]

  subgraph CLOUD["Cloud"]
    direction LR
    TG[Telegram API]
    CF[Cloudflare]
    ANT[Anthropic API]
    HS[(Hindsight Cloud)]
    EXT[(Linear · Notion · Gmail · …)]
  end

  subgraph HOST["Host"]
    B1[Bot · agent one]
    B2[Bot · agent two]
    AGG[MCP Aggregator]
    CFD[cloudflared]
    OS[OpenShell gateway]

    subgraph SANDBOX_1["Sandbox · agent one"]
      A1[Claude Code]
      I1[(Identity)]
    end

    subgraph SANDBOX_2["Sandbox · agent two"]
      A2[Claude Code]
      I2[(Identity)]
    end
  end

  U --> TG
  TG --> CF
  CF --> CFD
  CFD --> B1
  CFD --> B2
  B1 --> TG
  B2 --> TG

  B1 --> A1
  B2 --> A2

  A1 <--> I1
  A2 <--> I2

  A1 --> OS
  A2 --> OS
  OS --> ANT
  OS -->|MCP| AGG

  AGG --> HS
  AGG --> EXT

  style CLOUD stroke:#6b8fbf,stroke-width:2px
  style HOST stroke:#6bbf59,stroke-width:2px
  style SANDBOX_1 stroke:#E8632A,stroke-width:2px
  style SANDBOX_2 stroke:#E8632A,stroke-width:2px
Loading

what egress looks like

outbound traffic from the sandbox goes through openshell's policy engine. tls is terminated per-request. the destination is matched against the domain allowlist, and the request is logged. nothing leaves silently.

the default policy is permissive. one line in agent.yaml switches to restrictive: anthropic and claude endpoints only.

how it compares

typical agent setup right agent
sandbox container, no built-in rules openshell: policy engine, tls inspection
credentials tokens live next to the agent host-side aggregator; agents never see them
mcp secrets copied into every agent one aggregator, one location
memory replay full history each turn append-only; hindsight or local file
identity system prompt in a config file agent writes its own identity files
control surface cli + config + dashboards one telegram thread
claude billing api key per agent one claude subscription
scope configurable everything one opinionated path

other agents ship breadth and leave the wiring to you. right agent ships one path and does the wiring itself.

roadmap

shipped:

  • multi-agent orchestration, sandboxed by default
  • mcp aggregator with auto-detected oauth, bearer, header, query-string auth
  • evolving identity: agent writes its own IDENTITY.md / SOUL.md / USER.md
  • append-only memory: hindsight cloud or local MEMORY.md
  • telegram as single control plane: login, mcp auth, files, cron
  • group chats, topic routing, media groups in both directions
  • declarative cron with telegram notifications
  • agent backup & restore
  • right doctor end-to-end diagnostics

next:

  • credential providers for gh, gcloud, aws, kubectl: zero-token clis inside sandboxes
  • native browser automation
  • agent templates: shareable configs with mcps, skills, identity presets
  • auto-skills: agent writes its own skills from repeated tasks
  • per-turn budget caps for chat (currently cron-only)
  • agent-to-agent communication

full tracker on github issues.

docs

license

apache-2.0.

credits

built on claude code, nvidia openshell, and process-compose.