Core Concepts

​

Workspace

A workspace is a project or repo Omnara knows about. Think of it as the home for everything related to that codebase:

• where the project lives
• how it is configured
• whether sync is enabled
• which machines or sandboxes can run it

​

Worktree

A worktree is a specific working copy of a workspace. In practice, that usually means:

• the main branch you normally work from (aka the main worktree)
• or a separate branch / working copy for a new task

You will most often notice worktrees when:

• launching work in parallel
• switching between local and sandbox execution

​

Session

A session is one coding conversation and execution timeline. A session includes things like:

• your prompts
• the agent’s replies
• tool calls and progress
• diffs and follow-up work

Some sessions can also spawn child work for parallel or delegated execution, but you usually do not need to think about that when getting started. If you leave your desk and come back later, Omnara keeps the session in sync across devices.

​

Remote Control

Omnara lets you run a session on your own machine and control it from your phone, the web, or any other machine. That means you can:

• check progress while away from your desk
• respond when the agent needs input
• review work from another device
• keep the session moving without sitting in front of the terminal

This is different from sandboxing. Remote control keeps execution on your machine. Sandboxing moves execution to a managed remote environment.

​

Provider

A provider is the coding engine Omnara uses for the session. Today, Omnara supports:

• Claude Code
• Codex

You install and authenticate the provider separately, then Omnara connects to it.

​

Local vs Sandbox

A session can run in two places:

​

Local

Local means the coding work runs on your own machine. Use local when you want:

• your own installed tools
• your own local credentials
• direct access to files and services on your machine

Most users run sessions locally and control them from their phone. You don’t need to move to the cloud to work away from your desk.

​

Sandbox

Sandbox means the coding work runs in a managed remote environment. Use sandbox when you want:

• cloud execution
• to keep working when your machine goes offline
• a managed environment tied to your workspace state

​

How These Fit Together

A simple mental model:

1. You connect a provider
2. You open a workspace
3. Omnara launches a session, usually on your own machine
4. That session may use your current branch or a new worktree
5. While it runs, you can monitor and steer it from your phone
6. You can return to the same session later on your computer

​

When Users Usually Get Confused

​

“What is the difference between a workspace and a session?”

• Workspace = the project
• Session = one run of work inside that project

​

“What is the difference between local and sandbox?”

• Local = your machine runs the code
• Sandbox = Omnara runs the code in a managed remote environment

​

Next Steps