Use Astra to query resources and run workflows

Astra is an open-source AI agent from MatrixOrigin that runs in your terminal: you describe what you want in natural language, and it calls tools to get it done step by step. In this tutorial, Astra reaches MOI through moi-cli, MOI’s command-line tool. For example, if you type “List all MOI workspaces I can access”, Astra runs the matching moi-cli command and summarizes the result for you.

Technically, Astra is an Agent Runtime: it runs the agent loop and contains no model of its own. The model it uses is provided by MOI, so you do not need a model API key. You also do not need to learn moi-cli commands first; sign in once with your MOI account and you can start. Before Astra runs a command on your computer, it asks for your approval by default.

The first five steps cover installation, sign-in, and read-only queries. Once connected, you can submit and track a workflow run in a test workspace. Confirm its inputs, outputs, and permissions before running it.

These illustrations were made from screenshots of one real validation run and redacted. Click an image to open it at full size in a new tab. Version numbers and query results may differ from yours.

Before you begin

  • A macOS or Linux computer that can reach MOI;

  • An MOI account with access to at least one workspace;

  • A working directory for the Astra session. For a first try, use a dedicated project directory rather than trusting your entire home directory.

1. Install the client

Run this in a terminal on your computer:

curl -fsSL https://get.matrixorigin.cn/astra | sh

The confirmation is Astra and moi-cli are installed.:

Terminal showing Astra and moi-cli installation completed, with account and device details removed

If the terminal cannot find astra afterward, open a new terminal or follow the PATH instructions printed by the installer; do not rerun the installer.

2. Sign in to MOI and Astra

In the same terminal, run:

astra login

A browser page opens. If needed, sign in to your MOI account first. When the browser says You are signed in to Astra, return to the terminal and select a workspace. Logged in in the terminal is the completion signal.

See the browser success page
Privacy-redacted Astra browser sign-in success page with its address bar covered
Terminal showing workspace selection and Logged in, with authorization and workspace details redacted

The browser may show success while workspace selection is still open in the terminal. Do not share the browser callback URL or terminal authorization URL; they contain parameters for this sign-in attempt.

3. Start a conversation

From the directory where you want to work, run:

astra

If Astra asks whether to trust the current directory, decide whether you want its saved workspace rules enabled. The highlighted option below is from this run, not a recommendation to trust your directory.

See the directory trust prompt
Astra asking whether to trust the current working directory, with the real path redacted

After entering the conversation, send Hi. A reply confirms that ordinary chat is working:

Astra conversation showing a Hi message and reply, with account and local path removed

4. Query MOI without changing data

In the same Astra conversation, enter:

List all MOI workspaces I can access.

You can also ask in English: List all MOI workspaces I can access.

On the first MOI tool call, Astra may ask you to approve moi-cli ... workspace list. Verify that it is a workspace-list query, then select Yes to run it once.

See the first command approval prompt
Approval prompt for the first moi-cli workspace list command

You should then see the workspaces you can access:

Privacy-redacted Astra workspace result with workspace names, IDs, and owner details covered

The number and names depend on your account. Names, IDs, and owner details in the illustration are redacted.

5. View databases in the selected workspace

Continue in the same conversation. The prompt used in this walkthrough was:

List the databases in my currently selected MOI workspace. Do not change any data.

Astra returns the databases and table names in your selected workspace. This validation run found one user database and two internal system databases without changing data:

Result showing one user database and two internal system databases, with details redacted

If a query fails, preserve the command, error, and selected workspace. Check authentication and permissions before investigating further. A missing response does not establish that the database is empty.

Continue a workflow task

After read-only discovery succeeds, use a test workspace for a multi-step task. Ask Astra to list visible workflows matching a chosen name and show IDs and versions without running anything. Select the actual object before explicitly requesting a test run.

Ask it to preserve the execution ID, follow completion or failure and report actual output objects. Inspect proposed commands and confirmation prompts. Check the same run in MOI and open its outputs. Submitted work is not completed work; confirm input, output scope and permissions before writes, and do not automatically repeat failed runs.

Verify results and select actual objects, then explicitly request execution:

Submit one run using the workflow and test material I have confirmed. Retain the execution ID, track it to completion or failure, then list the actual results in the target knowledge base or output files. If it fails, identify the failure location before doing anything else; do not rerun automatically.

Read Astra’s proposed commands and confirmation prompts. After submission, verify state using the same execution ID, then inspect that same run and target artifacts in MOI. Astra saying “submitted” does not mean processing is complete. Workflows write target objects; confirm inputs, output locations, and permissions before testing.

Last updated on