Connect agents to an AI subscription

View as Markdown

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

A connection is the saved sign-in to one Claude or ChatGPT subscription. Several agents can use the same connection. A Codex agent can also sign in to ChatGPT on its own computer without a connection. This page covers connections only.

Before you start

Your Account role is Owner or Admin. Account roles and permissions describes each role.
The subscription is a Claude plan that includes Claude Code, or a ChatGPT plan that includes Codex.
The person who owns the subscription can sign in to Claude or ChatGPT during setup.
Your agents use the runtime that matches the provider: Claude Code for a Claude connection, Codex for a ChatGPT connection. To check an agent, open it in Admin. Under AI, the card title shows Claude Code or Codex.
Each agent is Sleeping or Paused when you choose its connection. You can create the connection and sign in while your agents run.

Create a Claude Code agent

Admin creates Codex agents only. In Create your AI teammate, under AI provider, Claude Code shows Coming soon. Only an Account Owner can create an agent in Admin. To create a Codex agent, follow Create an Agent in Admin.

To create a Claude Code agent, use the Socra CLI:

If you don't have the Socra CLI, install it as Install the CLI describes. If you already have it, run socra update. Older versions don't have the connection commands on this page, and their socra agent update has no --runtime option.
Run socra agent --help. If it shows "Unknown command", run socra install agent to add the Agent commands.
Run socra account status and confirm that it shows the Account you manage in Admin. If you aren't signed in, run socra account login. If it shows another Account, run socra account switch.
Create the agent. Replace USERNAME with a username of lowercase letters, numbers, and single hyphens.
sh
```
socra agent create USERNAME --runtime claude
```

You can also switch an existing agent to Claude Code. The agent must be sleeping or paused. If it uses a ChatGPT connection, remove it from that connection first. Replace AGENT with the agent's username or ID:

socra agent update AGENT --runtime claude

Review what a connection shares

Read these points before you sign in or choose agents:

All agents on a connection share the subscription's usage limits. Work from one agent counts against the limits for all of them.
The subscription owner's own use of Claude or ChatGPT outside Socra counts against the same limits.
For a Claude connection, Socra stores a Claude subscription token. Every agent on the connection receives this token in its environment and can read it. Choose only agents you trust with the subscription.
For a ChatGPT connection, Socra keeps the ChatGPT refresh credentials. Agents on the connection don't receive them. Each agent 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 an agent from the connection. An agent that read the token can still have a copy.
Only the person who creates a connection can see it in Admin. Other owners and admins don't see it under Connections.

Create the connection

Open Admin and select Agents → Connections.
Select Create connection.
Under Provider, select Claude or ChatGPT. To see what each provider works with, hover over the info icon next to Provider. Claude works with Claude Code agents. ChatGPT works with Codex agents.
Optional: change the Name. You see this name when you choose a connection for an agent.
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.

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.

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

Choose the connection on each agent

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

Pausing an agent can interrupt work in progress. If you can, wait until the agent shows Sleeping. To pause a running agent, open it under Agents → Agents and select Pause work under Computer. When you finish, select Resume work. Opening a Codex agent's page can wake its computer while Admin checks its ChatGPT sign-in.

You can choose agents from the connection or from each agent.

Choose agents from the connection

On the connection's page, in Choose agents, select Choose agents. Admin lists the agents that match the provider: Claude Code agents for a Claude connection, and Codex agents for a ChatGPT connection.
Check the line under each agent's name. "Agents can change connections while sleeping or paused." means the agent is running. Wait until it shows Sleeping, or pause it, and then open Choose agents again.
Select each agent that should use the subscription.
Select Save.

If an agent already uses another of your connections, Admin shows "Uses NAME now." under the agent, with the connection's name. Saving moves the agent to this connection.

Choose the connection from an agent

Select Agents → Agents and open the agent.
Under AI, select the Connection row. Before a Claude Code agent has a connection, the row shows None. Before a Codex agent has one, the row shows This computer.
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 agent with no connection shows Not connected under AI, with the text "Choose the Claude subscription this agent uses." and a Choose connection button. The button opens the same Choose connection dialog.

If you have no connection for the agent's provider, Choose connection shows "You have no Claude connections yet. Create one, then come back here to choose it." Select Create connection, and follow Create the connection.

Check the result

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

To check that an agent can use the subscription:

If the agent has no work yet, give it a small task, as Give it a place to work describes.
Wait until the agent finishes the work.
Open the agent 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 that started the work. Each event shows the time the agent received it.
Confirm that the event shows Completed. If it shows Failed, select View error and read the reason.

Remove an agent from a connection

Removing an agent stops it from using the subscription. The connection and its other agents don't change. In Admin, only the person who created the connection can remove agents from it. Admin changes the connection only while the agent's computer is Sleeping or Paused. Pausing a running agent can interrupt its work.

If the agent is running, wait until it shows Sleeping, or pause it as Choose the connection on each agent describes.
Select Agents → Connections and open the connection.
In Agents, select Choose agents.
Clear the agent and select Save.
If you paused the agent, select Resume work on the agent's page.

You can also remove an agent from its own page. Under AI, select the Connection row. In Choose connection, open Connection. For a Claude Code agent, select No connection. For a Codex agent, select Sign in on this agent’s computer. Then select Save.

The agent no longer appears on the connection's page. A Claude Code agent then has no AI connection. A Codex agent can sign in to ChatGPT on its own computer.

Removing an agent doesn't revoke the Claude token at Claude. To add the agent back, choose the connection again, as Choose the connection on each agent 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 agent from the connection first. While agents use it, both buttons are unavailable, and Danger zone says "To disconnect or delete this connection, remove its agents first with Choose agents."

Remove each agent from the connection.
Select Agents → 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 do the same steps from a terminal, for example when you automate setup. Before you start, set up the CLI and sign in, as Create a Claude Code agent describes. The commands act on the Account that socra account status shows.

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 agent's username or ID.

Each command prints JSON.

Create the connection. For a ChatGPT connection, use --provider chatgpt. Record the id in the output as CONNECTION_ID.

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

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.

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 agents from the CLI

If an agent 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 agent:

socra agent connection assign CONNECTION_ID AGENT

If you paused the agent, resume it:

socra agent resume AGENT

Confirm that ai_connection in the output shows your CONNECTION_ID:

socra agent get AGENT

Remove agents or delete the connection from the CLI

To remove an agent from the connection, run this command while the agent is sleeping or paused:

socra agent connection unassign CONNECTION_ID AGENT

To delete the connection, remove every agent 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.

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 agents can stay on the connection.

For a Claude connection, Open Claude says "To sign in again, remove this connection’s agents 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 agents use the connection, and then:

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

A Claude Code agent shows Not connected

Under AI, a Claude Code agent with no connection shows Not connected and "Choose the Claude subscription this agent uses." It uses a Claude connection only. Select Choose connection and choose a Claude connection, as Choose the connection on each agent describes.

You can't choose a connection for an agent

If Connection and Save in Choose connection are unavailable, Admin shows "You can change connections while the agent is sleeping or paused." The agent's computer isn't Sleeping or Paused. In Choose agents, the agent's checkbox is unavailable and its line says "Agents can change connections while sleeping or paused." Under Computer on the agent'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." 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 agents, its agents show "Connect this connection before adding agents." 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 agents, and ChatGPT connections only for Codex agents. Admin also doesn't list connections that another person created.

The Connection row shows Managed by another administrator

The agent uses a connection that another person created. In Choose connection, Connection shows Managed by another administrator, and you can't remove the agent from it. Admin doesn't show who created the connection. Ask the other owners and admins in your Account which of them created it. That person sees the connection under Agents → Connections and can remove the agent from it. Then choose your own connection on the agent.

Next steps

Choose a model for the agents that use the connection.

To give the agents work, see Delegate work.