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 before starting the host.
Before you start
Install from the installation page, 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 explains the commands and data directory.
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 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
-
Check the app's current state
Shell zortex manage --json '{"what":"sources"}'Find
gmailin 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 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.
-
Connect the account
Shell zortex connect --source gmail --presentation openThe explicit
--presentation openoption 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:
Shell zortex helpIn 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.
-
Read a small amount of current information
Shell 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; for importing supported sources, use Sync information.
-
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 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.
What to expect
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 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. |
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 before reading more. |
| The read succeeds but SQL finds no rows | Live access and stored history are separate. Check source coverage. |
The result is an err object |
Read its code and message; use 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.