Connect CoAgents to your ChatGPT or Claude subscription

View as Markdown

Connect a Claude subscription to your Claude Code CoAgents, or a ChatGPT subscription to your Codex CoAgents. You create a connection in Admin and sign in to the provider once. Then you choose that connection on each CoAgent.

A connection is the saved sign-in to one Claude or ChatGPT subscription. Several CoAgents can use the same connection. A Codex CoAgent can also sign in to ChatGPT on its own computer without a connection. For a shared ChatGPT connection, follow the common setup steps below and Connect your ChatGPT subscription. For a sign-in on one CoAgent’s computer, see Sign in on one Codex CoAgent's computer.

Before you start

Your Account role is Owner or Admin. Account roles and permissions describes each role.
The provider account has access to Claude Code or Codex. Check Claude Code subscription requirements or Codex plan requirements. Organization-managed accounts may also need their provider administrator to enable access.
The person who owns the subscription can sign in to Claude or ChatGPT during setup.
For ChatGPT, enable device-code sign-in in the subscription account’s ChatGPT Security Settings. The setting is Enable device code sign-in for Codex, Excel, PowerPoint, and Word. Check Account → Email to confirm you are changing the intended account.
Your CoAgents use the runtime that matches the provider: Claude Code for a Claude connection, Codex for a ChatGPT connection. To check a CoAgent, open it in Admin. Under AI subscription, the card title shows Claude Code or Codex. While the CoAgent shows Not connected, that section is titled Connect Claude or Connect ChatGPT instead.
Each CoAgent is Sleeping or Paused when you choose its connection. You can create the connection and sign in while your CoAgents run.

Creating a managed CoAgent incurs Socra charges separately from the AI subscription. Review How CoAgent billing works before creation. Your Account must be eligible to create and run CoAgents.

To create a Codex or Claude Code CoAgent, follow Create a CoAgent in Admin. To use the CLI for Claude Code, see Create a Claude Code CoAgent.

Review what a connection shares

Read these points before you sign in or choose CoAgents:

All CoAgents on a connection share the subscription's usage limits. Work from one CoAgent counts against the limits for all of them.
Your Codex use outside Socra also draws from the connected ChatGPT account's allowance. Claude and Claude Code share usage limits across their apps. The providers define which other features share limits; see OpenAI's current usage rules and Claude's current usage rules.
For a Claude connection, Socra stores a Claude subscription token. Every CoAgent on the connection receives this token in its environment and can read it. Choose only CoAgents you trust with the subscription.
For a ChatGPT connection, Socra keeps the ChatGPT refresh credentials. CoAgents on the connection don't receive them. Each CoAgent gets ChatGPT access tokens from Socra when it needs them, and those tokens expire.
Disconnecting or deleting a Claude connection removes Socra's copy of the token. Socra doesn't revoke the token at Claude when you disconnect or delete the connection, or when you remove a CoAgent from the connection. A CoAgent that read the token can still have a copy.
Owners and admins in your Account can view and manage shared connections under CoAgents → Connections, including connections created by another administrator.

Create the connection

Open Admin and select CoAgents → Connections.
Select Create connection.
Under Provider, select Claude for Claude Code CoAgents or ChatGPT for Codex CoAgents.
Optional: change the Name. You see this name when you choose a connection for a CoAgent.
Select Create connection.

Admin opens the connection's page and shows the setup steps. Next to the connection's name, the status shows Not connected.

Sign in with the account that owns the subscription. The steps depend on the provider. Each setup step on the connection's page shows a check mark when it is done. Keep sign-in codes private. Enter the ChatGPT code only on the ChatGPT sign-in page, or paste the Claude code only into the intended connection in Admin.

Connect your Claude subscription

The code from Claude expires within a few minutes and works only once. The sign-in attempt in Admin expires after 15 minutes. Keep Admin open, and paste the code as soon as you copy it.

In Open Claude, select Go to Claude. Claude opens in a new tab.
On the Claude page, read the Logged in as line. If it doesn't show the subscription owner's account, select Switch account and sign in with that account.
If Claude already shows the Authentication code page, go to the next step. Otherwise, select Authorize.
Select Copy code.
Return to Admin. In Paste the code from Claude, paste the code into Code from Claude.
Select Connect. You can also press Return. The button shows Connecting… while Admin waits for Claude.

If your browser blocks the Claude tab, Admin shows "Your browser blocked the Claude tab. Open it here to continue." Select Open Claude in that message.

To discard a sign-in and begin again, select Start over.

Connect your ChatGPT subscription

In Get a sign-in code, select Get code. Admin shows Preparing… and then a one-time code.
In Enter the code on ChatGPT, select Copy code. The button changes to Copied.
Select Go to ChatGPT. ChatGPT opens in a new tab.
Select or sign in to the ChatGPT account that owns the subscription. If ChatGPT shows Welcome back, choose the intended account. Select Use another account if it is not listed.
On Sign in to Codex with ChatGPT, check the email address and select Continue. If ChatGPT asks you to enable device-code sign-in, follow the recovery steps before continuing.
On Use your device code to grant access to Codex CLI, enter the code copied from Admin. ChatGPT says the code is displayed in your terminal; for this setup, Admin displays it.
Select Continue.
Return to Admin. The page updates when sign-in finishes.

To discard a code and begin again, select Start over.

When the provider confirms the sign-in, the status next to the connection's name changes to Connected, and Choose CoAgents becomes the current step. If sign-in fails or expires, see Fix a problem.

Choose the connection on each CoAgent

Admin changes a CoAgent's connection only while its computer is Sleeping or Paused. Admin lists a running CoAgent but you can't select it.

Pausing a CoAgent can interrupt work in progress. If you can, wait until the CoAgent shows Sleeping. To pause a running CoAgent, open it under CoAgents → CoAgents, expand Computer and advanced settings, and select Pause work under Computer. When you finish, select Resume work.

You can choose CoAgents from the connection or from each CoAgent.

Choose CoAgents from the connection

On the connection's page, in Choose CoAgents, select Choose CoAgents. Admin lists the CoAgents that match the provider: Claude Code CoAgents for a Claude connection, and Codex CoAgents for a ChatGPT connection.
If a CoAgent's checkbox is unavailable, check Computer → Status on its page. Wait until it shows Sleeping or Paused, then open Choose CoAgents again. See You can't choose a connection for a CoAgent for other states.
Select each CoAgent that should use the subscription.
Select Save.

If a CoAgent already uses another connection, Admin shows "Uses NAME now." when you can see its name, or "Uses another connection now." Saving moves the selected CoAgent to this connection.

Choose the connection from a CoAgent

Select CoAgents → CoAgents and open the CoAgent.
Under AI subscription, select the Connection row. While the CoAgent shows Not connected, the section is titled Connect Claude or Connect ChatGPT. Before a Claude Code CoAgent has a connection, the row shows None. Before a Codex CoAgent has one, the row shows Not assigned.
In Choose connection, open Connection and select your connection. You can select a connection only when its status is Connected.
Select Save.

A Claude Code CoAgent without an assigned connection shows Not connected under Connect Claude. A Codex CoAgent without an assigned connection or a working local sign-in shows Not connected under Connect ChatGPT. For a Claude Code CoAgent, the card says "Choose an existing Claude connection, or create one. Your CoAgent’s computer can stay asleep." A Codex CoAgent without a working sign-in sees the same text with ChatGPT. Select the Choose connection button, which opens the same Choose connection dialog.

If you have no connection for the CoAgent's provider, the dialog asks you to create one. For Claude Code, it says "You have no Claude connections yet. Create one, then come back here to choose it." Codex uses the same message with ChatGPT. Select Create connection, and follow Create the connection.

Check the result

Select CoAgents → Connections and open your connection.
Confirm that the status next to its name shows Connected.
Confirm that the CoAgents section lists every CoAgent you chose. A paused CoAgent shows as Paused.
Open one of the CoAgents. Under AI subscription, confirm that the Connection row shows the connection's name.

Verify a task

To check that a CoAgent can use the subscription, first select Resume work if the CoAgent is paused. Then:

If the CoAgent has no work yet, give it a small task, as Give it a place to work describes.
Open the CoAgent and select View activity. The Activity dialog lists events oldest first, 20 on each page.
Select Next page until it no longer appears. The newest events are at the end of the list.
Find the event for your task using its received time. Select Refresh to update the list while the CoAgent works.
Confirm that the event reaches Completed. If it shows Failed, select View error and read the reason. If it stays queued or the CoAgent does not respond, follow CoAgent is not responding before sending the task again.
Review the response and the result of the task in the app where you assigned it. Connected confirms the saved sign-in; a completed task with the expected result confirms that the CoAgent can use it.

Remove a CoAgent from a connection

Removing a CoAgent removes its assignment to this shared connection. The connection and its other CoAgents don't change. It does not revoke credentials at the provider. A Codex CoAgent may still have a separate ChatGPT sign-in saved on its computer. In Admin, any Account owner or admin can remove CoAgents from a shared connection. Admin changes the connection only while the CoAgent's computer is Sleeping or Paused. Pausing a running CoAgent can interrupt its work.

If the CoAgent is running, wait until it shows Sleeping, or pause it as Choose the connection on each CoAgent describes.
Select CoAgents → Connections and open the connection.
In CoAgents, select Choose CoAgents.
Clear the CoAgent and select Save.
If you paused the CoAgent and want it to continue working, select Resume work on the CoAgent's page.

You can also remove a CoAgent from its own page. Under AI subscription, select the Connection row. In Choose connection, open Connection. Select No connection. Then select Save.

The CoAgent no longer appears on the connection's page. A Claude Code CoAgent then has no assigned AI connection. A Codex CoAgent can use a previously saved local ChatGPT sign-in, or you can sign in on its computer. If your goal is to stop the CoAgent from doing any work, keep it Paused.

Removing a CoAgent doesn't revoke the Claude token at Claude. To add the CoAgent back, choose the connection again, as Choose the connection on each CoAgent describes.

Disconnect or delete a connection

Both actions affect only the connection you open. They don't cancel your Claude or ChatGPT subscription, and they don't revoke the token at Claude.

Disconnect removes the saved sign-in. The connection stays under Connections, and its status shows Not connected. To use it again, sign in again as Sign in to the subscription describes. Disconnect appears only while the connection is Connected.
Delete connection removes the connection and its saved sign-in. You can't undo it. To use the subscription again, create a new connection and sign in.

Remove every CoAgent from the connection first. While CoAgents use it, both buttons are unavailable, and Danger zone says "To disconnect or delete this connection, remove its CoAgents first with Choose CoAgents."

Remove each CoAgent from the connection.
Select CoAgents → Connections and open the connection.
Under Danger zone, select Delete connection or Disconnect.
In the confirmation dialog, select Delete connection or Disconnect again. The dialog names the connection, for example "Delete Team Claude?"

After you delete, Admin returns to Connections, and the connection no longer appears. After you disconnect, the status shows Not connected.

Use the CLI

The Socra CLI can create and manage connections from a terminal. Provider sign-in still requires the subscription owner to complete the browser steps. The commands act on the Account that socra account status shows.

Prepare the CLI

If you do not have the Socra CLI, follow Install the CLI. If you already have it, run socra update to get current CoAgent commands.
Run socra agent --help. If it shows "Unknown command", run socra install agent.
Run socra account status and confirm that it shows the Account you manage in Admin. If you are not signed in, run socra account login. If it shows another Account, run socra account switch.

Create and start a connection

Replace these placeholders in the commands:

CONNECTION_NAME: the name you give the connection.
CONNECTION_ID: the connection's ID. It starts with conn_.
ATTEMPT_ID: the ID of a Claude sign-in attempt.
AGENT: the CoAgent's username or ID.

Each command prints JSON.

Run only the command for your provider. Record the id in the output as CONNECTION_ID.

For ChatGPT:

socra agent connection create "CONNECTION_NAME" --provider chatgpt

For Claude:

socra agent connection create "CONNECTION_NAME" --provider claude

Start the sign-in:

socra agent connection login CONNECTION_ID

The login object in the output holds the sign-in details. If a value you need is null, wait a few seconds and read the connection again:

socra agent connection get CONNECTION_ID

Connect your Claude subscription from the CLI

The code from Claude expires within a few minutes and works only once. Follow these steps in order, so you submit the code as soon as you copy it.

Record login.attempt as ATTEMPT_ID.
Open the login.verification_url address in a browser.
Read the Logged in as line. If it doesn't show the subscription owner's account, select Switch account and sign in with that account.
If Claude already shows the Authentication code page, go to the next step. Otherwise, select Authorize.
Select Copy code.
Run this command. The --stdin option reads only piped input, so the command passes the code through cat.
sh
```
cat | socra agent connection code CONNECTION_ID --attempt ATTEMPT_ID --stdin
```
Paste the code, press Return, and then press Control-D to end the input.

Connect your ChatGPT subscription from the CLI

Open the login.verification_url address in a browser.
Sign in with the ChatGPT account that owns the subscription.
When ChatGPT asks for a code, enter the value of login.user_code.

Wait for the connection

Run socra agent connection get CONNECTION_ID until status shows connected. If login.status shows failed or expired, start the sign-in again with socra agent connection login CONNECTION_ID.

Assign CoAgents from the CLI

If a CoAgent isn't sleeping or paused, pause it before you assign it. Pausing can interrupt work in progress.

socra agent pause AGENT

Assign the connection to each CoAgent:

socra agent connection assign CONNECTION_ID AGENT

If you paused the CoAgent and want it to continue working, resume it:

socra agent resume AGENT

Confirm that ai_connection in the output shows your CONNECTION_ID:

socra agent get AGENT

Remove CoAgents or delete the connection from the CLI

To remove a CoAgent from the connection, run this command while the CoAgent is sleeping or paused:

socra agent connection unassign CONNECTION_ID AGENT

To delete the connection, remove every CoAgent first. Deleting removes the connection and its saved sign-in, and you can't undo it.

socra agent connection delete CONNECTION_ID

Fix a problem

Start with what Admin shows, and then follow the matching steps.

A Claude code expires within a few minutes and works only once. The sign-in attempt in Admin expires after 15 minutes. After a failure, Admin shows "This sign-in expired. Get a new code, then paste it here." or "Claude sign-in did not finish. Codes expire after a few minutes and work only once. Get a new code, then paste it here."

Select Get a new code. Claude opens in a new tab.
If Claude shows Authorize, select it. Then select Copy code.
Return to Admin, paste the code into Code from Claude, and select Connect.

Admin says "This is not a Claude code"

The full message is "This is not a Claude code. Copy the code Claude shows after you select Authorize." The text in Code from Claude isn't the code. Return to the Claude tab, select Copy code, and paste again. Admin removes spaces and line breaks that copying adds.

ChatGPT can stop before code entry with Continue unavailable. The page says "Enable device code sign-in for Codex, Excel, PowerPoint, and Word" and links to ChatGPT Security Settings. It then asks you to run codex login --device-auth again. For a shared Socra connection, restart sign-in in Admin instead, as described below.

This setting permits device-code authentication for every app named in its label.

Open ChatGPT Security Settings.
In ChatGPT settings, open Account and check Email. Confirm that this is the subscription account you chose during sign-in. The settings link can open a different saved account.
If the email is wrong, use ChatGPT's profile menu to switch accounts, then check Account → Email again.
Open Security and login.
Enable Enable device code sign-in for Codex, Excel, PowerPoint, and Word.
Return to the connection in Admin. Select Start over if the earlier attempt is still pending, then select Get code. If it has expired, select Get a new code.
Follow the ChatGPT steps under Sign in to the subscription with the new code.

If your organization manages ChatGPT permissions and the setting is unavailable, ask its ChatGPT administrator about device-code sign-in.

After an expired code, Admin shows "The code expired before sign-in finished. Get a new code and try again." After another failure, Admin shows ChatGPT's error message or "ChatGPT sign-in did not finish. Get a new code and try again."

Select Get a new code. Admin shows a new code.
Select Copy code, and then select Go to ChatGPT.
Sign in to ChatGPT and enter the new code.

If Copy code can't copy the code, Admin shows "Select the code above and copy it." Select the code and copy it.

The connection shows Reconnect required

The saved sign-in stopped working. Sign in again on the connection's page.

For a ChatGPT connection, follow the ChatGPT steps in Sign in to the subscription. The CoAgents can stay on the connection.

For a Claude connection, Open Claude says "To sign in again, remove this connection’s CoAgents first. You can add them back after you connect." In the CLI, socra agent connection login CONNECTION_ID fails with an error that includes "Unassign agents before replacing credentials." Write down which CoAgents use the connection, and then:

Remove each CoAgent from the connection.
Follow the Claude steps in Sign in to the subscription.
Choose the connection on each CoAgent again.

A Claude Code CoAgent shows Not connected

Under Connect Claude, a Claude Code CoAgent with no connection shows Not connected and "Choose an existing Claude connection, or create one. Your CoAgent’s computer can stay asleep." It uses a Claude connection only. Select Choose connection and choose a Claude connection, as Choose the connection on each CoAgent describes.

You can't choose a connection for a CoAgent

If Connection and Save in Choose connection are unavailable, Admin shows "You can change connections while the CoAgent is sleeping or paused." The CoAgent's computer isn't Sleeping or Paused. In Choose CoAgents, the CoAgent's checkbox is unavailable and its line says "CoAgents can change connections while sleeping or paused." Under Computer on the CoAgent's page, check Status:
- Running: wait until it shows Sleeping, or select Pause work.
- Provisioning, Waking or Upgrading: wait until the status changes.
- Failed: Admin shows "The computer needs attention before work can continue." Expand Computer and advanced settings and read the error shown under Computer. When the status shows Sleeping or Paused, change the connection.
If your connection is in the list but you can't select it, the connection isn't Connected. In Choose CoAgents, its CoAgents show "Connect this connection before adding CoAgents." Finish signing in to the subscription.
If your connection isn't in the list, check the provider. Admin lists Claude connections only for Claude Code CoAgents, and ChatGPT connections only for Codex CoAgents. Owners and admins can choose connections created by another administrator in the same Account.

The Connection row shows Managed by another administrator

Owners and admins can manage shared connections in their Account regardless of who created them. Refresh Admin and check that the intended Account is selected, then open CoAgents → Connections.

While the CoAgent is Sleeping or Paused, choose a Connected connection or select No connection in Choose connection, then select Save. If the shared connection is still unavailable, follow Troubleshooting with the Account, CoAgent, and connection identifiers. Keep provider credentials and sign-in codes private.

Next steps

Choose a model for the CoAgents that use the connection.

To give the CoAgents work, see Delegate work.

Create a Claude Code CoAgent

Admin can create Codex and Claude Code CoAgents. In Create your AI teammate, under AI connection, choose a connected Claude connection, or connect Claude there. A Claude connection creates a Claude Code CoAgent, and Admin assigns the connection during creation. Only an Account Owner can create a CoAgent in Admin. Follow Create a CoAgent in Admin. To prepare the connection first, create a Claude connection and sign in.

To create a Claude Code CoAgent using the CLI, you need an Account Owner or Admin role and an Account eligible for CoAgent creation. Prepare the CLI first. Replace USERNAME with a username of lowercase letters, numbers, and single hyphens:

socra agent create USERNAME --runtime claude

This creates the CoAgent, but does not connect a Claude subscription or grant resource access. Return to Create the connection to connect Claude and assign the CoAgent.

You can also switch an existing Codex CoAgent to Claude Code. Wait until it is Sleeping, or pause it before changing runtimes. If it uses a ChatGPT connection, remove that assignment first. Replace AGENT with the CoAgent's username or ID:

socra agent update AGENT --runtime claude