Getting Started

Installation

RobiOS ships as a CLI plus a runtime. Node 20+ or Bun 1.1+ required.

# with npm
npm install -g @robios/cli

# or with bun (recommended)
bun add -g @robios/cli

# verify
robi --version

Authentication

robi auth login        # opens the browser, links your wallet
robi workspace list    # pick a billing workspace

Your keys never leave the machine: the CLI stores a scoped session token in ~/.robi/credentials and signs chain transactions locally.

Getting Started

Quickstart

From zero to a live agent in five minutes.

robi create trader-bot
cd trader-bot
robi dev

robi create scaffolds a standard project and asks which template you want: trader, builder, social, research or blank.

Talk to your agent

> robi chat
you: scan the top movers on Robinhood Chain
trader-bot: 4,281 pairs scanned. 3 setups match your risk profile…

Ship it

robi deploy            # contracts + agent runtime on-chain
robi publish           # list it on the Agent Marketplace

Core Concepts

Agents & Characters

An agent is a running instance of a character: a declarative personality file.

// src/character.ts
import { Character } from '@robios/core';

export const character: Character = {
  name: 'MemeHunter',
  bio: 'Finds meme tokens before they trend. Paranoid about bundles.',
  style: ['terse', 'data-first', 'never financial advice'],
  triggers: ['new_pair', 'volume_spike', 'kol_mention'],
  tools: ['chain.scan', 'x.search', 'bundle.detect'],
  risk: { maxPosition: '2%', stopLoss: '8%' },
};

Lifecycle

Characters are validated at build time. At runtime the agent receives events from its triggers, plans with its model, and acts through tools: every action is signed and logged on-chain.

Multiple agents

// src/index.ts
import { Project } from '@robios/core';
import { trader } from './agents/trader';
import { researcher } from './agents/researcher';

const project: Project = {
  agents: [trader, researcher],
  pipeline: ['researcher', 'trader'],   // researcher feeds trader
};
export default project;

Core Concepts

Runtime & Lifecycle

The RobiOS runtime schedules agents, routes events and settles actions on Robinhood Chain.

Run loop

event → perceive → plan → act → settle → learn

• perceive: normalize the trigger (chain event, social signal, user prompt).
• plan: the model proposes an action plan within the character's risk bounds.
• act: tools execute; DeFi actions are simulated first, then signed.
• settle: the transaction confirms on Robinhood Chain; receipts stored in memory.
• learn: outcomes update the agent's episodic memory.

Services

Long-lived connections (websockets, X streams, mempool watchers) run as services owned by the runtime, so agents restart cleanly without dropping state.

Core Concepts

Memory & State

Agents remember. RobiOS ships a three-layer memory out of the box.

• Working state: the current run's context; discarded on completion.
• Episodic memory: past runs, trades and outcomes; embedded and searchable.
• Knowledge (RAG): documents you pin: strategies, docs, tokenlists.

const memories = await runtime.memory.search({
  query: 'last time $HOOD dipped 8% intraday',
  scope: 'episodic',
  limit: 5,
});

Local development uses an embedded PGLite database in .robi/; deployed agents use chain-anchored storage with the same API.

Projects

Projects Overview

A project is the top-level, deployable workspace. One agent or a swarm: same layout.

Standard project

my-project/
├── src/
│   ├── index.ts          # project entry: exports agents
│   ├── character.ts      # the agent's personality
│   ├── plugins/          # project-local plugins
│   └── __tests__/        # component + e2e tests
├── .env                  # secrets (never committed)
├── robi.config.ts        # chain, model, billing
├── package.json
└── .robi/                # runtime data: db, cache (gitignored)

Multi-agent project

swarm-project/
├── src/
│   ├── index.ts          # combines all agents + pipeline
│   └── agents/
│       ├── researcher.ts
│       ├── trader.ts
│       ├── builder.ts
│       └── kol.ts

Commands

robi start                          # run the project
robi dev                            # hot reload
robi start --character ./alt.ts    # swap the character
robi test                           # run all tests

Projects

Environment Variables

Secrets live in .env. The runtime validates them at boot.

# model providers (one required)
ANTHROPIC_API_KEY=sk-ant-…
OPENAI_API_KEY=sk-…

# chain
ROBINHOOD_CHAIN_RPC=https://rpc.robinhood.chain
ROBI_WALLET_KEY=0x…              # signing key (or use robi auth)

# integrations (optional)
X_BEARER_TOKEN=…
TELEGRAM_BOT_TOKEN=…

# runtime
ROBI_LOG_LEVEL=info
ROBI_MAX_DAILY_SPEND=250         # hard cap, USD

robi env pull syncs deployed secrets down; robi env push uploads local changes. Values are encrypted at rest.

CLI Reference

robi CLI

Everything RobiOS can do fits in one binary.

USAGE
  robi <command> [flags]

CORE
  create        scaffold a new project
  start         run the project
  dev           development mode, hot reload
  test          run component + e2e tests
  chat          talk to a running agent

CHAIN
  deploy        ship agents + contracts to Robinhood Chain
  publish       list the agent on the Marketplace
  vault         manage portfolio vaults
  launch        launchpad: token from a prompt

ACCOUNT
  auth          login / logout / token
  env           pull / push encrypted secrets
  workspace     billing workspaces

Examples

robi launch etf --top10 --name HOOD10
robi scan whales --24h --min 1m
robi build "landing for $DRIFT"

These are the same commands the Robi Terminal accepts: try them there.

CLI Reference

Deploy to Robinhood Chain

One command builds, simulates, signs and ships.

robi deploy
✓ compiled 2 agents
✓ simulated 14 actions: 0 reverts
✓ contracts verified: 0xd1fe…17
✓ runtime live: https://my-agent.robi.app
$ROBI staked as agent bond: 5,000

What the bond does

Every deployed agent stakes a $ROBI bond. Misbehaving agents (failed simulations, spam, oracle abuse) get slashed; honest uptime earns yield from the treasury.

Rollbacks

robi deploy --list          # deployment history
robi rollback <deploy-id>   # instant revert

Plugins

Plugin Registry

Capabilities are plugins. Install what your agent needs, nothing else.

robi plugins add @robios/defi-robinhood   # swaps, vaults, staking
robi plugins add @robios/x                # X/Twitter read+post
robi plugins add @robios/telegram         # TG bot transport
robi plugins add @robios/knowledge        # RAG over your docs
robi plugins add @robios/bundle-detect    # anti-rug heuristics

Write your own

import { definePlugin } from '@robios/core';

export default definePlugin({
  name: 'my-oracle',
  tools: {
    'oracle.price': async ({ symbol }) => fetchPrice(symbol),
  },
  services: [priceStream],
});

Publish with robi publish --plugin: the registry reviews for malicious tool patterns before listing.

REST API

API Reference

Every deployed project exposes a REST + WebSocket API.

BASE  https://api.robi.app/v1

POST  /agents/:id/runs          # start a run { prompt, params }
GET   /agents/:id/runs/:run     # status + result
GET   /agents/:id/memory?q=     # search episodic memory
POST  /agents/:id/message       # chat transport
GET   /runs/:run/logs           # streamed logs (SSE)
WS    /ws?agent=:id             # live events

Example

curl -X POST https://api.robi.app/v1/agents/meme-hunter/runs \
  -H "Authorization: Bearer $ROBI_TOKEN" \
  -d '{ "prompt": "scan fresh pairs, flag bundles" }'

{ "run": "run_8f3k2", "status": "queued" }

Resources

$ROBI Tokenomics

$ROBI aligns agents, builders and the community.

• Agent bonds: deployed agents stake $ROBI; slashing keeps the swarm honest.
• Compute credits: runs are metered in $ROBI; holders get boosted rates.
• Campaign rewards: community campaigns pay contributors from project pools.
• Governance: plugin registry listings and treasury spend are token-voted.

robi stake 5000          # boost every agent you run
robi vault create --risk balanced
robi claim               # campaign rewards

See live staking and campaigns on the Campaigns board.