> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opencomputer.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Deploy a Gmail summarizer agent with the OpenComputer CLI

This quickstart creates a source-controlled Gmail summarizer, connects your
Google account, tests the agent locally, and deploys it to OpenComputer.

## Prerequisites

* Node.js 22 or newer
* An OpenComputer account
* A Google account you can authorize for Gmail

## 1. Install and log in

Install the agents-focused OpenComputer CLI:

```bash theme={null}
npm install --global @opencomputer/cli
```

Log in and confirm the account the CLI will use:

```bash theme={null}
opencomputer login
opencomputer whoami
```

`opencomputer whoami` prints your user, organization, and OpenComputer API.

## 2. Choose a template

List the available agent use cases:

```bash theme={null}
opencomputer templates
```

Create a Gmail summarizer from the `email-triage` template:

```bash theme={null}
opencomputer init email-triage gmail-summarizer
cd gmail-summarizer
npm install
```

Initialization generates an immutable UUID and a readable two-word name.
Confirm both before the first deployment:

```bash theme={null}
cat opencomputer.toml
```

You should see:

```toml theme={null}
schema = 1
id = "0195f5fb-2d5d-4aa4-b28e-b0df0af60cd8"
name = "Gentle Falcon"
template = "email-triage"
```

The generated name is what people see in the dashboard. The UUID is the
unique identifier used by deployments, sessions, channels, and APIs. Generated
names vary and can be edited without changing the agent's identity.

<Warning>
  Keep the `id` stable after the first deployment. Changing it creates a
  different agent instead of a new version.
</Warning>

## 3. Customize the agent

Open `instructions.md` and describe the job and its approval boundaries. For
example:

```md theme={null}
Summarize unread and recent Gmail threads.

- Group messages into urgent, needs action, and informational.
- Identify deadlines and messages that need a reply.
- Never send, archive, label, mark read, or otherwise modify mail without
  explicit approval.
```

The generated project already includes the Gmail tool and its Google
connection declaration.

## 4. Commit the agent

Treat the project like any other codebase:

```bash theme={null}
git init
git add .
git commit -m "Initialize Gmail summarizer agent"
```

This commits `opencomputer.toml`, so future deployments use the same identity.
Files containing local runtime state and environment secrets are ignored.

## 5. Connect Gmail

Start the Google authorization flow:

```bash theme={null}
opencomputer connection add gmail --alias personal
```

Open the authorization link, select the Google account, and approve the
requested access. The CLI waits until the connection becomes active.

<Note>
  Connections belong to your OpenComputer user identity, not to one local
  directory. Give each account an alias, such as `personal` or `work`, to connect
  more than one Gmail account without sharing either account with another user.
</Note>

## 6. Test locally

Run one task with the local agent:

```bash theme={null}
opencomputer session "Summarize up to 10 unread Gmail messages. Group them into urgent, needs action, and informational. Include sender, subject, a one-sentence summary, and any deadline. Do not modify any email."
```

The CLI starts OpenCode with the project files and a scoped connection to
Gmail. You can edit `instructions.md` or the tools and run the command again
until the behavior is right.

For an interactive development session, run:

```bash theme={null}
opencomputer dev
```

## 7. Deploy

Publish the current source as the `production` version:

```bash theme={null}
opencomputer deploy --alias production
```

The result includes the stable agent ID and an immutable deployment ID:

```text theme={null}
Deployed gmail-summarizer@production
Deployment: gmail-summarizer:<source-digest>
Source ID:  opencomputer.toml
```

Verify that the agent is registered:

```bash theme={null}
opencomputer agents
```

Run the deployed agent:

```bash theme={null}
opencomputer run gmail-summarizer \
  "Summarize my unread inbox and call out anything urgent."
```

## Ship an update

Edit any source file, commit the change, and deploy again:

```bash theme={null}
git add .
git commit -m "Refine inbox urgency rules"
opencomputer deploy --alias production
```

The agent remains `gmail-summarizer`; the `production` alias moves to the new
immutable version.

## Next

<CardGroup cols={2}>
  <Card title="Agents overview" icon="robot" href="/agents/overview">
    Learn the project structure and versioning model.
  </Card>

  <Card title="Architecture" icon="diagram-project" href="/agents/architecture">
    Follow source from local development to managed execution.
  </Card>
</CardGroup>