# Connect an app

Open connection help, complete an app's setup and sign-in, and check that its tools are ready.

This guide connects one app on an existing installation. Start with [Quickstart](/docs/vision/quickstart) if Vision is not installed. You need the computer holding your Vault and access to the account or local resource you want to connect.


### Background collection

An existing host may also run automatic full collection. For live access without automatic historical sync, apply `ZORTEX_AUTO_SYNC=0` before starting it; changing a shell variable does not reconfigure a host already running. See [source controls](/docs/vision/settings/permissions).

## Connect and verify an app

1. **Open connection help**

   Run the following with your existing Vault directory:

   ```sh
   indra --root "/absolute/path/to/your/Vault" help
   ```

   The command opens **Local connection help** and keeps its local server running. If a browser does not open, use the live URL printed in the terminal. To print the URL without opening it automatically, add `--no-open`.

   `indra help` without a root only prints command usage. `zortex help` opens the connection page using the installation's saved Vault binding.

2. **Find your app and choose its next step**

   Incomplete sources appear first. Expand **Ready to use** to inspect apps already checked, or **Unavailable** to read missing prerequisites.

   | What the row shows | What to do |
   | --- | --- |
   | **Connect** or **Continue connecting** | Start or continue the connection. |
   | A setup form | Enter the displayed nonsecret settings, such as a folder, tenant, region, or public client ID; save them and follow the next message. |
   | **Continue current authorization** | Continue the existing provider transaction. |
   | **Open authorization page** | Open that live page, finish its steps, then return. |
   | **Open QR code page** | Follow the provider's pairing instructions on the required device. |
   | Connected, awaiting checks | Choose **Check again**. |
   | **Unavailable** | Read the reason before retrying; the source may need installation, configuration, or a supported operating system. |

   The exact controls depend on the source. A connector that needs an approved provider client or a running local service cannot be made ready by repeatedly clicking Connect.

3. **Complete the provider step**

   Confirm the intended account, workspace, and requested access on the provider's page. If a credential form is required, use the provider page or the protected local authorization form opened by Vision. Folder and account selections limit what the connector can reach.

   Keep the original help page and its terminal alive. A connection can remain pending after a provider page opens. Wait for Vision to verify the account and available operations; the page opening is not the success signal.

   An agent should operate the available pages and finish routine setup itself. A phone challenge, missing credential, or unresolved account choice may still require your input.

4. **Check the result**

   A ready row can report **Actions are available; no action has been run**, a successful operation, or a successful empty read. These are different results. To verify your own task, perform a small relevant read—for example, list a few calendar events or read the document you need.

   You can also inspect the report from a terminal:

   ```sh
   indra --root "/absolute/path/to/your/Vault" manage --json '{"what":"onboarding"}'
   ```

   Ready sources stay available while others are incomplete. You do not need to wait for the whole directory before using one connected app.

## Connect from the command line

For a provider such as Gmail, a person working directly in the terminal can request the visible manual authorization route:

```sh
indra --root "/absolute/path/to/your/Vault" connect --source gmail --presentation open
```

Complete the opened provider page while the command checks the same job. Omitting `--presentation open` selects automatic connection instead; it can return a browser continuation for an agent to operate.

If an automatic transaction is already waiting, finish it or cancel it through its current owner before starting a new manual transaction. Do not start a second sign-in against the same pending job.

Use `onboard` without source arguments to start or resume the installation's automatic connection pass.

## Stop or return later

**Cancel connection** stops the displayed active connection attempt. **Continue later** closes this help session while preserving completed connections. Reopen help to continue. The live help URL expires after 30 minutes or when its owning process ends; use a newly returned URL rather than a bookmark.

If the row fails, follow [Recover a connection](/docs/vision/connectors/recovery). An empty read alone does not require a new sign-in.
