Public setup docs
Connect Orbiter to the coding agent you already use.
Choose your tool, follow the setup path, and add mobile approval control, policy, and auditability around the AI coding workflow you already trust.
Get the Orbiter Dev app on iPhone or iPad.
Add Orbiter to your IDE, CLI, or MCP-compatible agent host.
Route important agent decisions to mobile with a clear record.
Integration availability
orbiterdev.ai/setup
Install Orbiter Dev
Download Orbiter Dev from the App Store. You can also use the QR page when you are opening setup on a desktop screen.
Sign in and pair your first coding agent
- Open Orbiter Dev on iPhone or iPad.
- Sign in with the same GitHub or Google account you use for development.
- Open Settings -> Pair IDE.
- Generate a pairing code and enter it when your IDE or agent asks for Orbiter authentication.
Keep notifications ready
Approval requests are time-sensitive. Enable notifications for Orbiter Dev in iOS Settings so Face ID-gated decisions arrive promptly.
Review approvals with context
Approval cards show the proposed action, command or file context, risk level, available diff summary, and agent notes. Approve or reject from the app so the agent can continue or stop cleanly.
Run the Codex setup command
Run this from the terminal you use for Codex. The command is safe to copy into an existing config because it merges Orbiter-managed entries instead of replacing the whole file.
Merges Orbiter MCP and supported hooks into the Codex config while keeping unrelated settings intact.
npx -y @orbiterdev/mcp-server@0.1.12 codex setup --adapter http --server-url https://api.orbiterdev.ai --hook-profile full --approval-timeout 300Pair Codex with the mobile app
- Open Orbiter Dev -> Settings -> Pair IDE.
- Ask Codex to authenticate with Orbiter or call the Orbiter auth tool from the MCP server.
- Paste the pairing code when prompted.
- Confirm Codex reports a verified pairing token.
Use hooks for high-risk decisions
Codex can surface lifecycle and command decisions before work proceeds. Orbiter uses those moments to show the proposed action, risk, and context on mobile.
{
"hooks": {
"PermissionRequest": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "npx -y @orbiterdev/mcp-server@0.1.12 permission-check"
}
]
}
]
}
}Check the installation
Run doctor after setup, after changing Codex config, or when approval requests stop arriving.
Checks Codex config, hook support, backend mode, and pairing readiness.
npx -y @orbiterdev/mcp-server@0.1.12 codex doctor --check-backendManual MCP fallback
If you prefer to edit MCP config by hand, add the Orbiter server entry and then restart Codex so it reloads tools.
{
"mcpServers": {
"orbiter-dev": {
"command": "npx",
"args": ["-y", "@orbiterdev/mcp-server@0.1.12"],
"env": {
"ORBITER_SERVER_URL": "https://api.orbiterdev.ai"
}
}
}
}Add the MCP server
Create or edit the Claude Code MCP settings file for your project and include Orbiter as a server.
{
"mcpServers": {
"orbiter-dev": {
"command": "npx",
"args": ["-y", "@orbiterdev/mcp-server@0.1.12"],
"env": {
"ORBITER_SERVER_URL": "https://api.orbiterdev.ai"
}
}
}
}Restart Claude Code
Restart or reload the Claude Code session after changing MCP settings so Orbiter tools become available in the active context.
Add permission routing
Use a permission hook when you want Claude Code shell decisions to pause for Orbiter review before continuing.
Routes Claude Code permission events through Orbiter before risky shell actions continue.
npx -y @orbiterdev/mcp-server@0.1.12 permission-check{
"hooks": {
"PermissionRequest": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "npx -y @orbiterdev/mcp-server@0.1.12 permission-check"
}
]
}
]
}
}Pair with iPhone or iPad
- Open Orbiter Dev -> Settings -> Pair IDE.
- Have Claude Code call the Orbiter auth tool.
- Paste the pairing code.
- Send one low-risk test approval before relying on the flow for critical work.
Install the extension path
Use the Orbiter Dev extension from the marketplace channel supported by your Antigravity build or compatible VS Code-style host.
Run Antigravity setup
Run this from the target Antigravity workspace, or add --workspace <workspace>. Antigravity stores hooks per project/worktree, so repeat setup for each workspace where approvals should fire.
Adds Orbiter MCP and blocking approval hooks for supported Antigravity workspaces.
npx -y @orbiterdev/mcp-server@0.1.12 antigravity setup --adapter http --server-url https://api.orbiterdev.ai --profile blocking --fallback deny --approval-timeout 300 --configure-native-command-policyCheck native command-policy readiness
Antigravity workspaces can have their own command policy. Use doctor to confirm the workspace will let Orbiter-approved actions continue after mobile approval.
Checks project hook config, native command-policy readiness, and Orbiter backend mode.
npx -y @orbiterdev/mcp-server@0.1.12 antigravity doctor --check-backendPair and test
- Open Orbiter Dev -> Settings -> Pair IDE.
- Run the Orbiter auth flow from Antigravity or the MCP server.
- Send a harmless test command through the hook path.
- Confirm the iOS decision returns to the Antigravity session.
Manual MCP fallback
If you are only using Antigravity MCP settings, add the Orbiter server entry and restart the session.
{
"mcpServers": {
"orbiter-dev": {
"command": "npx",
"args": ["-y", "@orbiterdev/mcp-server@0.1.12"],
"env": {
"ORBITER_SERVER_URL": "https://api.orbiterdev.ai"
}
}
}
}Run Gemini CLI setup
The setup command adds Orbiter MCP and guarded hook behavior for Gemini CLI workspaces that support local settings.
Adds Orbiter MCP and guarded hooks for Gemini CLI workspaces.
npx -y @orbiterdev/mcp-server@0.1.12 gemini setup --adapter http --server-url https://api.orbiterdev.ai --profile guardedPair the CLI with Orbiter Dev
- Open Orbiter Dev -> Settings -> Pair IDE.
- Have Gemini CLI call the Orbiter auth tool or follow the pairing prompt.
- Paste the pairing code.
- Confirm the paired status before using higher-risk actions.
Use guarded hooks
Guarded hooks let Orbiter review protected commands while allowing routine work to continue under your chosen policy.
{
"hooks": {
"PermissionRequest": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "npx -y @orbiterdev/mcp-server@0.1.12 permission-check"
}
]
}
]
}
}Run doctor
Doctor checks workspace settings, hook wiring, and backend mode.
Checks Gemini workspace settings, hook wiring, and backend mode.
npx -y @orbiterdev/mcp-server@0.1.12 gemini doctor --check-backendOpen Cursor MCP settings
- Open Cursor Settings.
- Find the MCP servers section.
- Add a new server named orbiter-dev.
- Use npx as the command and @orbiterdev/mcp-server@0.1.12 as the package argument.
Use raw config when needed
If your Cursor version accepts JSON config, use the same Orbiter server entry below.
{
"mcpServers": {
"orbiter-dev": {
"command": "npx",
"args": ["-y", "@orbiterdev/mcp-server@0.1.12"],
"env": {
"ORBITER_SERVER_URL": "https://api.orbiterdev.ai"
}
}
}
}Pair from the mobile app
- Open Orbiter Dev -> Settings -> Pair IDE.
- Ask Cursor to authenticate with Orbiter through the MCP tool.
- Paste the pairing code.
- Run a low-risk approval request to confirm the route.
What Cursor gets from Orbiter
Orbiter adds a focused mobile approval path, progress reporting, notifications, and decision history through MCP tools. Host-level hooks depend on what your Cursor build exposes.
Open Windsurf MCP settings
- Open Windsurf settings.
- Find the MCP servers or custom tools section.
- Add a server named orbiter-dev.
- Use the npx package command for @orbiterdev/mcp-server@0.1.12.
Use raw config when needed
If the Windsurf build accepts raw JSON, use this Orbiter MCP server entry.
{
"mcpServers": {
"orbiter-dev": {
"command": "npx",
"args": ["-y", "@orbiterdev/mcp-server@0.1.12"],
"env": {
"ORBITER_SERVER_URL": "https://api.orbiterdev.ai"
}
}
}
}Pair and verify
- Open Orbiter Dev -> Settings -> Pair IDE.
- Ask Windsurf to authenticate through Orbiter MCP.
- Paste the pairing code.
- Confirm a test approval reaches the mobile app.
What Windsurf gets from Orbiter
Orbiter gives Windsurf sessions a cross-agent approval protocol and a mobile decision trail. The exact hook depth depends on the host capabilities available in your Windsurf version.
Check prerequisites
Install Node.js 18 or newer, install Orbiter Dev on iPhone or iPad, and confirm your host can add a custom MCP server.
Add the Orbiter server
Most MCP hosts need a server name, command, args, and environment. Use this config as the reference shape.
{
"mcpServers": {
"orbiter-dev": {
"command": "npx",
"args": ["-y", "@orbiterdev/mcp-server@0.1.12"],
"env": {
"ORBITER_SERVER_URL": "https://api.orbiterdev.ai"
}
}
}
}Pair the host
- Open Orbiter Dev -> Settings -> Pair IDE.
- Start or reload the MCP host.
- Call the Orbiter auth tool.
- Paste the pairing code.
Use the available MCP tools
The public server supports pairing, token verification, approval requests, heartbeats, checkpoints, notifications, tool outcomes, usage reports, approved memory, stop requests, and project guidance.
Keep raw command text handy
If your host asks for a command instead of JSON, use npx with the Orbiter MCP server package.
Use this command in MCP hosts that separate command and args fields.
npx -y @orbiterdev/mcp-server@0.1.12Pairing code expired
Generate a new code from Settings -> Pair IDE in the iOS app, then retry the pairing flow from your IDE or agent host.
Notifications do not arrive
- Confirm iOS notifications are enabled for Orbiter Dev.
- Confirm the mobile app is logged in.
- Confirm the IDE or MCP server is paired.
- Try once without a strict VPN or corporate proxy.
What to include in support
Send device type, iOS version, IDE or agent host, approximate time, and safe screenshots with private values removed. Keep API keys, auth tokens, private code, payment details, and credentials out of support messages.
Sales and team enquiries
Use the support form for governance, security review, rollout support, custom policies, discount interest, and early team-plan conversations.
What the export contains
It mirrors public setup paths for the mobile app, Codex, Claude Code, Antigravity, Gemini CLI, Cursor, Windsurf, generic MCP hosts, support, billing, and FAQ guidance.
Current public docs version
Version 2026.06.19.2 covers the IDE-first setup model, MCP 0.1.12 commands, iOS empty-approval troubleshooting, Windows launcher guidance, and public AI-readable setup docs.
Best use
Give the Markdown link to an assistant when you want it to help a user configure Orbiter Dev from public instructions only.
Windows one-time setup
Enable Open PowerShell buttons.
Run this once on Windows to register Orbiter's local setup launcher for your user account. After that, the Open PowerShell buttons can open a local PowerShell window with the selected setup command.
The launcher accepts fixed Orbiter setup actions only. It does not run arbitrary command text from the browser URL.
$p = Join-Path $env:TEMP 'orbiterdev-windows-launcher.ps1'; Invoke-WebRequest '__ORIGIN__/download/orbiterdev-windows-launcher.ps1' -OutFile $p; powershell -NoProfile -ExecutionPolicy Bypass -File $pFAQ and troubleshooting
Frequently asked questions
These answers stay consistent across the website and the AI-readable export.
My extension shows '[gRPC] TLS disconnect' warnings
This can appear when no AI agent session is active. The extension checks for an available local agent-side connection and reconnects when a session is available. Update to the latest Orbiter Dev extension if repeated idle warnings are noisy.
Walkthrough doesn't open on install
The walkthrough only shows once per extension version. To re-open it, run Ctrl+Shift+P and choose 'Orbiter: Open Onboarding Guide'.
Extension buttons in walkthrough don't work
Make sure you're running the latest Orbiter Dev extension from VS Code Marketplace or OpenVSX, then re-open the walkthrough from the command palette.
Push notifications aren't arriving
Check that iOS notifications are enabled for Orbiter Dev, that you are signed in, and that the IDE or MCP server is paired. If you use a corporate proxy or VPN, try once without it because strict network filters can interrupt approval delivery.
Pairing code expired
Pairing codes expire after a short window. Open Orbiter Dev on iPhone or iPad, go to Settings -> Pair IDE, generate a new code, and retry from your IDE or agent host.
WebSocket keeps disconnecting
Long-lived approval connections can be interrupted by corporate proxies, VPNs, captive portals, or unstable Wi-Fi. The extension and app retry automatically; if approvals do not resume, reconnect on a stable network and contact support with the approximate time.
MCP tools not showing in Claude Code
Check that your MCP settings file exists, that the JSON syntax is valid, and that the agent host was restarted after editing settings. Run 'npx @orbiterdev/mcp-server --version' to confirm the package can install.
iOS shows no approval requests
First run the provider doctor command with --check-backend. Then confirm the setup uses https://api.orbiterdev.ai, the IDE or MCP profile is paired with the same account as the iOS app, and the app refreshes while foregrounded. Push notifications affect alerts; a healthy foreground refresh should still show pending approvals.
MCP server returns 401
Your credential may be expired or missing. Sign in again from the extension or repeat the MCP pairing flow from Orbiter Dev on iOS.
Approval requests are delayed
The most common causes are network instability, push notification settings, or an IDE/agent host that is no longer paired. Check the iOS notification setting, confirm the pair status, and keep the host machine online while the agent is working.
Can I use both Extension and MCP?
Yes. Use both when your workflow supports both paths. The extension adds IDE-side capture and policy controls; the MCP server adds agent tools such as approval requests, heartbeats, checkpoints, notifications, usage reports, and session memory.
Is my code sent to Orbiter servers?
Orbiter routes approval metadata, command or file context, risk levels, timestamps, decisions, and user-requested review context so the mobile app can show what needs approval. Do not send private source code or secrets in support requests.
How do I uninstall?
Extension: use the editor's extension uninstall command. MCP: remove the orbiter-dev entry from your MCP settings file. Mobile: delete the app. To remove account data, open Orbiter Dev iOS -> Settings -> Account Controls -> Delete Account, or email support@orbiterdev.ai.
The app says too many requests or too many connections
Wait about a minute and retry. If approvals do not resume, send support your device type, iOS version, approximate timestamp, and a safe screenshot with no private tokens or secrets.
I signed in but do not see approval events
Use the connection checklist first: provider doctor with backend check, setup pointing at https://api.orbiterdev.ai, and the same paired account on desktop and iOS. Notifications can be interrupted while foreground refresh still works, so check account alignment before investigating push delivery.
How do subscriptions work?
Orbiter Dev offers Pro Monthly and Pro Annual through Apple In-App Purchase. Use Settings -> Restore Purchases after reinstalling or switching devices. Billing, cancellation, and renewal are handled by Apple.
How do I contact support?
Use the support form at /support or email support@orbiterdev.ai. Include device type, iOS version, IDE or agent host, safe screenshots, and the approximate time of the issue. Do not send API keys, auth tokens, private code, or payment details.
What IDEs and agents are supported?
Orbiter provides documented setup paths for Codex, Claude Code, Antigravity, Gemini CLI, Cursor, Windsurf, and generic MCP-compatible hosts. Gemini CLI is a beta integration; start with low-risk approvals and run doctor after setup changes.
What's the free tier limit?
Free includes 50 approvals per week, 1 workspace, and 7-day history. Pro Monthly and Pro Annual are available through Apple In-App Purchase in the iOS app.