# Get started

Connect one app, read a small result, and check that you used the right source.

This walkthrough uses Gmail for a first read. You can follow it in a terminal without an agent.


### Background collection

The read requests up to five messages; independently enabled background sync may collect more history. If you want live access without background copying, configure [background sync](/docs/vision/connectors/sync) before starting the host.

## Before you start

Install from the [installation page](/install), or continue with an existing installation. You need Node.js 24 or newer, the installed `zortex` command, and access to the app you want to connect. The [installation guide](/docs/vision/local-app) explains the commands and data directory.

```sh
zortex --version
zortex --help
```

Check that your installed help lists `connect`, `action`, and `manage`. Documentation can describe a newer capability than an older installation provides. If a command is absent, follow [Update Vision](/docs/vision/settings/updates) before using that feature.

`zortex` reuses the configured Vault or its platform default. If you use a custom Vault, add `--root` with that existing absolute directory to each command. Do not choose a new empty directory to recover missing information.

## Complete your first read

1. **Check the app's current state**

   ```sh
   zortex manage --json '{"what":"sources"}'
   ```

   Find `gmail` in the result. If it is already connected, go to step 3. If it is disabled, preserve that choice unless you intend to enable it. If it is absent or unavailable, use [Supported sources](/docs/vision/connectors/sources) to find the appropriate installed route.

   The source ID is the exact value used in commands; the provider's display name is not necessarily its ID.

2. **Connect the account**

   ```sh
   zortex connect --source gmail --presentation open
   ```

   The explicit `--presentation open` option requests a browser page you can operate yourself. Keep the command running, select the intended Google account, and follow the provider’s actual sign-in and access steps. If an earlier automatic attempt is still active, continue that attempt or use its **Cancel connection** control and wait for cancellation before beginning a new one. Do not run competing authorization flows.

   For a consolidated recovery view, open another terminal and run:

   ```sh
   zortex help
   ```

   In **Local connection help**, find the app under **Connect your apps** or **Review your connections**. Use the offered **Connect**, **Continue connecting**, or **Reconnect** control. After finishing the provider step, use **Check again** when it is offered. A connection belongs under **Ready to use** only after its supported check succeeds. More detail: [Connect a service](/docs/vision/connectors/connect).

3. **Read a small amount of current information**

   ```sh
   zortex action --json '{"name":"connector.read","params":{"source":"gmail","request":{"limit":5}}}'
   ```

   Inspect the returned records. Check that their account, subjects, dates, and contents match the source you intended. The exact record fields depend on the connector. A successful empty result is different from an authentication or access error; do not reconnect merely because no records were returned.

   This is a live, bounded read. Its success does not establish the separate background synchronization state or that a complete mailbox history is in the Vault. For locally collected information, use [Search saved information](/docs/vision/tools/search); for importing supported sources, use [Sync information](/docs/vision/connectors/sync).

4. **Keep the result useful**

   You have finished when you can identify the source, inspect the returned information, and distinguish a successful read from an error. If your next task is a summary, save the relevant source identities with your notes. If it changes an app, follow [Run an action](/docs/vision/tools/actions) and verify the resulting object.

## If you use an agent

With Vision connected to your agent host, try:

### Agent host

> Read up to five recent messages from my connected Gmail account. List the subjects and explain which need a reply. Do not send anything. Tell me which account you used and identify the messages behind your answer.

The agent uses the same connection and read operations. It should complete recoverable setup under your existing instructions, and ask only for information or a step it cannot obtain through available tools. [MCP setup](/docs/vision/reference/mcp-setup) explains how to make the tools available to the host.

## Fix a failed first read

| What happened | Next step |
| --- | --- |
| `zortex` was not found | Reopen the terminal after installation and check the installation command and PATH. |
| The app is unavailable | Inspect its installed source entry; see [Supported sources](/docs/vision/connectors/sources). |
| The result reports `unauthenticated` | Reuse the current authorization or open `zortex help`; then retry this small read. |
| You see the wrong account | Follow [Choose an account](/docs/vision/connectors/accounts) before reading more. |
| The read succeeds but SQL finds no rows | Live access and stored history are separate. Check [source coverage](/docs/vision/connectors/coverage). |
| The result is an `err` object | Read its code and message; use [Troubleshooting](/docs/vision/settings/troubleshooting). |

These examples use a POSIX shell or PowerShell with single-quoted JSON. In Windows Command Prompt, use PowerShell for these examples rather than removing the JSON quotes.
