---
title: "Set up Claude Code cloud, Claude projects and Codex cloud"
description: "A one-time setup, in numbered steps, so Claude Code cloud sessions and Claude project threads sign in and run every Overlane hook, and a Claude Code routine and a Codex cloud task each run overlane run next on your project. Nothing is pasted anywhere."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.overlane.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up Claude Code cloud, Claude projects and Codex cloud

This is a one-time setup. When it is done, a Claude Code routine and a Codex cloud task can each pick up the next task in your project with `overlane run next`, and they never claim the same task. You paste no token, key or secret into either vendor's settings. People sign in with `overlane auth login`. Unattended cloud runs sign in with the repository itself.

## Before you start

- You have an Overlane project connected to a GitHub repository. [Get started with onboarding](/getting-started/onboarding/) covers it.
- The Overlane GitHub App is installed on that repository. Installing the App and connecting the repository is the only setup the agents need.
- The project has tasks. See [Runs and the project kit](/runs-and-kit/).

## One-time setup

1. **Sign in once yourself.** On your own machine, run `overlane auth login`. The CLI prints a link and a short code. Open the link on any device, a phone is fine, check the code matches and approve. This checks that you can reach the project. It is not copied into any cloud setting.

2. **Check the project is connected.** Run `overlane context`. It prints the project binding, the run policy and the next runnable task. If the binding is empty, finish onboarding first.

3. **Commit the Claude Code setup.** In the project, run `overlane client install claude --surface cloud` and commit what it writes: `.claude/settings.json`, `.claude/skills`, `.overlane/hooks` and the Overlane section of `CLAUDE.md`. Cloud sessions do not install plugins, so this puts every Overlane hook and skill in the repository instead. Each hook loads its script from the installed CLI, so updating the CLI updates the hooks.

4. **Attach the repository to Claude Code on the web.** In Claude Code on the web, add the same GitHub repository to an environment. In that environment's setup script, install the CLI with `npm install --global overlane`. Add no secret. From then on every session in that environment signs in for the repository, connects and prints the context packet as it starts, and every Overlane hook runs: a request for work becomes a task, edits wait until a task is held, and stopping waits until the held task is submitted.

5. **Create a Claude Code routine.** In the routine, attach the repository and give it this prompt:

   ```text
   Run `overlane run next`. Do the task it prints, commit the work, then run `overlane run next` again until it stops.
   ```

   Pick a schedule, or run it once by hand first. The routine signs in with the repository on its own, because it has no terminal. It pushes its work to its own `claude/` branch, so the sign-in proof uses that branch and moves it back straight after.

6. **Attach the repository to Codex cloud.** In Codex cloud, create an environment for the same repository and install the Overlane CLI in its setup. Add no secret. Codex removes setup secrets before the agent runs, which is another reason none are used.

7. **Start a Codex cloud task.** Give it the same prompt, with the executor named so the run records which agent did the work:

   ```text
   Run `overlane run next --executor codex`. Do the task it prints, commit the work, then run `overlane run next --executor codex` again until it stops.
   ```

8. **Check both runs.** Back on your machine, run `overlane run status`. Each run shows the task it holds. Two runs at the same moment get different tasks, and a task whose dependencies are not finished is never handed out.

## Claude projects

A Claude project starts a cloud thread for each task. Those threads read the repository's `CLAUDE.md`, but they never run the hooks in its `.claude/settings.json`, so step 3 alone does not reach them. Plugins added to the project do load in every new thread, so Overlane's hooks reach the threads that way. Do this once per account, then once per project:

1. **Commit the setup.** Do step 3 above. It also marks the repository as one that uses Overlane, which is what the plugin looks for before it signs anything in.

2. **Make the plugin file.** On your own machine, run `overlane client package claude`. It writes `overlane-claude-plugin.zip`, holding the plugin and no credential.

3. **Add the plugin to your account.** At [claude.ai](https://claude.ai/customize/plugins), open **Customize > Plugins**, select **Add > Upload plugin** and choose the file.

4. **Add it to the project.** Open the project, open **Project settings** from the gear icon in the project header, go to **Plugins** and add Overlane. Changes there reach new threads, not threads already running.

5. **Optional: install the CLI in the environment.** **Project settings > Environment** shows which cloud environment the project uses. To edit it, go to [claude.ai/code](https://claude.ai/code), open the environment selector (the first control under the message box on the new-session screen), hover over that environment under **Cloud** and select its settings icon. Select **Setup script**, add `npm install --global overlane` and select **Save changes**. Never put a token in a setup script: everyone who uses the environment can read it. Without it the plugin runs the published CLI through `npx`, which takes a few seconds longer each time a thread starts.

From then on, each new thread signs in for the repository and connects as it starts, the same way as step 4 above, with nothing pasted. Until that finishes, the task gate refuses file edits. After it, edits wait until the thread holds a task. Where the repository's own hooks already run, such as an ordinary cloud session or your own machine, the plugin from your account stays silent, so no hook runs twice.

To check a project, start a thread and ask it to run `overlane context`. It should show the thread signed in and the project bound.

## What happens on each run

`overlane run next` is one step of the loop. It finishes the task the working copy holds by running that task's checks on the committed work, pushes the branch and opens the pull request, then claims the next runnable task. A task closes only when its checks passed on the exact commit. A failed check leaves the task with the agent that holds it. See [overlane run next](/cli/run-next/).

## How the sign-in works with no token

A cloud run has no terminal and starts empty. When any command needs access, the CLI asks the service for a one-time challenge, pushes one empty commit that names it, and the service reads it through the Overlane GitHub App and removes it. Only a run that can push to the repository can do this. The result is a credential for that one project that lasts one hour and cannot be refreshed. The CLI signs in again when it expires. You can also run it by hand with `overlane auth login --repo`. The full detail is in [Agent sign-in](/agent-tokens/).

The CLI never reads or sends the cloud sandbox's own git credentials.

A cloud session binds its checkout itself: the committed session start hook runs `overlane connect --yes`, which in a cloud session signs in for the repository first and opens a browser only if that fails. You can run it by hand too. Then `overlane task new`, `overlane task next` and the rest work in the same session. When the repository carries the committed setup, `connect` does not also register the plugin, so no hook runs twice.

When a task is submitted, the working copy is free: the next `overlane task start` or `overlane task new` goes ahead, and the submitted task waits for its checks.

## If a run is refused

- **The repository cannot sign in.** The App is not installed on it, or it is not connected to a project. Connect it, then run again.
- **Exit code 6.** A budget is spent, the run policy is paused or nothing is runnable. The message names the reason and the `overlane run end` command to finish with.
- **The sandbox refuses the proof push.** Pushing to the session's own branch is the fallback. Run `overlane auth login --repo` in the session to see which place was refused. Some sandboxes allow a push only to the branch the session started on; the CLI also tries that branch after you switch, and when every push is refused the message lists each place it tried.

Source: https://docs.overlane.app/getting-started/cloud-agents/index.mdx