# Getting Started

Suger Insulin is an AI-powered workspace built into the Suger console for ISVs selling through cloud marketplaces.

---

Insulin gives you conversational AI, reusable agents, Custom Apps, knowledge bases, connected third-party tools, and automated jobs. Whether you need help drafting offers, analyzing revenue data, managing co-sell opportunities, coordinating across Gmail, Salesforce, HubSpot, Slack, or Teams, or building a lightweight internal app, Insulin brings AI assistance directly into your marketplace workflow.

## Key Capabilities

- **Chat** — Have multi-turn conversations with AI, complete with streaming responses, extended thinking, automatic model failover, and tool execution. See [Chat](./2.chat.md).
- **Agents** — Install catalog agents or create your own. Each agent can have its own instructions, model, integration allowlist, skills, and knowledge bases. See [Agents](./3.agents.md).
- **Channels** — Create group chats with team members for collaborative AI-assisted conversations. See [Channels](./5.channels.md).
- **Jobs** — Set up manual, scheduled, or event-triggered automations that run agents with optional filter expressions. See [Jobs](./6.jobs.md).
- **Marketplace** — Browse and install pre-built agents and skills from the catalog. See [Marketplace](./7.marketplace.md).
- **Custom Apps** — Build interactive apps with AI, connect them to approved integrations, preview them, and share them with your team. See [Custom Apps](./8.custom-apps.md).
- **Knowledge Bases** — Add files, websites, connectors, and pasted content so agents can retrieve trusted context. See [Knowledge Bases](./4.knowledge-base.md).
- **Inbox** — Triage email with AI: classify and tag incoming messages, draft replies in your voice, and review them in an approvals queue before anything sends. See [Inbox](./9.inbox.md).
- **AWS Support** — Open, track, and reply to your organization's AWS Support cases without leaving the workspace. See [AWS Support](/insulin/aws-support/).
- **Workspace Tools** — Use Files, Preview, Browser, and Git apps when an agent or app needs a working environment. **Preview** renders files opened from Files or an agent — PDFs, images, video, Markdown, HTML, CSV, spreadsheets, Word documents, Google Docs, and code. Most of these offer a **download** control; the code viewer and the Google Doc viewer do not (a Google-native document has no file to download — Preview embeds Google's own viewer instead).

## Who It's For

Insulin is designed for ISVs and their teams who use Suger to manage cloud marketplace listings across AWS, Azure, GCP, and Snowflake. It helps sales, operations, engineering, and product teams work faster by bringing AI assistance into daily marketplace workflows.

## Adoption Path

Most teams adopt Insulin in this order:

1. **Connect systems** — Open the **Settings** app and connect the tools agents and apps should use. Organization integrations live under **Settings → Integrations** (Organization group): any member can view the list, but only an org **ADMIN** can connect or disconnect them, and they power organization-level resources. Personal connections (such as Gmail, Google Calendar, Google Drive, and Gong) are per-user and are available only to your own user-level agents and apps.
2. **Start with chat** — Open a conversation with the built-in Insulin assistant or a catalog agent. Ask it to explain what it can access before asking it to act.
3. **Install or create agents** — Use [Marketplace](./7.marketplace.md) to install a specialized agent, or create a custom agent with a focused system prompt, allowed integrations, and optional knowledge bases.
4. **Build Custom Apps** — Use [Custom Apps](./8.custom-apps.md) when a workflow needs a reusable interface, dashboard, or form instead of a one-off chat answer.
5. **Collaborate and automate** — Use [Channels](./5.channels.md) for shared conversations and [Jobs](./6.jobs.md) for repeatable or event-triggered work.

## Accessing Insulin

1. Sign in to the [Suger console](https://console.suger.io)
2. Click **Insulin** in the left sidebar
3. You are taken to the standalone Insulin workspace

No additional setup, API keys, or integrations are required.

### Switching between the classic console and Insulin

The Suger console has two shells: the **classic console** and the **Insulin desktop**. A switch in the top bar toggles between them — it reads **New** (tooltip *"Switch to new insulin desktop"*) while you are in the classic console, and **Classic** (tooltip *"Switch to classic console"*) while you are in Insulin.

Your choice is remembered. After you switch to Insulin, signing in again takes you straight back to the Insulin desktop; switching back to Classic returns you to the classic console next time. New workspaces start on the classic console by default.

## The Interface

Insulin is a desktop-OS workspace, not a single chat page. Every feature is its own app that opens in a resizable, movable window on a full-screen desktop.

- **System Bar (top)** — Runs across the top of the workspace. It includes the **app launcher** (a "Search apps…" field): click it, or press **Cmd/Ctrl + Space**, to search and open any app.
- **Desktop (center)** — A full-screen wallpaper with **desktop icons**. Double-click an icon to open that app.
- **Dock (bottom)** — A row of pinned apps you can open with one click.
- **Windows** — Each app opens in its own window that you can move, resize, minimize, or maximize. Multiple windows can be open at once.

The Dock comes pinned with these apps:

**Chat**, **Settings**, **Marketplace**, **Files**, **Preview**, **Browser**, **Custom Apps**, **Knowledge Base**, **Git**, and **Inbox**.

Two more built-in apps are **not pinned to the Dock by default** — **Jobs** and **[AWS Support](/insulin/aws-support/)**. Open either from the app launcher, or drag it onto the desktop as an icon.

:::info
If your organization's Insulin license is invalid or expired, a banner appears across the top of the workspace above everything else. Contact Suger at sales@suger.io to restore access.
:::

### The desktop right-click menu

Right-click empty space on the desktop for a menu of things you can make and change:

| Item | What it does |
|------|--------------|
| **New Chat** | Opens the Chat app. |
| **New Folder** | Drops a new folder icon on the desktop, named *New Folder* until you rename it. |
| **New Link...** | Adds an icon that opens a URL you supply. |
| **Wallpaper → Choose File...** | Sets the desktop background from an image on your computer. |
| **Wallpaper → From URL...** | Sets the desktop background from an image address. |
| **Wallpaper → Reset to Default** | Appears once you've set a custom wallpaper; puts the original back. |
| **Theme** | Switches the desktop theme. The active one is marked. |
| **Settings** | Opens the Settings app. |
| **Developer Mode** | Toggles developer mode, the same as **Cmd/Ctrl + .** — it overlays the icon grid so you can line icons up. Marked when it's on. |

Right-click an **icon** instead and you get **Rename** and **Delete** for that item.

**Folders** work the way you'd expect: drag an icon onto a folder to file it away, open the folder and drag an icon back out onto the desktop to take it out again. Drag two loose icons together and Insulin makes a folder from them. Folders don't nest — a folder can't go inside another folder.

### Keyboard Shortcuts

| Shortcut | Action |
|----------|--------|
| **Cmd/Ctrl + Space** | Open or close the app launcher |
| **Cmd/Ctrl + W** | Close the focused window |
| **Alt + Tab** | Cycle focus to the next window |
| **Alt + Shift + Tab** | Cycle focus to the previous window |
| **F11** | Toggle fullscreen |
| **Cmd/Ctrl + .** | Toggle developer mode |

![The Insulin desktop — the System Bar and its "Search apps…" launcher run across the top, desktop icons sit on the wallpaper, and pinned apps (Chat, Settings, Marketplace, Files, Preview, Browser, Custom Apps, Knowledge Base, Git, Inbox) line the Dock at the bottom](images/01-insulin-desktop.png)

![The app launcher — press Cmd/Ctrl + Space (or click "Search apps…" in the System Bar) to search and open any app](images/12-insulin-app-launcher.png)

## Settings

Open the **Settings** app from the Dock. Tabs are split into two groups:

- **Personal** — **Sandboxes**, **Memory** (what agents remember about you and your work), and **Preference** (theme, accent color, font size, and desktop background). These apply only to you, and the same Personal tabs are also available from the classic console's Settings. (Older links to the *Appearance* or *Home Page* tabs open **Preference** automatically.)
- **Organization** — **Integrations**, **AI Model Policy**, **Sandboxes**, **Users & Roles**, **Notification**, **API Client**, and more. Most Organization tabs are visible to every member but only an org **ADMIN** can change them; a few, such as **Sandboxes**, are hidden from non-admins entirely.

![The Settings app on the Organization → Integrations tab, where organization connections are managed (org ADMIN only)](images/13-insulin-settings-integrations.png)

### AI Model Policy

**Settings → Organization → AI Model Policy** decides which AI providers are allowed to serve your organization, and in what order. It answers two questions your organization probably has an opinion about: *which vendors may see our prompts*, and *may Suger's own keys be used at all*.

**Allowed AI integrations** is an ordered allow-list. AI features may use **only** the integrations listed here — and because the list is ordered by preference, **the entry at the top is the organization default** for any feature that has no model picker of its own.

1. Pick a provider from the **Add integration** dropdown to put it on the list
2. Use **Move up** and **Move down** on a row to change the order — the top row is the default
3. Use **Remove** to take a provider off the list entirely
4. Click **Save**

The first row carries a **Default** badge so the top of the list is never ambiguous. A row for a provider your organization has not connected and verified is marked **not connected**. Leave the list **empty** for no restriction at all — the tab says so directly: *"No restriction — every connected provider is allowed."*

**Allow Suger platform key** is a switch, and it is **on** by default. Left on, Suger's shared keys can serve an allowed provider that your organization has not connected its own key for. Turn it **off** to make the organization **bring-your-own-key only**: every AI call must then use one of your own connected keys, and an allowed provider with no connected key **fails closed** rather than quietly falling back to Suger. That is the point of the switch — it is a guarantee, not a preference, so plan for the allow-list and your connected keys to line up before you turn it off.

**Embeddings (Semantic Search & Memory)** is a status line, not a setting. Semantic search, knowledge-base search, and AI memory need an OpenAI or Gemini embedding model, and they follow the policy above. The line tells you exactly what they will use:

| Status line | What it means |
|-------------|---------------|
| *<Provider> · your connected key* | Embeddings run on your own connected key. |
| *OpenAI · Suger's shared key* | Your policy allows Suger's shared key, and that is what embeddings use. |
| *Disabled — allow OpenAI or Gemini and connect a key* | Your policy leaves embeddings with nothing to run on. Semantic search and memory are switched off until you allow OpenAI or Gemini and connect a key. |

![Settings → Organization → AI Model Policy: the ordered Allowed AI integrations list with a Default badge on the top row, the Allow Suger platform key switch, and the Embeddings status line](images/14-ai-model-policy.png)

### Sandboxes (Organization)

**Settings → Organization → Sandboxes** manages the shared sandbox pool your organization's own agents run jobs in. This tab is **org-admin only** — it does not appear for other members, and a non-admin who reaches it is told so and pointed at **Personal → Sandboxes** for their own boxes instead.

Organization sandboxes are provisioned automatically the first time an organization-owned agent runs a job, so there is nothing to create here. Each row shows:

| Column | What it shows |
|--------|---------------|
| **Name** | The sandbox's name in the pool. |
| **Status** | **Running**, **Stopped**, **Failed**, or **Not provisioned** for a slot that hasn't been built yet. |
| **Provider** | The sandbox provider backing it. |
| **Created** | When the sandbox was created. |
| **Auto-stop** | When an idle sandbox shuts itself down. |

Three actions sit on each row, as icon buttons — hover one for its label:

- **Start** — Bring a stopped sandbox up. On a slot that is *not provisioned*, Start builds it for the first time.
- **Stop** — Shut a running sandbox down.
- **Destroy** — Remove the sandbox. Offered only while it is stopped; a sandbox that is currently serving a run refuses to be destroyed.

![Settings → Organization → Sandboxes: the pool table with Name, Status, Provider, Created and Auto-stop columns, and the row actions on the right](images/15-org-sandboxes.png)

### When a connection expires

A green check on an integration card means a connection exists — but a sign-in can lapse long before you notice. For your personal **Claude Code** and **Codex** connections, Suger therefore verifies the stored credential itself rather than trusting the card.

If the credential no longer works — the sign-in expired, or you revoked it at the provider — the card shows an **orange alert** in place of the green check, reading *Connection expired — reconnect to keep using it*, and a **Reconnect** button appears on the card. Reconnect runs the same connect flow you used originally; you do not need to disconnect first, and the alert clears once the new connection is in place.

:::info
This check applies only to the sign-in-based AI connections, **Claude Code** and **Codex**. Connections you authenticate with an API key — such as Anthropic and OpenAI — cannot be verified without using the key, so they never show this state. If Suger cannot reach the credential store at all, the check is skipped and cards stay as they are rather than telling everyone to reconnect.
:::

## Your First Conversation

When you open Insulin for the first time, you start with the default **Insulin** agent — a general-purpose assistant that acts as your chief of staff for marketplace operations.

1. Type a message in the input bar, such as: *"What can you help me with?"*
2. Press **Enter** or click the send button
3. The agent responds with streaming text

You can also attach files, images, or code references as context, or use the microphone control to dictate your message by voice.

That's it. You're now having a conversation with Insulin.

## Selecting a Model

Insulin selects the model for you — there's no model picker in the input bar. Your agents run on the models available to them and **fail over automatically** across your connected providers, so one provider's outage or usage limit doesn't interrupt a conversation.

The built-in **Insulin** assistant runs on **your own connected providers** (bring-your-own-key) — connect at least one under **Settings → Integrations** to use it. See [Chat](./2.chat.md#model-selection) for how an agent's ownership decides which models it can draw on, and [Agents](./3.agents.md) for choosing a custom agent's default model.

## Extended Thinking

Toggle **Extended Thinking** in the input bar to enable the agent's step-by-step reasoning before it responds. When enabled, you can see the agent's thought process displayed above its final answer. This is useful for complex questions where you want to understand how the agent arrived at its response.

## Switching Agents

To use a different agent in your conversation:

1. Click the agent name at the top of the chat area, or start a new conversation
2. Select an agent from the list — you can browse installed catalog agents, custom agents, or agents shared with you
3. The conversation continues with the selected agent's personality and capabilities

See [Agents](./3.agents.md) for the agent catalog model and how to create your own.

## Roles and Permissions

Insulin uses role-based access control (RBAC) for agents, channels, Custom Apps, knowledge bases, jobs, sandboxes, skills, and marketplace actions. Understanding these roles helps you collaborate effectively with your team. This section is the canonical reference for Insulin roles — other pages link back here and note only their own differences.

### Ownership Levels

Every agent and channel has an **ownership level** that determines its visibility:

| Level | Description |
|-------|-------------|
| **User** | Private to the creator. Only visible to others when explicitly shared. |
| **Org** | Owned by your organization. Private by default, but can be shared to other members of the organization explicitly. |
| **System** | Built-in by Suger. Available to all users. Cannot be deleted or modified. |

### Organization Roles

Every user in your Suger organization has an org-level role that determines what they can do across Insulin:

| Org Role | Permissions |
|----------|-------------|
| **ADMIN** | Full access. Can create organization-level resources, manage settings, and manage organization-level integrations. Only an ADMIN can act at the organization ownership level. |
| **EDITOR** | Can create and manage their **own** agents, channels, jobs, skills, and Custom Apps. Can read and upload to sandboxes they created. Read-only access to settings. Cannot create organization-level resources. |
| **VIEWER** | Read-only on **shared** resources — can view agents, channels, and Custom Apps but not create, edit, or delete them, and cannot start a chat. Can still fully manage the [self-owned resources](#your-own-things-are-not-role-gated) they created. |

### Your own things are not role-gated

Five kinds of thing are **self-owned**, and they sit outside the role tiers above:

**desktop · memory · jobs · skills · sandboxes**

Any member of the organization may create and manage the rows they own on these — **including a VIEWER**, and including someone on a custom organization role your admins defined. The test is ownership, not org role. Your desktop layout, what agents remember about you, the jobs you set up, the skills you wrote, and your own sandboxes are yours to manage whatever tier you sit in.

What still applies:

- **You can only manage rows you created.** Someone else's desktop icons, memories, jobs, skills, or sandboxes are not yours to touch. An org **ADMIN** can reach the others on your behalf — but **not jobs**: a job is visible and runnable only to the person who created it, admin or not.
- **Organization-level versions are a different matter.** Creating or editing a skill in the Organization store, or managing the organization's shared sandbox pool, still requires org admin.
- **Everything else stays on the tiers above.** Agents, channels, and Custom Apps are governed by the org roles and the resource roles below — a VIEWER reads them and nothing more.

### Resource Roles and Exceptions

When an agent or channel is shared, each participant is assigned a resource-level role. Roles are hierarchical — higher roles inherit all permissions of lower roles.

| Role | View | Chat | Edit | Share | Delete |
|------|------|------|------|-------|--------|
| **OWNER** | Yes | Yes | Yes | Yes | Yes |
| **ADMIN** | Yes | Yes | Yes | Yes | No |
| **EDITOR** | Yes | Yes | Yes | No | No |
| **USER** | Yes | Yes | No | No | No |
| **VIEWER** | Yes | No | No | No | No |

- **OWNER** — The creator of the agent or channel. Only the owner can delete the resource — not even a shared ADMIN can. Ownership can be transferred.
- **ADMIN** — Can manage sharing (invite/revoke members and assign roles) and edit configuration, but cannot delete the resource.
- **EDITOR** — Can modify the agent's system prompt, model, knowledge bases, and integration allowlist, or a channel's settings.
- **USER** — Can chat with the agent or participate in the channel, but cannot change any configuration.
- **VIEWER** — Read-only access. Can view resources but cannot send messages or trigger actions.

### Working with a Shared Resource

When you open a resource that's shared with you — an agent, channel, knowledge base, or Custom App — its settings view shows an **owner-and-role banner** at the top: the owner's name (and email) on the left, and a badge on the right that reads **Owner** when the resource is yours or **Shared · _Role_** otherwise. The **USER** role appears in this badge as **Member**.

If your role is below **Editor** — that is, **Member** (USER) or **Viewer** — the settings render **read-only**: you see the full configuration, but every control is disabled so you can't change it. Editor, Admin, and Owner see the same view with editable controls. Deleting a resource stays **Owner-only** no matter what else you can edit.

### Sharing Constraints

Not every role can be assigned in every situation:

| What you're sharing | Roles you can assign to individuals | Roles you can assign org-wide |
|---------------------|-------------------------------------|-------------------------------|
| **Agents** | ADMIN, EDITOR, USER (no VIEWER) | EDITOR, USER |
| **Channels and Custom Apps** | ADMIN, EDITOR, USER, VIEWER | EDITOR, USER, VIEWER |

- Agents cannot be shared as **VIEWER** — the lowest agent role is USER.
- Org-wide shares can never grant **ADMIN** to the whole organization, for any resource type.

Important exceptions:

- User-level agents, channels, and Custom Apps are private to their creator unless shared flows explicitly allow otherwise.
- Organization admins do not automatically get elevated access to every organization channel; channel access is controlled by channel membership and org-wide sharing.
- Organization-level agent and Custom App integration changes require organization administrator privileges.
- Organization-level agents can only use organization-level integrations. User-level agents use user-level integrations.

:::tip
When you create a custom agent, you are its OWNER by default. Share it with your team by assigning roles to individual users or to your entire organization.
:::

## Next Steps

- Learn about [Chat](./2.chat.md) features like tool calls, plan approvals, and attachments
- Explore the [Agents](./3.agents.md) available to you
- Connect integrations and build a reusable workflow with [Custom Apps](./8.custom-apps.md)