Skip to main content

​
Overview

Omnara has two execution targets:
TargetWhere it runsUses
LocalYour linked machineLocal files, tools, MCPs, provider auth, secrets, and localhost services
SandboxOmnara-managed Cloudflare containerSynced workspace state, sandbox env vars, Omnara-managed provider config, and GitHub credentials
Omnara’s web, mobile, desktop, and watch apps can control a Local session, but they do not move execution. The agent still runs on the linked machine. Use Sandbox when that machine is offline, asleep, or unavailable and you want to keep working from your phone or another device.

​
Set Up

There are two setup paths.

​
New Cloud-Only Workspace

Use this when you want to start directly in Sandbox from GitHub:
  1. Click Add Workspace.
  2. Select a GitHub repository.
  3. Connect your GitHub account.
  4. Install the Omnara GitHub App on the account or organization that owns the repository.
  5. Return to Omnara and select the repository.
  6. Start a session.

​
Existing Workspace

Use this when the workspace already exists locally:
  1. Open the new session screen.
  2. Select Cloud Sandbox for the workspace.
  3. If prompted, connect GitHub and enable workspace sync.
  4. Start a session.
If GitHub is already connected and workspace sync is already enabled, you can start a sandbox session even when your local machine is offline. If either step still needs setup, your local machine must be online so Omnara can connect the workspace and upload the state needed by Sandbox.

​
Use Sandbox

You can use Sandbox in two ways:
  1. Start a new session with Cloud Sandbox selected.
  2. Move an existing local worktree to Sandbox from the execution target control.
If your local machine is already offline, Sandbox can only resume from state that synced before the machine became unavailable. You can move a sandbox worktree back to Local when a linked machine is online.

​
How It Works

When Sandbox starts, Omnara:
  1. Creates or reuses a managed machine record for the worktree.
  2. Restores the session conversation and workspace checkpoint, or clones from GitHub for base-ref starts.
  3. Starts a Cloudflare sandbox container for the worktree.
  4. Injects sandbox environment variables, GitHub credentials, provider config, and Omnara daemon credentials.
  5. Runs the sandbox daemon inside the restored workspace.
  6. Runs the configured setup script.
  7. Marks the workspace ready so sessions can start or resume.
Sandbox model calls use Omnara-managed cloud credits. They do not spend through your local Claude Code or Codex subscription.

​
Secrets and MCPs

Sandbox is a separate machine. It does not automatically have your local home directory, shell environment, keychain, provider config, MCP packages, or localhost services. Put required sandbox secrets in Workspace Settings -> Sandbox -> Remote environment. Use the setup script to install dependencies, install MCP servers, generate config files, and validate required env vars. 
## Sandbox readiness checklist

- Workspace sync enabled
- GitHub connected
- Required sandbox env vars configured
- Setup script installs dependencies and MCP servers
- No reliance on local-only files like ~/.claude/settings.local.json
- No reliance on laptop localhost services

​
Common Questions

​
Is remote control the same as Sandbox?

No. Remote control means using Omnara from another device. If the target is Local, the agent still runs on your machine.

​
Why is Sandbox unavailable?

Check that the workspace is a GitHub repo, GitHub is connected, workspace sync is enabled, and you have Cloud Sandbox Credits.

​
Does Sandbox use my git credentials?

Sandbox git operations use GitHub access connected through Omnara for that workspace.

​
Can I connect to another individual user’s GitHub repository?

Not directly. For repositories owned by an individual GitHub account, Omnara currently requires the connected GitHub user to own the repository. This keeps repository permissions scoped to the individual account that installed and authorized access. If you need to use a repository owned by another individual user, you can:
  • fork the repository into your own GitHub account and connect the fork
  • move the repository to a GitHub organization and install the Omnara GitHub App on that organization

​
Why did my MCP work locally but fail in Sandbox?

The MCP likely depended on local-only config, files, packages, secrets, or localhost services. Move required values into remote environment variables and install or generate MCP config from the setup script.