stablyai / stablyai/orca

[Feature]: Support importing an existing CODEX_HOME

Open
#10,366 1 comment 0 reactions 1 assignee Claimed by @brennanb2025 View on GitHub
enhancement
Dominant language
TypeScript
Stars
71.3k
Forks
4.7k
Avg merge
17h 8m
Merged PRs (30d)
475

Description

### Problem or use case

# Support importing an existing CODEX_HOME

## Summary

Currently, Orca supports multiple Codex accounts, but every additional account must be created through Orca's own login flow.

This makes it impossible to reuse an already authenticated `CODEX_HOME`, even though many advanced users intentionally manage multiple isolated Codex homes outside Orca.

I would like Orca to support **importing an existing CODEX_HOME**.

---

## Motivation

Many users intentionally keep different Codex accounts isolated.

For example:

```
~/.codex # personal
~/.codex-work
~/.codex-openai
~/.codex-huanyi
```

Each account is authenticated independently, for example:

```bash
CODEX_HOME=~/.codex-huanyi \
codex login --device-auth
```

or

```bash
CODEX_HOME=~/.codex-work \
codex login
```

This keeps authentication, configuration, and credentials completely isolated.

Currently there is no supported way to bring these existing accounts into Orca.

---

## Current behavior

Adding a new account always creates a brand new managed home and launches

```bash
codex login
```

Internally Orca creates something similar to

```
/codex-accounts//home
```

and performs authentication there.

There doesn't appear to be any way to register an already existing CODEX_HOME.

---

## Proposed feature

Add an additional option:

```
Add Account

• Browser Login
• Import Existing CODEX_HOME
```

The import flow could simply ask for a directory.

For example:

```
~/.codex-work
```

or

```
~/.codex-huanyi
```

Then Orca would

- validate the directory
- verify it is a valid CODEX_HOME
- read auth.json
- resolve the account identity
- register it as an Orca account

without requiring another login.

---

## Optional implementation

If Orca prefers to keep using managed homes internally, importing could simply:

1. Copy the imported CODEX_HOME into an Orca-managed home
2. Preserve the authentication
3. Register the account normally

This preserves Orca's current architecture while making existing Codex installations reusable.

---

## Why this is useful

This is larger than supporting one particular login method.

Importing an existing CODEX_HOME naturally enables

- Device Authentication (`codex login --device-auth`)
- Remote SSH workflows
- Enterprise authentication
- Account migration
- Backup / restore
- Work vs personal accounts
- Testing accounts
- Scripted provisioning
- Future authentication mechanisms

without Orca needing to know how those credentials were originally obtained.

---

## Example workflow

Today

```
User

Orca

Browser Login
```

Proposed

```
User

CODEX_HOME=~/.codex-work
codex login --device-auth

Orca

Import Existing CODEX_HOME

Done
```

No reauthentication is necessary.

---

## Why this fits Orca's design

Orca already manages multiple Codex accounts and switches between isolated CODEX_HOMEs.

This proposal simply adds another way to create those accounts:

- Create new account (current behavior)
- Import existing account (new)

Both result in the same managed account abstraction inside Orca.

I think this would make Orca significantly more flexible for power users while keeping the current UX unchanged for everyone else.

### Proposed solution

## Proposed solution

Introduce a second account onboarding path in addition to the current browser-based flow.

```
Add Account

• Browser Login
• Import Existing CODEX_HOME
```

The import workflow could be:

1. Select an existing `CODEX_HOME`.
2. Validate that it is a valid Codex home.
3. Read `auth.json` (or equivalent authentication state).
4. Resolve the authenticated account identity.
5. Register the account inside Orca.

From that point onward, the imported account should behave exactly like a normal Orca-managed account.

---

### Possible implementation strategies

Either implementation would satisfy this feature.

#### Option A — Register external CODEX_HOME

Orca keeps using the existing directory directly.

```
~/.codex-work


Registered in Orca
```

Advantages:

- no file copying
- authentication remains external
- compatible with existing workflows

---

#### Option B — Import into Orca-managed storage

Orca copies the existing CODEX_HOME into its managed account directory.

```
~/.codex-work


Import


/codex-accounts//home
```

Advantages:

- preserves Orca's current account architecture
- no special handling after import
- imported accounts behave exactly like newly created accounts

---

### Device authentication becomes a natural workflow

Supporting account import also enables users who authenticate outside Orca.

For example:

```bash
CODEX_HOME=~/.codex-work \
codex login --device-auth
```

After authentication, users simply choose:

```
Import Existing CODEX_HOME
```

No additional login is required.

This approach is more general than adding support for one specific login method, since it also works with future authentication mechanisms.

### Alternatives or additional context

_No response_

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.