Skip to content

somora docs ​

somora runs AI agents on your own machine. They remember what you told them, work together as a team, and you talk to them from the browser, the phone or the terminal. This page shows where to start and what each page is for.

What somora is ​

  • Agents with memory. Each agent has its own character, model and notes. Background phases turn finished conversations into notes and into a shared wiki.
  • Your models. A Claude, ChatGPT or Grok subscription, a local model server or an API key. somora brings no model of its own.
  • Three clients. A desktop in the browser, an app for the phone and a terminal client. All talk to the same server.
  • Real work. Agents read and write files, run commands, search the web, drive a browser and hand work to each other.
  • Local first. Conversations, notes and the wiki are plain files on your machine.

Start here ​

bash
curl -fsSL https://somora.ai/install.sh | bash

The installer sets everything up and starts an assistant that connects a model, creates your first agent and sends it a test message. That takes about ten minutes. Setup explains each step.

Choose your path ​

I want to …Open
chat from the browser or the phoneSetup for HTTPS, or run somora setup access. Then Web client and Mobile app.
add a provider or a modelSetup and Models
create another agentAgents
have my agents know who is whoTeam
let an agent do real workTools, then File tools, Resources and tmux
teach an agent a recipeSkills
decide what each agent may useTools, MCP servers and Skills
have an agent build softwareBuilder agents
give agents long-term memoryMemory, Wiki and Dream phases
talk instead of typeVoice and Realtime voice
have agents make images or videoImage generation and Video generation
have agents act on a schedule or when something happensSentinel
chat with agents of other systems (OpenClaw, Hermes)External agents
have my agents hand work to OpenClaw or Hermes, or take work from themA2A
use my agents from an editor such as ZedACP
let a model judge items for scripts and checksDecision models
know what is exposed and to whomSecurity
build my own clientHTTP API

The words somora uses ​

WordMeaning
agentA persona with its own instructions, model, notes and conversations. Lives in ~/.somora/agents/<name>/. A chat agent talks and coordinates. A builder plans and writes software.
sessionOne conversation with one agent. Stored as a file, can be resumed and switched.
engineThe way somora reaches a model: claude-cli (Claude subscription), codex-cli (ChatGPT subscription), grok-cli (SuperGrok or Premium subscription) or openai-compatible (any server or API that speaks the OpenAI chat format).
provider, model, aliasconfig.yaml lists providers and the models on each. An alias is a short name for a model that works everywhere.
memoryAn agent's own short-term notes. Recalled automatically for every message, together with the wiki and your vault.
wikiThe long-term knowledge base shared by all agents. Lives in a folder, usually inside your Obsidian vault.
dream phasesBackground work. REM turns conversations into notes. Deep moves lasting notes into the wiki. Lucid reviews the wiki.
projectA working set of paths and notes pinned to a session, shown to the agent in every turn.
resourceAnother machine reached over SSH. File, shell and tmux tools can target it.
external agentAn agent of another agent system (OpenClaw, Hermes, …) you chat with from somora. It keeps its own model, tools and memory.
A2AThe Agent2Agent standard for agents of different systems giving each other tasks. somora agents hand external agents work with it and take work from them. Between somora's own agents, agent_ask needs no standard.
skillA Markdown how-to the agent loads when the situation calls for it.
toolSomething an agent can call: read a file, run a command, search the web, ask another agent.
sentinelA trigger that starts an agent turn on a schedule, or when a small check script sees that something happened.
decision modelA small model that answers typed questions (yes/no, choice, score) about some data. Agents, scripts and Sentinel checks ask it.

After the first chat ​

  1. Create a second agent with a different job: somora setup agent.
  2. Turn on memory and the wiki: somora setup memory.
  3. Put the app on your phone: Mobile app.
  4. Write the team file once you have two agents: Team.
  5. Add a machine an agent may work on: Resources.
  6. Pin a project to a session: Projects.

All pages ​

Getting started ​

PageReads likeWhen to open it
SetupOperator runbookFirst install, the setup assistant, HTTPS, updates, every command and server setting
ModelsModel referenceModels known to run with somora, per engine, with the config values that work
SecurityTrust modelWho can reach the server, what agents may do, where credentials live

Clients ​

PageReads likeWhen to open it
Web clientBrowser clientThe desktop in the browser, window by window
Mobile appMobile PWAInstalling on the phone, sessions and model, what it can and cannot do
TUI displayTerminal clientWhat the terminal client shows, and every slash command
VoiceDictation and spoken repliesThe microphone in web and mobile, optional spoken answers
Realtime voiceTalking to an agentA standing call you can interrupt: the voice talks, the agent knows

Agents & team ​

PageReads likeWhen to open it
AgentsPersona and agent.yaml referenceCreating an agent, and every per-agent setting
TeamOrg chart for agentsTelling every agent who is who and who to involve
Builder agentsThe builder kindAn agent that builds software: plan, Go, build, with a task panel and questions
ProjectsConcept and workflowPinning a working set to a session
SentinelTrigger runtimeWaking agents on a schedule or when a check script sees a change
External agentsAgents of other systemsChatting with OpenClaw, Hermes and other ACP agents from somora
A2AWork between systemsYour agents ask external agents or send them off as sub-agents, and take tasks from them, over the A2A standard
ACPsomora in an editorsomora acp for Zed, JetBrains and other ACP clients, locally or over SSH

Memory ​

PageReads likeWhen to open it
MemoryConcept and settingsHow agents remember, writing notes by hand, tuning recall
WikiConcept and settingsThe shared knowledge base, its structure, editing by hand
Dream phasesBackground workersWhat REM, Deep and Lucid do, when they run and how to review them
CompactionContext managementWhen and how a session is summarised, which model does it, what contextWindow controls per engine

Tools & integrations ​

PageReads likeWhen to open it
ToolsTool catalogEvery tool an agent can have, and how to limit them per agent
File toolsFile tools in depthWorking with file_read/file_write/analyze_file
Image handlingHow images travelWhich file a model sees and which one a tool gets
Decision modelsTyped decisionsAsking a decision model yes/no, choice and score questions, with images
ResourcesSSH targetsAdding a remote machine
tmuxMulti-turn shell sessionsDriving long-running CLIs from agents
Shared browserShared browserA Chromium per agent profile that agents drive and you can take over for logins
Language serversLanguage serversA builder's writes come back with the compiler's errors
MCP serversExternal MCP serversPlugging third-party MCP tools into your agents
SkillsMarkdown skill formatWriting or installing skills
Image generationText-to-imageGenerating images from the web app or an agent
Video generationText-to-videoJob-based renders, and how an agent gets its result without waiting

Model tuning ​

PageReads likeWhen to open it
ThinkingReasoning depthPer-engine thinking levels, session overrides
SamplingSampling parameterstemperature, top_p and friends per model, agent and session
Prompt cachePrompt-cache mechanicsWhy the system prompt is ordered the way it is

Reference ​

PageReads likeWhen to open it
HTTP APIHTTP and SSE referenceBuilding your own client or integration