---
title: "Connect agents to an AI subscription"
canonical: https://workspace.socra.com/docs/admin/agents/connect-an-ai-subscription
---

# Connect agents to an AI subscription

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](/docs/admin/concepts/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](/docs/admin/guides/review-agents-and-apps#create-an-agent-in-admin).

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

1. If you don't have the Socra CLI, install it as [Install the CLI](/docs/cortex/reference/cli#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.
2. Run `socra agent --help`. If it shows "Unknown command", run `socra install agent` to add the Agent commands.
3. 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`.
4. 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:

```sh
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

1. Open [Admin](https://admin.socra.com) and select **Agents → Connections**.
2. Select **Create connection**.
3. 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.
4. Optional: change the **Name**. You see this name when you choose a connection for an agent.
5. 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 to the subscription

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.

### Claude

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.

1. In **Open Claude**, select **Go to Claude**. Claude opens in a new tab.
2. 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.
3. If Claude already shows the **Authentication code** page, go to the next step. Otherwise, select **Authorize**.
4. Select **Copy code**.
5. Return to Admin. In **Paste the code from Claude**, paste the code into **Code from Claude**.
6. 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**.

### ChatGPT

1. In **Get a sign-in code**, select **Get code**. Admin shows **Preparing…** and then a one-time code.
2. In **Enter the code on ChatGPT**, select **Copy code**. The button changes to **Copied**.
3. Select **Go to ChatGPT**. ChatGPT opens in a new tab.
4. Sign in with the ChatGPT account that owns the subscription.
5. When ChatGPT asks for a code, enter the code from Admin.
6. Return to Admin. The page updates when sign-in finishes.

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

### Confirm the sign-in

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](#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

1. 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.
2. 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.
3. Select each agent that should use the subscription.
4. 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

1. Select **Agents → Agents** and open the agent.
2. 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**.
3. In **Choose connection**, open **Connection** and select your connection. You can select a connection only when its status is **Connected**.
4. 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](#create-the-connection).

## Check the result

1. Select **Agents → Connections** and open your connection.
2. Confirm that the status next to its name shows **Connected**.
3. Confirm that the **Agents** section lists every agent you chose. A paused agent shows as **Paused**.
4. 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:

1. If the agent has no work yet, give it a small task, as [Give it a place to work](/docs/agents/get-started#give-it-a-place-to-work) describes.
2. Wait until the agent finishes the work.
3. Open the agent and select **View activity**. The **Activity** dialog lists events oldest first, 20 on each page.
4. Select **Next page** until it no longer appears. The newest events are at the end of the list.
5. Find the event that started the work. Each event shows the time the agent received it.
6. 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.

1. If the agent is running, wait until it shows **Sleeping**, or pause it as [Choose the connection on each agent](#choose-the-connection-on-each-agent) describes.
2. Select **Agents → Connections** and open the connection.
3. In **Agents**, select **Choose agents**.
4. Clear the agent and select **Save**.
5. 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](#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](#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."

1. [Remove each agent from the connection](#remove-an-agent-from-a-connection).
2. Select **Agents → Connections** and open the connection.
3. Under **Danger zone**, select **Delete connection** or **Disconnect**.
4. 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](#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`.

```sh
socra agent connection create "CONNECTION_NAME" --provider claude
```

Start the sign-in:

```sh
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:

```sh
socra agent connection get CONNECTION_ID
```

### Claude

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.

1. Record `login.attempt` as `ATTEMPT_ID`.
2. Open the `login.verification_url` address in a browser.
3. 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.
4. If Claude already shows the **Authentication code** page, go to the next step. Otherwise, select **Authorize**.
5. Select **Copy code**.
6. 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
   ```

7. Paste the code, press Return, and then press Control-D to end the input.

### ChatGPT

1. Open the `login.verification_url` address in a browser.
2. Sign in with the ChatGPT account that owns the subscription.
3. 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 agents from the CLI

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

```sh
socra agent pause AGENT
```

Assign the connection to each agent:

```sh
socra agent connection assign CONNECTION_ID AGENT
```

If you paused the agent, resume it:

```sh
socra agent resume AGENT
```

Confirm that `ai_connection` in the output shows your `CONNECTION_ID`:

```sh
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:

```sh
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.

```sh
socra agent connection delete CONNECTION_ID
```

## Fix a problem

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

### Claude sign-in failed or the code expired

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."

1. Select **Get a new code**. Claude opens in a new tab.
2. If Claude shows **Authorize**, select it. Then select **Copy code**.
3. 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 sign-in failed or the code expired

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."

1. Select **Get a new code**. Admin shows a new code.
2. Select **Copy code**, and then select **Go to ChatGPT**.
3. 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](#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:

1. [Remove each agent from the connection](#remove-an-agent-from-a-connection).
2. Follow the Claude steps in [Sign in to the subscription](#sign-in-to-the-subscription).
3. [Choose the connection on each agent](#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](#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](#sign-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](/docs/agents/guides/choose-a-model) for the agents that use the connection.

To give the agents work, see [Delegate work](/docs/agents/guides/delegate-work).