Skip to content

[Feature]: Support importing an existing CODEX_HOME #10366

Open

Description

@a-green-hand-jack

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:

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

or

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

codex login

Internally Orca creates something similar to

<userData>/codex-accounts/<uuid>/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
        │
        ▼
<userData>/codex-accounts/<uuid>/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:

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

Activity

  1. innocarpe commented on Jul 24, 2026

    @innocarpe
    Contributor

    Opened #10394 — Import existing CODEX_HOME (copy into managed home, no re-login).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

enhancementNew feature or request

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions