[Feature]: Support importing an existing CODEX_HOME
- 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
Assessment
This issue has not been assessed yet.