An Extract scan clones your application’s repository into your sandbox, runs the repository’s setup steps there, and starts a coding agent to read the code. Command Center tasks use the same sandbox. Each of those steps can fail for a reason you can fix up front, so the Extract page checks them before a scan starts.
The panel at the top of the Extract page lists four checks. A scan can start once the first three are ready. Each check that isn’t ready has a Setup guide link back to this page and a button that opens the place where you fix it.
| Check | What it needs | Blocks a scan? |
|---|---|---|
| Repository | A connected repository with an owner and a name | Yes |
| Source control | Credentials the sandbox can use to clone the repository | Yes |
| Repository setup | Install and build steps that have run in a sandbox and passed | Yes |
| Environment | A value for every environment name the repository needs | No, a warning |
When an application has more than one repository, the checks apply to the one Extract scans, and the panel names it.
Fixed something in another tab? Come back to the Extract page, or click Re-check, and the panel reads the checks again.
1. Connect a repository
Connect the repository from the application’s settings, under Integrations. See Repositories for how repositories and their mappings work.
If the panel says the connected repository is missing its owner or name, reconnect it.
2. Connect source control
The sandbox clones the repository with your organization’s source-control credentials.
GitHub
- Open Settings → Integrations → GitHub and connect GitHub. See GitHub Integration.
- Install the Catalio GitHub App on the account or organization that owns the repository, so the sandbox can clone it.
Scans aren’t available yet for repositories on other providers. The panel says so instead of offering a fix.
3. Set up and validate the repository
Repository setup is the list of steps that get the repository running in a sandbox: installing dependencies, building, and checking that it starts. Catalio needs those steps to have run in your sandbox and passed before it scans.
You don’t write the steps by hand. An agent drafts them, runs them in your sandbox, and asks you to approve what worked. There are three ways to start it.
From the Extract page
Click Set up in Command Center on the Repository setup row. Catalio starts setup for the repository Extract scans and opens its Command Center thread, where you follow the agent’s progress and approve the steps.
The button only appears if you may change the repository’s setup steps. If setup is already running for the repository, the page says so; follow the existing thread in Command Center.
From the repository’s settings
Open the repository’s card in the application’s Integrations settings and run setup from there. The card also shows the saved steps and their status.
From a coding agent in your terminal
If your coding agent, for example Claude Code, is connected to Catalio MCP, it can start setup for you. Click Copy terminal prompt on the Repository setup row and paste the prompt into your agent. The prompt names your application and repository and asks the agent to call the start_repository_onboarding tool.
The tool returns a link to the Command Center thread. Open it to follow the setup and approve the steps, the same as starting it from the Extract page.
If your MCP client lists only discover, describe and call, the agent finds start_repository_onboarding with discover. To connect an agent to Catalio MCP, see MCP Authentication.
If the copy fails, select the prompt and copy it by hand:
Use Catalio's MCP tools to set up the repository "<owner>/<name>" for the application "<application>" so Extract can scan it: call start_repository_onboarding with application_id "<application id>" and repository "<owner>/<name>" (find it with discover if your client lists only discover, describe and call). Then give me the Command Center link it returns, where I follow the setup and approve its steps.The tool runs as you, in your organization, and has the same permission check as the button.
When setup fails
If the steps fail, the panel says Repository setup failed. Open the repository’s setup, fix the steps, and validate again.
4. Add environment values
Some repositories need environment values to build or run, such as a database URL or an API key. When the repository needs a name that has no value yet, the Environment row shows a warning with the missing names. A scan can still start; some repositories scan fine without them.
Add the values from the repository’s card in the application’s Integrations settings. Values can come from:
- Catalio. Values are stored in Catalio. A value can be shared with your organization, or kept as your own, which overrides the organization’s value when you run a scan.
- A secrets manager. Doppler, 1Password, Infisical, AWS or Vault. The sandbox runs the repository’s commands through the secrets manager’s run command, and Catalio records which names it provided the last time it ran.
5. Sign in the coding agent
A scan runs a coding agent in your sandbox, and the agent needs you to sign in once. If a scan stops because sign-in is required, the Extract page shows a callout. Open Command Center, sign in when prompted, then run the scan again. The sign-in stays on your sandbox for later scans and Command Center tasks.
Agents that run in the cloud use an API key instead. The callout links to the settings page where you add it.
