Open source · MIT · local-first
An agent identity is a stateful interface, not a profile image.
Orbsona separates a stable visual identity from live runtime state. Relief, motion system, palette, and seed remain recognizable while the composition responds to what the agent is doing.
MIT licensed
The Studio and renderer are open source. You can use, modify, distribute, and ship them under the MIT License.
Local-first
Studio saves one working draft in browser storage. There is no Orbsona account, database, cloud sync, or analytics service.
Provider-neutral
The package exposes semantic states. It does not bundle or claim first-party adapters for voice or agent providers.
Layered identity system
Relief meets living geometry
A deterministic relief establishes the agent’s body. A foreground motion system establishes its behavior. Orbsona’s new presets translate structures found in living systems into reproducible geometry, while the original thinking-orbs collection remains available under its MIT license.
Motion systems
phyllotaxisOrbsonaGolden-angle growth found in flowers and seed heads
radiolariaOrbsonaA rotating lattice inspired by microscopic silica shells
fieldMIT collectionUndulating multi-band sash
orbitMIT collectionParticles on tilted orbits
globeMIT collectionScanning dotted meridians
waveMIT collectionRolling latitude waveform
solveMIT collectionReorganizing spherical bands
pulseOrbsonaConcentric signal rings
Relief families
reliefOrganic mineral terrain
dunesWind-shaped parallel ridges
strataLayered geological terraces
currentsDirectional flowing relief
Public npm package
Install the renderer
npm, pnpm, Yarn, and Bun install the same public @accidental-revenue/orbsona release. Choose the manager already used by your application.
npm install @accidental-revenue/orbsonaWhy agents need identity
Communicate state
A voice agent has long silent intervals. Motion shows whether it is listening, reasoning, speaking, using a tool, or waiting for help.
Preserve continuity
The same visual identity can follow an agent across a call screen, support widget, dashboard, and embedded workflow.
Support, do not replace, language
Animation is an ambient signal. Product UI still needs labels, announcements, and explicit error messages for accessibility.
Identity format v2
Runtime state contract
AgentStateidleAvailable and waitingconnectingEstablishing a live sessionlisteningReceiving user inputthinkingReasoning before respondingspeakingReturning voice outputworkingCalling a tool or completing a tasksuccessThe requested action completederrorThe session needs attentionReact 18+ · ESM
Component API
identityAvatarIdentityThe stable visual configuration.stateAgentStateThe agent's current semantic state.sizenumber | stringRendered width and height.energynumberGeneral signal level from 0 to 1.inputLevelnumberOptional microphone or listening level.outputLevelnumberOptional speech-output level.classNamestringClass name applied to the canvas wrapper.styleCSSPropertiesInline styles applied to the canvas wrapper.Portable identity file
{
"format": "orbsona.identity",
"version": 2,
"identity": {
"name": "Aster",
"background": "relief",
"rotateBackground": false,
"grain": false,
"animation": "phyllotaxis",
"palette": {
"id": "ion",
"name": "Ion",
"colors": ["#77c8ff", "#214bb4", "#e0f7ff"]
},
"seed": 2718
}
}Rendering guarantees
- Reduced motion. Movement becomes restrained when the operating system requests it.
- Bounded rendering. The canvas caps pixel density to avoid unnecessary GPU work.
- Semantic state. Provider events map to a small, stable set of agent states.
- Versioned files. Version 1 identities migrate deterministically; unknown versions are rejected safely.
- Stable seeds.
identityFromSeedretains the v1 mapping;identityFromSeedV2opts into the expanded catalog.
Ownership model
Your identity lives with your code.
Studio keeps one working draft in this browser so a refresh does not erase your work. Download the .orbsona.json file and commit it with your application. That file is the portable source of truth, and you can import it back into Studio whenever you want to edit it.
Create
Tune one browser draft in Studio.
Own
Download and version the identity file.
Run
Map your agent events to semantic states.
Included today
- Visual Studio with one browser-saved working draft
- Import and export for versioned identity JSON
- React canvas renderer and TypeScript contract
- PNG and WebM fallback exports
Deliberately not included
- User accounts, subscriptions, or a hosted backend
- Cloud identity storage or cross-device synchronization
- Analytics, telemetry, or identity uploads
- Provider-specific SDK adapters or hosted event relays
License
Build on it freely.
Orbsona is distributed under the MIT License, including the repository-level Studio and the @accidental-revenue/orbsona package. Keep the copyright and permission notice with copies or substantial portions of the software.