Skip to main content
When your Gumloop agents generate files during a conversation, those files are saved as artifacts. You can preview, download, share, and version reports, spreadsheets, images, code files, and HTML dashboards from the chat.

How artifacts work

When an agent generates a file in its sandbox (using code execution, data processing, or any tool that produces a file), it exports the file using a built-in export tool. The export:
1

Saves the file

The file is written to secure cloud storage.
2

Creates a version

Gumloop records a versioned artifact for it.
3

Generates previews

Preview thumbnails and representations are built.
4

Shows it in chat

The file appears as a rich card in the conversation.
No export setup is required. Files appear in the conversation when the agent exports them.

Viewing artifacts

When an agent exports a file, it appears as a card in the chat message showing its display name or filename, file type icon, and a thumbnail preview (for supported types). Click the card to open a side panel preview without leaving the chat.
On mobile, tapping a file card opens the viewer page in a new tab instead of a side panel, and auto-preview of new files is disabled so it doesn’t interrupt the chat.

Supported preview types

Gumloop can render inline previews for many file types:
Audio and video stream for playback, including files larger than 50 MB. Other files larger than 50 MB are download-only instead of being previewed inline. Playback depends on your browser’s support for the file’s media format and codec; download the file if it cannot play in the viewer.

Actions

From the viewer page or the in-chat card, you can perform several actions on an artifact:

Can I ask an agent to manage an artifact?

Yes. Give the agent an artifact from the conversation or its link, then ask it to check or change the file’s name, hosted link, or sharing. Changes normally require your approval; checking the file does not. File permissions and organization restrictions still apply. Change thumbnails and password links in the artifact’s Settings.
No. Don’t ask again for this tool applies to artifact changes made by that agent, not just one file. Permissions still apply. There is currently no settings control to turn asking back on for Manage Artifact.
The new name or link may already be saved even if sharing fails. Ask the agent to check the file’s current settings before retrying.

How do I change a file’s display name?

Owners and Editors can give an artifact a display name without renaming the underlying file. The name appears on artifact cards, in the viewer, and in search. Changing it does not change the downloaded filename, file contents, artifact link, or version history.
1

Open the artifact's Settings

Open the artifact, then select Settings.
Artifact Settings showing the Quarterly report display name, thumbnail, Copy link, and Upload thumbnail

The display name and thumbnail controls are at the top of Settings.

2

Edit the display name

Double-click the name, enter up to 256 characters, and press Enter or click outside the field to save. Press Escape to cancel. Clear the name to use the filename again.

How do I change a file’s thumbnail?

Owners and Editors can upload a custom thumbnail for an artifact. One thumbnail applies to every version of that file until you replace it or return to the default preview. It changes the cover image, not the file’s contents, and does not create a new version.
1

Choose an image

In the artifact’s Settings, select Upload thumbnail and choose a PNG, JPEG, or WebP image. The upload limit is 5 MB.
2

Crop and save

Adjust the crop, then select Save thumbnail.
Close-up of the thumbnail crop area with Cancel and Save thumbnail controls

Crop an uploaded image before saving it as the file's thumbnail.

3

Return to the default preview when needed

Click the thumbnail in Settings, then select Use default preview to remove the custom image.

Automatic versioning

When an agent exports a file with the same filename multiple times in the same conversation, Gumloop automatically creates new versions instead of overwriting. This gives you a full history of how a file evolved during the conversation.
Version history panel showing Version 2 and Version 1 with timestamps and file sizes
Each version shows:
  • Version number (v1, v2, v3, etc.)
  • Timestamp of when it was created
  • File size
Owners and Editors can open version history and select a version to view. The latest version is shown by default.
Agents are instructed to keep the same filename and let the system handle versioning. If you see files like report_v2.pdf instead of version 2 of report.pdf, you can update your agent’s instructions to tell it not to rename files for versioning.

Sharing & access control

You can control who can view, download, and manage each file.

Share dialog

Select Share from the artifact viewer or its options menu to open the Share artifact dialog. From top to bottom it has:
  • An Add people or teams field with a role picker inside it (Editor or Viewer) and an Add button.
  • Who can edit: the Owner and any Editors, who can manage the file.
  • Who can view: people and teams with Viewer access, then two separate rows. Organization is No access or Viewer. Public link access opens its own view, where Who can access public link is No public link, Anyone with the link, or Anyone with the password.
  • Copy share link, Add a password, and Add custom domain at the bottom. Once a password or custom domain is set, these read Edit password and Edit custom domain.
Share artifact dialog with an Add people or teams field and an Editor role picker, Who can edit showing the Owner, Who can view with Organization set to No access and Public link access set to No public link, and Copy share link, Add a password, and Add custom domain
Public link access view with Who can access public link set to No public link and a menu listing Anyone with the link and Anyone with the password
Settings shows the same editing and viewing lists, plus the Password protected link controls.

Who can inspect or change sharing?

Viewers see a limited sharing list and can remove their own direct invitation, not someone else’s access or an Owner. Removing your invitation does not remove access you have another way, such as through your team. This also works for Viewers invited from another organization. A file invitation does not give them access to the source agent or conversation. Organization and public link access grant viewing access only, even if an older organization or public grant previously allowed editing. They do not remove a person’s separate Owner or Editor access. To let someone edit a file, add them or their team as an Editor. The organization and public link rows are independent, so you can turn on one without the other.

Password protected artifacts

A Password protected link lets people outside the file’s existing audience view it with a password. Team or organization access can stay enabled at the same time: authorized members do not need the password, while other link visitors do.
1

Turn on the password link

Open Settings, then select Turn on beside Password protected link. You can also select Add a password in the Share artifact dialog.
Password protected link section with Turn on and a note that people with viewing or editing access do not need the password
2

Save a password

Enter a password of 6 to 256 characters and select Save. The password link stays off until a password is saved. Choosing Anyone with the password without one fails with “Set a password before you turn on the password link for this item.”
3

Share the link and password

Use Copy link in Settings or Copy share link in the Share dialog. Send the password separately using your usual secure channel.
To give your whole team password-free access, add that team to the file’s Who can view list. Team membership or access to the source agent alone is not the same as sharing the file with the team. When a password is required, the file shows a Password field and an Unlock button. Unlocking grants viewing access only, not permission to edit the file.
If Public link access is Anyone with the link, saving a password narrows that access first: a team artifact switches to its team, and a personal artifact switches to invited people only. Choosing Anyone with the link later removes the password link. Turning the password link off removes password-based access and restores normal access inherited from the task or agent. It does not make the file public.
24 hours. After that, a viewer who still needs the password is asked to enter it again.
Changing the password invalidates existing unlocks. Select Turn off beside Password protected link to remove password-based access while keeping the file’s other access settings.
Repeated incorrect guesses are throttled. Correct unlocks are unaffected.
Yes. People who can manage the artifact’s sharing can reveal the saved password in Settings.
Yes. A hosted URL points to the same artifact, so its viewing permissions and password requirement apply there too.
Your organization’s role settings can block external password-protected artifact sharing. If Turn on is blocked, ask an organization admin to review your role’s External password-protected artifact sharing permission.

Default file sharing

Each agent has an Artifact Sharing setting that controls how new artifacts are shared when created. You can configure this in Access → Artifact Sharing → Default behavior:
The default sharing setting applies to new artifacts only. Owners and Editors can change an artifact’s sharing after it is created, subject to organization restrictions.

Does a public agent make its files public?

A public agent does not give signed-out visitors access to personal workspace files or files linked to a conversation. Only top-level team workspace files, with no conversation link, can inherit anonymous access from the agent’s public setting. A file’s own Anyone with the link or Password protected link setting is a separate way to share that file with outside visitors.

Requesting access

If someone shares a file link with you but you don’t have access:
  • Not signed in: Sign in or create a Gumloop account first.
  • Signed in, no access: Use Request Access, when available, or ask the person who shared the link to invite you.
On a hosted link, click Sign in and you can request access from the same link.

Who has viewed an artifact?

On Enterprise, editors and owners see an Analytics tab at the top of the artifact, next to Preview and Settings. It shows Views, Viewers, and Avg. time on page for the version and date range you pick (for example All versions and Last 30 days), with breakdowns by viewer, country or city, and device or browser. Visits by the person who created the artifact aren’t counted. Recent views lists each view, and you can filter it by viewer. Open a view to see the viewer and the tool calls the page ran, with status and latency. You can open a call’s inputs and outputs if you could see that call on the Connector activity page.
Artifact Analytics tab with All versions and Last 30 days filters, Views 1, Viewers 1, Avg. time on page 51s, a views chart, and Viewers, Countries, and Devices breakdowns

Hosting artifacts on a custom domain

Each artifact has a canonical /artifacts/{id} URL. You can also give it a subdomain on gumloopartifacts.com:
Use a custom domain to share a memorable link to a dashboard, report, or other artifact.
A custom domain is an alternate URL for the same artifact, not a separate copy or a published snapshot. Viewing permissions and version history still apply. Connector behavior differs between gumloopartifacts.com and organization-owned domains; see Your credentials, your data.

Per-artifact domains

Enabling hosting

Hosting is configured per artifact. Open Settings, then select Turn on beside Custom domain. You can also select Add custom domain in the Share dialog. Once enabled, the custom URL appears in Settings and you can edit its alias. You need Owner or Editor access on the file to manage hosting. Hosting does not grant anyone additional viewing or editing access. When you enable hosting, Gumloop derives an alias from the artifact’s filename: the extension is dropped, anything that isn’t a letter or number becomes a hyphen, and the result is lowercased. If that alias is already taken, a suffix is added automatically so enabling never fails on a collision.
Very short names are padded to meet the three-character minimum, and long names are truncated.

Customizing the URL alias

You can rename the alias at any time while hosting is enabled. Aliases follow the same rules as hosted pages:
  • 3–64 characters
  • Lowercase letters, numbers, and hyphens only
  • Must start and end with a letter or number
  • Must be unique across Gumloop
Certain aliases like admin, api, app, auth, beta, docs, gumstack, help, localhost, mcp, sandbox, staging, support, ws, and www are reserved and cannot be used.
Renaming frees the old alias immediately. Anyone holding the previous link gets a dead URL, and the old alias becomes available for someone else to claim.

Embedding the artifact on another site

Once Custom domain is on, Settings shows an Embed box under the custom URL. Select its copy button and paste the snippet into any web page, such as an internal wiki, a help center, or a company site:
The snippet lets the embedded page use the microphone, camera, clipboard, and full screen. Change the height to fit your page. Embedding doesn’t change who can open the artifact. If Public link access is No public link, the box notes “Embedded viewers sign in through a new tab,” and viewers sign in to Gumloop before the artifact loads.
Custom domain section in artifact Settings with the custom URL sheet-dashboard.gumloopartifacts.com, the note This link is published, an Embed box showing an iframe snippet with a copy button, and the note Embedded viewers sign in through a new tab

Authentication and sign-in

Visitors sign in through Gumloop and return to the artifact, with two exceptions:
  • An artifact whose Public link access is Anyone with the link opens without sign-in, unless it has live-data scripts.
  • An artifact with live-data scripts always asks for sign-in, with any Gumloop account, because the scripts run as the viewer. If it’s password-protected, visitors need the password too.

Versions and access

  • No version pin. The custom domain always serves what /artifacts/{id} serves, so a new version of the artifact appears on both URLs at once.
  • No extra sharing. Hosting does not widen access. An artifact with No public link stays private on its custom domain. A public URL does not make the file public.
  • Canonical links still work. The /artifacts/{id} URL remains available. Settings offers the custom URL for copying once hosting is enabled; links to older versions remain version-specific.

Disabling hosting

Disabling hosting immediately stops the subdomain from resolving. The alias stays reserved for that artifact, so you can turn hosting back on later with the same URL. Deleting the artifact also stops the subdomain from resolving.
Enabling, renaming, and disabling artifact hosting are all recorded in audit logs.

Organization domains

Organization admins can claim one organization-level domain for artifact hosting from Organization Settings.
1

Claim your domain

In Organization Settings, open the Custom artifact domain section, select Add domain, and enter a domain such as yourdomain.com. New artifacts are shared on this domain once its DNS records are verified. The Add domain button stays disabled until the domain is valid.
2

Add DNS records

Add these records at your domain provider. DNS changes can take up to 48 hours.
3

Wait for verification

Verification runs against those records; use Re-check DNS to check again, or DNS records to see the values you need.
New artifacts are automatically shared on your own domain instead of gumloopartifacts.com.
You can paste the bare domain; casing, http:// or https:// prefixes, paths, and a leading *. are cleaned up for you. Gumloop-owned and other reserved suffixes are rejected, as is a domain another organization has already claimed. Each organization can have one domain at a time, so remove the current domain before adding a different one.

Domain status

Select Remove to deregister the domain. The removal confirmation warns that artifact links on the domain stop working.

Hosting on the organization domain

Once the domain is Active:
  • Newly exported artifacts from the organization’s agents are automatically given an alias at https://<alias>.<your-domain>, replacing the corresponding <alias>.gumloopartifacts.com URL.
  • The alias is derived and collision-suffixed using the same behavior documented for gumloopartifacts.com aliases.
  • Auto-hosting is best effort, so a hosting failure never fails the artifact export.
  • Auto-hosting is skipped when hosting was explicitly disabled for the artifact or when the artifact already has a hosted alias. An explicitly disabled artifact is not silently re-enabled.
When your organization has an active domain, enabling Custom domain in the artifact’s Settings hosts the file on that organization domain. The file’s sharing permissions still apply. An artifact with No public link stays private on the organization domain. Paste an artifact link into chat and ask the agent to import it. It can use the original https://gumloop.com/artifacts/... link, a gumloopartifacts.com link, or a link on your organization’s artifact domain. When a specific version is named, it is used ahead of any version in the link. A link the agent can’t resolve or doesn’t have access to comes back as simply not found or not accessible, without revealing whether the artifact exists.

HTML artifacts

HTML files get special treatment. Agents can generate fully interactive HTML pages, dashboards, and web applications that render directly in the viewer.

How do HTML artifacts follow light and dark mode?

HTML projects that use the agent’s default theme follow your Gumloop appearance in the viewer and your operating system’s appearance when opened standalone. Ask the agent to customize both light and dark colors. For direct edits, the palettes are in theme.css. Older files are not automatically restyled; ask the agent to update the file if needed.

Can an HTML artifact embed its own pages?

Yes. An HTML artifact can embed another page from the same artifact bundle in an iframe. Ask the agent to create a multi-page HTML project with an embedded page, such as a report inside a dashboard. Embedded pages can use the artifact’s live-data scripts and follow its light or dark appearance. This does not allow embedding arbitrary external sites or pages from other artifacts.

Full screen mode

HTML artifacts support a full screen mode that hides the toolbar and gives the artifact the full browser window. This is useful for dashboards, interactive tools, and presentations. Click the full screen button in the viewer toolbar to enter full screen.

Security

HTML artifacts run in a strict security sandbox. This is important because agents can generate arbitrary HTML and JavaScript. The preview runs on an isolated origin, separate from your Gumloop session. It can read its own artifact files, but can’t read the Gumloop app’s cookies or local storage. A page can connect only to its own origin and to outside servers the agent declared when it saved that version. Gumloop serves each published page at the root of its own domain. Pages can use in-page routing with history.pushState, and unknown paths fall back to index.html. They can also use the microphone, camera, and clipboard after a click, embedding in other sites, and live-data scripts. They can open WebSockets and EventSource streams, and send fetch or XHR requests, to the servers the agent declared. The browser blocks connections to any other server. alert, confirm, and prompt dialogs work in the preview. Attached data-script calls use their declared tools, connection settings, and applicable tool policies.

How are Chat Widgets different from artifacts?

Chat Widgets are compact charts, comparisons, or mockups inside a live web reply, using saved content or live data. Artifacts are exported files you can download, share, and version.
Gumball reply with an inline order board for a fictional studio, showing Cutting, Finishing, and Ready columns with two orders each

A Chat Widget appears inside the agent's reply. This order board uses fictional sample data.

Enable Chat Widgets in the agent’s Agent tab under Abilities. It is on for newly created agents; existing agents need it enabled. Widgets appear only in live web chats, not Slack, Teams, email, or triggered tasks. An existing HTML artifact can also appear inline. That view keeps the artifact’s access and version settings; it does not create a new file or make the artifact public.

Can a Chat Widget load live data?

Yes. With Chat Widgets and Computer enabled, ask your agent for an inline chart or dashboard that loads data from your connectors. Live widgets are not available in incognito chats. Live widgets follow the same integration consent, connector account settings, and tool permissions as live artifacts. Opening a live widget reruns its data scripts and uses the viewer’s credits. Refreshes also use credits; data updates only when the widget loads or refreshes, not continuously in the background.

Interactive artifacts (live data)

Interactive artifacts are HTML files with attached scripts that load live integration data. Live scripts require Computer and are not supported in incognito tasks. The connections those scripts can use depend on the source agent, the file’s sharing settings, and where you open it. See Your credentials, your data.

How they work

When you ask an agent to build something that needs live data, it creates two things:
  1. An HTML file with the layout, styling, and JavaScript for the UI
  2. One or more Python data scripts that fetch data from your integrations at view time
You don’t need to know how the two are wired together. Just ask your agent for a dashboard, report, or tool that uses your connected apps, and it handles the rest. When you open an interactive artifact for the first time, you’ll see a consent overlay that lists every integration the file can access and the specific actions it can perform.
Integration consent overlay showing the file is requesting permission to use Slack with 1 tool, with an I acknowledge, continue button
You must approve before any scripts run. This is a deliberate security step. It means:
  • You always know exactly which integrations a file uses
  • No data is fetched until you explicitly approve
  • If someone shares a file with you, you decide whether to grant it access to your accounts
If the page connects to outside servers, the overlay also lists them under It can also send data to these sites.
Your acknowledgement is saved for that artifact version. Review the listed integrations and actions before continuing.

Your credentials, your data

An interactive artifact’s connections depend on where you open it and how the source agent’s connectors are configured. Sharing a file or giving it a password does not give visitors access to the creator’s personal connections. For example, a dashboard using viewer-owned Slack connections can show each signed-in viewer data from their own Slack account. A connector configured as agent-owned uses the account pinned to the agent instead.
If the artifact has Anyone with the link access or a Password protected link, its scripts cannot use agent-owned connections. This also applies when a password link is kept alongside team or organization access. On an organization-owned artifact domain, that leaves no connector access for the scripts.
Your connector credentials are not exposed to the HTML itself. If a required connector is unavailable, complete the setup prompt before loading that data.

What can you build?

Anything that combines a UI with live integration data. Here are some example prompts:
The more specific you are about which integrations and data you want, the better the result. Tell the agent exactly which tools you want it to pull from.

How teams use interactive artifacts

A shared dashboard can show each viewer data from their own connections. For example, a “My Open Tasks” dashboard with viewer-owned connections shows each person their own tasks. Agent-owned connections instead use the account configured on the source agent, where that access is allowed.

Download buttons

Ask the agent to add a download button to an interactive artifact, for example to export the dashboard’s data as Excel, a filtered CSV, or a PDF. The button creates the file when you click it, and your browser downloads it. The script builds the file when you click the button and returns it as a browser download, rather than saving it as a new artifact.
A download runs a script, so it takes a few seconds and costs credits like any other data load. If the script produces nothing, the artifact shows an error instead of saving a file.

Credits

Creating the artifact uses the agent conversation’s usual credits. After export, live data scripts and AI model calls use credits billed to the viewer rather than the creator. Organization members use their organization’s credit balance and any applicable user limits. If a credit limit blocks execution, the script returns an error. See Credits.

Can a page call AI models?

Yes. A page’s data scripts can send the data they load to an AI model and show the answer on the page. The page can summarize, tag, score, or answer questions about live data every time someone opens it, without anyone starting a chat. Example: a support triage board. Ask an agent:
“Build a dashboard of this week’s open Zendesk tickets. Tag each ticket’s sentiment as positive, neutral, or negative, and its product area. Put a three-sentence summary of the main themes at the top, and add a box where I can ask questions about these tickets.”
When a teammate opens the page:
  1. A data script loads the open tickets with that teammate’s Zendesk connection.
  2. A model tags each ticket and writes the summary. Each tag and the summary appear next to the data.
  3. Typing a question into the box, such as “Which customers mentioned billing twice?”, sends the question and the loaded tickets to a model and shows the answer on the page.
Everyone who opens the page gets fresh results from their own data, with no chat or prompt to write. More ideas: Pages can use two kinds of models. Chat models write free text, such as summaries, answers, and drafts. Decision models answer closed questions like yes or no, pick one option, or a score, and suit tagging many rows quickly. Who can use it: the person who publishes the page needs a custom role with AI models from agent code turned on. The feature is off by default. Every run also checks the viewer’s own role and model access, and bills the model usage to the viewer. There is no per-run approval. If an older page can’t call models, republish it.

Refreshing data

Opening an artifact again can rerun its data scripts. A refresh button or auto-refresh timer can also start another execution. Each script execution uses credits. Long-running queries can time out; ask the agent to reduce the data scope if needed.

Error handling

If a data script fails, the HTML receives an error response. Common causes are a disconnected integration, an API error, or a script timeout. Well-built artifacts show a friendly error message. If the agent didn’t include error handling, the section may simply be blank. Common causes and fixes:

Files page

Open Artifacts in the sidebar to find files across your agent conversations. Your personal library is available at Artifacts.
Artifacts library with Mine and Shared with me tabs, search, and a Quarterly report card
Search by display name or filename, filter by file type, and sort by date. A team artifact list also supports filtering by Creator. Each card shows the display name or filename, thumbnail, file type, and version.

Workspace files (persistent across conversations)

By default, files created during an agent conversation are scoped to that conversation. However, agents can also work with workspace files that persist across conversations. Files saved to the /home/user/.workspace/ directory in the agent’s sandbox are treated as workspace-scoped artifacts. These files persist across conversations with the same agent.

How workspace scope works

Workspace files use two separate folders:
  • Shared agent workspace, /home/user/.workspace/agent/: Access follows your role on the agent. Owners can edit shared files; Users can read them. Team membership is not an additional requirement for this shared disk.
  • Personal workspace, /home/user/.workspace/personal/: Private to you and persistent across your conversations with the same agent. It remains writable when the shared workspace is read-only.
This is useful for agents that maintain ongoing project files, configuration, or reference data that should carry over between sessions.
Sharing an agent or task does not automatically share your personal workspace.

Common questions

Files and versions

Artifacts are stored in secure cloud storage. You can open them in the Gumloop viewer or download them. Workspace files remain available across conversations with the same agent.
Yes. Anyone with Owner or Editor access to the file can delete it. Deleting is a soft delete: the file is removed from your files list, search, sharing, and normal viewer/API access, while its stored versions are preserved.

Sharing and access

Yes. Invite them by email, choose Anyone with the link, or enable a Password protected link for other link visitors. Your organization can restrict external sharing. Organization, public link, and password access grant viewing access only.

Interactive artifacts

A static artifact shows saved content, such as a PDF, image, or CSV. An interactive artifact can use attached scripts to load live data. An artifact you already acknowledged may open without a consent overlay.
Inside Gumloop and on gumloopartifacts.com, scripts can use your available connections and eligible agent-owned connections. Organization-owned artifact domains use agent-owned connections only. Public or password-shared artifacts cannot use agent-owned connections. See Your credentials, your data for the full comparison.
Both. Agents can build forms and buttons that send Slack messages or create Linear issues. These actions use the connections described in Your credentials, your data and run a data script, just like read operations.
HTML artifacts cannot read the Gumloop app’s session, cookies, or local storage. They run on an isolated origin and can read their own artifact files. External data access uses controlled script or proxy paths, not the app’s browsing session.
Check that the required connectors are available. Refresh an expired connector from Connectors, check your credit limit, or ask the agent to reduce the data scope for a query that times out.

Custom domains

Your artifacts keep working at their canonical URLs and their gumloopartifacts.com URLs. Nothing is served on the new organization domain until its status is Active.
No. An organization can claim one custom artifact domain at a time. Remove the current domain before adding a different one.
No. A custom domain is an alternate URL for the same artifact. An artifact with No public link stays private and uses the same access checks as its canonical URL.
Links on that domain stop working. Canonical artifact URLs continue to work.

Agents

Learn how to create and configure agents

Agent access

Owners, Users, and file sharing on an agent