Docs / Integrations

Google Workspace

The Secretary reads your calendar, your Gmail inbox, your Drive and your Google Sheets after you consent once. It writes only when you turn writing on and approve each call, and it never sends.

The Secretary

The Secretary is the secretary preset. It holds google.read and google.write and owns the google skill. It is on the team only when IVRALO_GOOGLE_SERVICES names at least one service.

The main agent never reads an account itself. Calendar, inbox, Drive and Sheets questions go to the Secretary, and what it brings back goes to whichever specialist the rest of the work belongs to.

Setup

You need a Google account and an OAuth client for ivralo in Google Cloud Console. That is Google's way of giving a program an identity; you do it once.

Open console.cloud.google.com and create a project.
Under APIs & Services, Library, enable the APIs you want: Google Sheets API, Google Drive API, Google Calendar API, Gmail API.
Under OAuth consent screen, choose External, give it a name, and add your own account under test users. The app can stay in testing mode for one person.
Under Credentials, create an OAuth client ID of type Desktop app. Google shows a client ID and a client secret.

Put them in your home's .env, with the services to connect:

GOOGLE_CLIENT_ID=123456789-example.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-change-me
IVRALO_GOOGLE_SERVICES=sheets,drive,calendar,gmail

Install the google-workspace extra (the first line, in a checkout), then consent:
```
uv sync --extra google-workspace
ivralo google login
```

A browser page opens. Sign in with the account you added and allow the access listed. The token is saved as google-token.json in the home and refreshed from then on. From the next session, the Secretary is on the team.

A session never opens a browser. Consent is given only through ivralo google login, which you run yourself. Without a usable token, the Secretary has one tool, and it tells you what to run instead of retrying.

Command	What it does
`ivralo google login`	opens the browser for consent; `--yes` skips the question before it opens
`ivralo google status`	says what is in place, and names the first thing to fix
`ivralo google logout`	forgets the token

ivralo doctor has a google section too. You can also revoke the token from your Google account's security page at any time.

What it reads

You ask	It calls
what is on the calendar on Thursday	`list_events`, `search_events`, `find_available_slots`
whether someone sent the contract	`search_emails`, `get_emails_from_user`, `get_thread`
bring the attachment into the workspace	`download_attachment`, into `inbox/` in the workspace
a file in Drive	`search_files`, `read_file`, `download_file`
the numbers in a Google Sheet	`read_sheet`

Every claim cites its source: the event's title and time, the mail's sender, date and subject, the file's name and id. A downloaded file is a workspace file like any other, so it can be indexed or computed over.

Scopes

By default ivralo asks Google only for the read-only scope of each service you named. Turning writing on adds the write scopes, so run ivralo google login again afterwards.

Service	Read scope	Added with writing on
`sheets`	`spreadsheets.readonly`	`spreadsheets`
`drive`	`drive.readonly`	`drive.file`
`calendar`	`calendar.readonly`	`calendar`
`gmail`	`gmail.readonly`	`gmail.compose`, `gmail.modify`

Writing, and never sending

IVRALO_GOOGLE_WRITE=true adds creating and updating sheets and events, uploading to Drive, drafting mail, and marking or labelling mail. Each pauses for your approval as a high-risk call, and none exists in a run nobody is watching.

Settings

Variable	Default	Sets
`GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`	unset	the OAuth client from Cloud Console
`IVRALO_GOOGLE_SERVICES`	unset	any of `sheets`, `drive`, `calendar`, `gmail`; unset means no Secretary
`IVRALO_GOOGLE_WRITE`	`false`	the write tools, each approved
`IVRALO_GOOGLE_TOKEN`	`google-token.json` in the home	where the token is kept