A desktop coding agent with free access to frontier models.
OmniRush.ai Server
Filesystem-backed API for OmniRush.ai remote clients. This package provides the OmniRush.ai server layer described in apps/app/pr/omnirush-server.md and is intentionally independent from the desktop app.
Quick start
npm install -g omnirush-server
omnirush-server --workspace /path/to/workspace --approval auto
omnirush-server ships as a compiled binary, so Bun is not required at runtime.
Or from source:
pnpm --filter omnirush-server dev -- \
--workspace /path/to/workspace \
--approval auto
The server logs the client token and host token on boot when they are auto-generated.
Add --verbose to print resolved config details on startup. Use --version to print the server version and exit.
Desktop task recovery
The desktop enables resumeInterruptedTasks when embedding a server that owns
its local engines. Standalone servers, attached engines, remote workspaces, and
read-only servers do not opt in. Recovery works with both OpenCode v1 and v2 and
does not depend on an open conversation tab.
The desktop_task_recovery table in the existing runtime SQLite database stores
up to 1,000 task identities, their workspace path, original engine, last observed
user turn, and recovery phase. It stores no prompts, transcripts, or credentials.
Only tasks admitted after this feature is enabled are tracked; old unfinished
conversations are not swept or resumed retroactively.
On quit or update, a final checkpoint runs before engine teardown with two task snapshots in flight and a 10-second budget. On restart, the coordinator checks two task snapshots every two seconds and admits at most one continuation every two seconds, with at most two recovered tasks active. Already-active native runs are observed, not re-prompted, and native active work also limits new recovery admissions.
Completed, archived, manually stopped, approval/question-blocked, and active delegated work are excluded. New manual work invalidates the old recovery intent. Missing workspaces, changed directories, unavailable policy, and unverified snapshots never authorize a send. V1 requires the original user turn and model in its recent 100-message snapshot; v2 keeps the session's native model. A continuation asks to inspect completed effects first, not rerun the original prompt.
A send is claimed durably before admission. Lost acknowledgements are never blindly retried, even after another restart. Crash recovery requires an observed running task and a still-unfinished matching turn; unexplained aborts stay stopped. Tasks whose admission or shutdown checkpoint cannot be confirmed remain manual. This prevents duplicate recovery admissions, not exactly-once execution of external tools; uncertain earlier effects must be inspected or clarified before continuing.
Desktop Automation and remote-command requests opt out with
x-omnirush-task-recovery: off; their existing execution ownership is unchanged.
Runtime journey verification for actual Electron restarts on both engines remains
separate from the focused coordinator and mocked-proxy tests.
Config file
Defaults to ~/.config/omnirush/server.json (override with OMNIRUSH_SERVER_CONFIG or --config).
{
"host": "127.0.0.1",
"port": 8787,
"approval": { "mode": "manual", "timeoutMs": 30000 },
"workspaces": [
{
"path": "/Users/susan/Finance",
"name": "Finance",
"workspaceType": "local",
"baseUrl": "http://127.0.0.1:4096",
"directory": "/Users/susan/Finance"
}
],
"corsOrigins": ["http://localhost:5173"]
}
Environment variables
OMNIRUSH_SERVER_CONFIGpath to config JSONOMNIRUSH_HOST/OMNIRUSH_PORTOMNIRUSH_TOKENclient bearer tokenOMNIRUSH_HOST_TOKENhost approval tokenOMNIRUSH_APPROVAL_MODE(manual|auto)OMNIRUSH_APPROVAL_TIMEOUT_MSOMNIRUSH_WORKSPACES(JSON array or comma-separated list of paths)OMNIRUSH_CORS_ORIGINS(comma-separated list or*)OMNIRUSH_OPENCODE_BASE_URLOMNIRUSH_OPENCODE_DIRECTORYOMNIRUSH_OPENCODE_USERNAMEOMNIRUSH_OPENCODE_PASSWORD
Token management (scoped tokens):
OMNIRUSH_TOKEN_STOREpath to token store JSON (default: alongsideserver.json)
File injection / artifacts:
OMNIRUSH_INBOX_ENABLED(1|0)OMNIRUSH_INBOX_MAX_BYTES(default: 50MB, capped)OMNIRUSH_OUTBOX_ENABLED(1|0)
Sandbox advertisement (for capability discovery):
OMNIRUSH_SANDBOX_ENABLED(1|0)OMNIRUSH_SANDBOX_BACKEND(docker|container|none)
Endpoints
GET /healthGET /statusGET /capabilitiesGET /whoamiGET /workspacesGET /workspace/:id/configPATCH /workspace/:id/configGET /workspace/:id/eventsPOST /workspace/:id/engine/reloadGET /workspace/:id/pluginsPOST /workspace/:id/pluginsDELETE /workspace/:id/plugins/:nameGET /workspace/:id/skillsPOST /workspace/:id/skillsGET /workspace/:id/mcpPOST /workspace/:id/mcpDELETE /workspace/:id/mcp/:nameGET /workspace/:id/commandsPOST /workspace/:id/commandsDELETE /workspace/:id/commands/:nameGET /workspace/:id/auditGET /workspace/:id/export
Token management (collaborator or owner bearer token):
GET /tokensPOST /tokens(body:{ "scope": "owner"|"collaborator"|"viewer", "label"?: string })DELETE /tokens/:id
Inbox/outbox:
POST /workspace/:id/inbox(multipart upload into.opencode/omnirush/inbox/)GET /workspace/:id/artifactsGET /workspace/:id/artifacts/:artifactIdPOST /workspace/:id/files/sessionsDELETE /files/sessions/:sessionIdGET /files/sessions/:sessionId/catalog/snapshotPOST /files/sessions/:sessionId/ops
UI control mailbox:
POST /experimental/ui-control/request(collaborator or owner bearer token)GET /experimental/ui-control/pending(collaborator or owner bearer token; optional?wait=1)POST /experimental/ui-control/:id/reply(collaborator or owner bearer token)
Desktop and web renderers poll the same server they are connected to. The first polling window claims each request; commands are never broadcast to every tab. Requests expire after five seconds, and a server with no recent renderer poll returns an explicit no-window result. The external desktop UI MCP bridge remains available; in-app tools no longer discover or fall back to that bridge.
OpenCode proxy:
GET|POST|... /opencode/*GET|POST|... /w/:id/opencode/*
Approvals
All writes are gated by host approval.
Best practices
Settings > General has a Best practices switch. It starts on. The local runtime database keeps the choice for this server across restarts. The setting is independent of account sign-in and workspace files.
The bundled pack adds a short development prompt and nine guides the agent can load when needed. Off removes the pack's prompt and skill path. It preserves the swarm and user-installed skills. The pack is stored beside the runtime skills folder, outside all projects. It has no runtime download, private-note reader, or account-sync path.
GET /runtime-config/best-practicesreturns{ "enabled": true }or false.PUT /runtime-config/best-practicesaccepts only{ "enabled": boolean }. It requires client authentication and collaborator scope. Organization settings restrictions still apply.- A write returns the saved
enabled,changed, andengine.status:applied,deferred,failed, orunconfigured. A deferred change lets the current reply finish. A failed apply keeps the saved choice and the UI asks for Reload. It does not claim that the engine changed.
The server statically imports the MIT pack
so Node builds and compiled Bun binaries carry the same pinned source and
license. See its source and per-skill sourceSha256 fields when updating it.
This feature does not change the app's existing account or data settings.
Host APIs accept either:
X-OmniRush-Host-Token: <token>(legacy host token), orAuthorization: Bearer <token>where the token scope isowner.
Approvals endpoints:
GET /approvalsPOST /approvals/:idwith{ "reply": "allow" | "deny" }
Set OMNIRUSH_APPROVAL_MODE=auto to auto-approve during local development.
Automatic title recovery
The managed v1 engine ships a title-only compatibility plugin. If a provider
returns HTTP 400 with unsupported_value or unsupported_parameter for
reasoning.effort, reasoning_effort, temperature, or top_p, it makes at
most one corrected request. It uses a reported supported effort or omits the
rejected optional parameter so the same model can use its default. Provider,
model, credentials, conversation content, and normal chat options stay intact.
Access, quota, transport, and unrelated request errors do not trigger an added
recovery request. The engine's own transport retry policy still applies.
Engine log records with service omnirush.title / message Automatic title generation contain only session/provider/model IDs, outcome, recovery attempt,
HTTP status, and the rejected parameter name. accepted_after_recovery means
the provider accepted the retry; title_available separately confirms a real
title was observed in a session update. An accepted request with no title update
within 60 seconds is title_unconfirmed, which can mean empty output, a stream
failure, or missing persistence; it is not reported as success. The app's
existing bounded placeholder probes and warning remain the user-facing safety
net. Existing untitled conversations are not bulk-regenerated.