Host Server

The o3-code start command runs a headless HTTP server that any O3 Code desktop app or CLI can communicate with.

It manages workspaces, ports, and agent runs on the machine it's running on. The desktop app starts it automatically; on a CLI-only or headless machine you start it yourself.

If you installed the desktop app, it already includes the CLI and installs a ~/.o3/code/bin/o3-code shim on app launch. O3 Code terminals prepend that directory to PATH automatically. On a headless machine, use the standalone installer from Getting Started.

Prerequisites

git and gh need to be on your PATH. git handles clone, worktree, and branch ops; gh handles PR checkout and metadata.

gh auth login

The host server reuses your existing gh auth. For sandboxes or CI, set GH_TOKEN (or GITHUB_TOKEN) instead of running gh auth login — gh picks it up automatically.

Agent CLIs (optional)

If you plan to run AI agents inside workspaces, install whichever agent CLIs you want available. The host server launches them based on which are on your PATH:

None are required to start the host server or create workspaces — install only what you plan to run.

Authenticate the O3 Code CLI

The host server starts under your O3 Code session. If you haven't already:

o3-code auth login

See Getting Started for the full sign-in flow, including API-key auth for CI.

Start the host server

o3-code start --daemon

Spawns the daemon in the background and writes a manifest at ~/.o3/code/host/<organizationId>/manifest.json so other clients can find it. Binds to 127.0.0.1 only.

Verify it's healthy:

o3-code status

Getting started

Create or adopt a project

A workspace branches off a project — a repo registered with O3 Code.

Each repo gets one cloud project record, shared across the organization. The first machine to register the repo runs projects create; every machine after that uses projects setup to attach to the existing project instead of creating a duplicate.

Start by checking what's already in your org:

o3-code projects list

First machine — projects create

If the project doesn't exist yet, clone a remote repo or import an existing local one:

# Clone from a Git URL
o3-code projects create \
  --name "My Project" \
  --local \
  --clone https://github.com/org/repo.git \
  --parent-dir ~/code

# Or import a repo that's already on disk
o3-code projects create \
  --name "My Project" \
  --local \
  --import ~/code/existing-repo

The host server clones (or registers) the repo, creates the cloud project record, and ensures the main workspace.

Subsequent machines — projects setup <id>

If a teammate (or a previous machine of yours) already created the project, adopt it instead of running create again — create would make a duplicate cloud project pointing at the same repo. Pick the ID from projects list, then:

# Clone the project's repo onto this machine
o3-code projects setup 47c31b04-… --local --parent-dir ~/code

# Or attach to an existing local checkout
o3-code projects setup 47c31b04-… --local --import ~/code/repo

The URL for clone mode comes from the cloud project record, so setup doesn't need --clone <url>. setup is idempotent: re-running against a project that's already set up here is a no-op.

Create your first workspace

o3-code projects list
o3-code workspaces create \
  --project prj_… \
  --name "fix-login-bug" \
  --branch fix/login-bug

The host server clones the project (if it isn't already on disk), creates a git worktree at the chosen branch, and registers the workspace.

You can also create a workspace from a pull request number:

o3-code workspaces create \
  --project prj_… \
  --name "review-pr-123" \
  --pr 123 \
  --local

Stop the host server

o3-code stop

Shared state

State lives under ~/.o3/code/host/<organizationId>/:

~/.o3/code/host/<organizationId>/manifest.json    # endpoint + auth token
~/.o3/code/host/<organizationId>/host.db          # local host server DB

A host server started by the desktop app is visible to the CLI and vice-versa. O3_CODE_STATE_ROOT relocates the whole tree.

Command details

For full flags, exit codes, and output shapes:

• o3-code start
• o3-code status
• o3-code stop