ORKESTR OPEN SOURCE
Run your coding agent, leave your desk, and stay in control.
Orkestr is an open-source runtime that keeps agent jobs running on your own machine or VPS. It is built so jobs resume after restarts, sensitive actions wait for your approval, and every run leaves an audit record. Exactly what has been verified so far, and how, is listed in the status table below.
WHAT ORKESTR OSS IS
A runtime for agent jobs that outlive your terminal.
- Persistent agent runtime
- An Agent Job has a trigger (API, webhook, schedule or message), an agent, a task, tool permissions and notifications. Its state is on disk, so a crash or deploy does not lose the run, and recovery reconciles side effects instead of blindly repeating them.
- Self-hosted
- You run it on infrastructure you control. No account with us is needed; the only credentials are the provider and connector logins you choose to add.
- No telemetry
- The runtime does not send usage data to us. It talks to the providers and connectors you configure.
- Provider-independent
- Providers sit behind one adapter interface, so a job is not tied to one vendor. Today only Codex jobs are verified on a real provider; see the status table below.
ONE-MINUTE QUICKSTART
Try the simulation.
SIMULATION orkestr demo uses a simulated AI and a fake code host in a throwaway directory. No API key and no account are needed, and no real job is created. Cloning and npm ci download the code; after that, the demo itself makes no network calls.
It queues a job, kills the worker after a pull request was opened, recovers without opening a second one, pauses for approval before merging, and prints the audit trail and guarantee checks.
git clone https://github.com/otcan/orkestr.git
cd orkestr
npm ci
# SIMULATION: simulated AI, fake code host, no real job
node apps/cli/bin/orkestr-oss.js demo --yesWITH A REAL PROVIDER
Run your first real job.
Real jobs need a connected provider on the same host. Codex is the verified path today: run codex login first.
node apps/cli/bin/orkestr-oss.js init my-jobs # writes a job for your connected provider
node apps/cli/bin/orkestr-oss.js run my-jobs
node apps/cli/bin/orkestr-oss.js jobs listWith the package on your PATH (for example via npm link), the commands are orkestr init and orkestr run. If no provider is connected, orkestr init stops and tells you to connect one. Real jobs never fall back to the simulation.
WHAT WORKS TODAY
Capability status, without rounding up.
Each row says how it was checked: simulation, offline tests, or a live run. Anything not listed here should be treated as unverified.
| Capability | Status | Evidence | Details |
|---|---|---|---|
| Codex jobs | live-verified once on production build (approval pause -> approve -> single-use approval consumed, effect ledgered) | Live-verified | Tested configuration: Codex CLI 0.157.1 job, approval-gated file change, live-verified once on release main-a343edf1ac91 (one controlled run, isolated ORKESTR_HOME, synthetic content). One run is not a reliability measurement; other Codex versions and tool mixes are untested. |
| Claude Code jobs | NOT supported yet (permission hook not enforced in live test; refused unless configured) | Offline-tested | Not working. The executor passes its offline tests with a fake Claude CLI, but the one live test failed: the per-call permission hook did not run, so tool approvals were not enforced. Production refuses Claude Code jobs unless a job login is configured. A host whose own Claude login is active can still start them today; set ORKESTR_AGENT_JOB_CLAUDE_CODE_EXECUTOR=0 to turn them off. |
| YAML/JSON job specs | verified | Live-verified | Tested configuration: a YAML job spec loaded by the released CLI on release main-9b92e3c47f3d; JSON job specs loaded on earlier released builds. Specs are validated before a job is registered. |
| WhatsApp/email notifications | built, not live-verified | Offline-tested | The dispatcher delivers each notification at most once in tests. No real job notification has been sent yet. |
| Webhooks (HMAC) | built and tested offline | Offline-tested | Signed trigger endpoint and signed outgoing webhooks (HMAC-SHA256), covered by automated tests only. |
| Guarantees G1-G11 | tested with simulated/fake providers | Simulation | Durable admission, dedupe, at-most-once effects, approvals, audit, notification-once and cancellation are tested with the simulated provider and a fake code host. The single-use approval path has additionally been seen once on a live Codex run (row above). |
| orkestr demo | simulation by design | Simulation | Uses a simulated AI and a fake code host in a throwaway home directory. It shows the runtime's crash recovery and approval flow; it does not call a real model. |
- Simulation
- Exercised only with the built-in simulated provider or fake external systems. No real model and no real external service took part.
- Offline-tested
- Real code paths covered by automated tests without network access or real accounts. Not yet observed against a live service.
- Live-verified
- Observed working on a real provider or a released build, in a controlled test run with synthetic content.
PUBLIC-ALPHA LIMITS
What this page is not.
- There is no public or hosted job runner here. Jobs run only on a machine you install Orkestr on.
- After this page loads, it sends nothing back: no analytics, no data uploads. It has no forms and runs no page code.
- Interfaces, job spec fields and CLI output can change between releases.
- Self-hosting means you own security, backups and updates for that machine.
- The simulation demonstrates the runtime's recovery and approval logic. It says nothing about the quality of any real model.
READ THE SOURCE AND THE SPEC
Check every claim yourself.
- GitHub repositorySource, issues and the MIT license.
- docs/quickstart.mdThe simulation and your first real Agent Job.
- docs/spec/agent-job.mdAgent Job: trigger, agent, task, permissions, runtime policy, notifications
- docs/spec/agent-job-runner.mdHow the runner works today, including what is runnable per provider
- docs/spec/runtime-guarantees.mdGuarantees G1-G11, non-guarantees and the failure model
- docs/spec/adapter-interface.mdThe interface every provider adapter implements
- docs/spec/conformance.mdThe adapter conformance suite