Skip to main content
When your Gumloop agents generate files during a conversation, those files are saved as artifacts. Reports, spreadsheets, images, code files, HTML dashboards: anything your agent creates can be viewed, downloaded, shared, and version-tracked directly 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.
You don’t need to configure anything. Agents automatically export files they create, and artifacts appear inline in the conversation as they’re generated.

​
Viewing Artifacts

When an agent exports a file, it appears as a card in the chat message showing the 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:
There is no hard limit on the size of a file an agent can create, but files larger than 50 MB cannot be previewed inline and are shown as download-only.

​
Actions

From the viewer page or the in-chat card, you can perform several actions on an artifact:
Artifact options menu showing Share, Copy link, and Download actions

​
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
Click any version to view it. The latest version is always 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

Artifacts use Gumloop’s share permissions system. You can control who can view, download, and manage each file.

​
Share Dialog

Click Share from the options menu to open the share dialog:
Artifact share dialog showing General Access options: Restricted, Organization, and Anyone
You can:
  • Add specific users by email
  • Set General Access to control broader visibility

​
General Access Levels

​
Default File Sharing

Each agent has a Default File Sharing setting that controls how new artifacts are shared when created. You can configure this in Agent Settings > Chat Preferences > Default File Sharing:
The default sharing setting applies to new artifacts only. You can always change the sharing level of any individual artifact after it’s created.

​
Requesting Access

If someone shares a file link with you but you don’t have access:
  • Not signed in: You’ll see a prompt to create a Gumloop account
  • Signed in, no access: You’ll see a Request Access button that sends a notification to the file’s owner or a workspace admin. If they have Slack connected, they can approve with a single click. See Action Requests for more details.

​
Hosting Artifacts on a Custom Domain

Every artifact is always reachable at its canonical /artifacts/{id} URL. On top of that, you can give an individual artifact its own subdomain on gumloopartifacts.com:
This is useful when you want to hand out a clean, memorable link — a dashboard, a report, or an interactive HTML artifact — without exposing the internal artifact ID.
The custom domain is an alternate URL for the same artifact, not a separate copy or a published snapshot. Access checks, version behavior, and credentials are identical on both URLs.

​
Per-Artifact Domains

​
Enabling Hosting

Hosting is configured per artifact, from the same Share dialog as General Access. Turn on Custom Domain and the artifact’s URL appears below the toggle, with buttons to copy it or rename the alias.
Share this artifact dialog with the Custom Domain toggle enabled and the artifact's gumloopartifacts.com URL shown
You need the same level of access that lets you change the artifact’s General Access — Owner or Editor on that file. 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 will get a dead URL, and the old alias becomes available for someone else to claim.

​
Authentication and Sign-In

The custom domain is a different origin from the main Gumloop app, so visitors who aren’t already signed in there go through a handoff:
1

Open the artifact

A visitor opens your-artifact.gumloopartifacts.com.
2

Resolve the alias

The page resolves the alias to the artifact it serves.
3

Sign in if needed

If the artifact isn’t public, the visitor is sent to Gumloop’s sign-in.
4

Return to the artifact

On success, a one-time token is exchanged for a session on the artifact domain and the visitor lands back on the artifact.
The handoff validates the return URL against the artifact’s own hosted URL, and credentials are never passed through the subdomain directly.
Artifacts whose General Access is set to Anyone open without a sign-in, exactly as they do on the canonical URL.

​
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. A Restricted artifact stays restricted on its custom domain — the URL being public doesn’t make the file public.
  • Canonical links are unchanged. Links generated by agents and the Gumloop UI still point at /artifacts/{id}. The custom URL is offered alongside it for copying and sharing.

​
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 will be 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 will 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.
The per-artifact Custom Domain toggle in the Share dialog is unchanged. When your organization has an active domain, that toggle hosts the artifact on the organization domain. Its description reads: “Give this artifact its own URL on <domain>. Your sharing settings still apply.” A Restricted artifact stays restricted on the organization domain. An agent can import an artifact from its link — a canonical https://gumloop.com/artifacts/... link, a gumloopartifacts.com link, or a link on your organization’s own artifact domain — and pull that file into its sandbox. 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.

​
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 sandbox:
  • Blocks access to your Gumloop session, cookies, and storage
  • Blocks direct network requests (fetch, XHR, WebSocket)
  • Prevents opening new windows or popups
  • Automatically strips sensitive headers from any proxied requests
Safe requests (GET, HEAD) from within an HTML artifact are automatically proxied. Unsafe requests (POST, PUT, DELETE) require your explicit approval via a confirmation dialog.

​
Interactive Artifacts (Live Data)

Interactive artifacts are HTML files that pull live data from your connected integrations every time you open them. Instead of showing a static snapshot from when the agent ran, the data refreshes on each view using your own credentials.

​
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.
The HTML calls fetch('/gumloop/data/...') to request data. Gumloop intercepts these requests, runs the matching Python script in a secure sandbox, and returns the results as JSON. The HTML then renders the data.
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 will use
  • 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
Consent is per-session. If you refresh the page, you’ll see the consent overlay again. This is intentional: it ensures you’re always aware of what a file is doing.

​
Your Credentials, Your Data

Interactive artifacts run using the viewer’s connected accounts, not the creator’s. This is a core design choice. If your teammate creates a “Team Slack Dashboard” and shares it with you:
  • When they open it, they see data from their Slack account
  • When you open it, you see data from your Slack account
  • The file creator never sees your data and you never see theirs
Each time a script runs, Gumloop mints a short-lived, scoped token that only allows the specific integrations and tools that the file declared. The token expires in 5 minutes and is invalidated as soon as the script finishes. Your credentials are never exposed to the HTML itself.
If you haven’t connected a required integration, you’ll see a setup prompt asking you to connect it before the file can load. The artifact won’t execute until all required integrations are connected.

​
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

Interactive artifacts are especially powerful for teams because the same file works differently for each person.

Shared dashboards

A team lead creates a “My Open Tasks” dashboard and shares it with the whole team. Each team member opens the same link but sees their own tasks, their own calendar, their own inbox. One artifact, personalized for everyone.

Self-service tools

An ops lead creates a “Post to #announcements” tool with a form. Anyone on the team can use it to send formatted messages to the channel without needing Slack open.

Onboarding kits

Create a “New Hire Status” page that shows a new team member their onboarding checklist from Linear, upcoming meetings from Google Calendar, and key documents from Google Drive. Share the link as part of onboarding.

Client-facing reports

Build a report template that pulls live data from your CRM. Share it with stakeholders, and each person sees data scoped to their access level.

​
Credits

Every time a data script runs, the viewer is charged credits for the sandbox execution time. The creator is not charged when someone else opens their file. This means:
  • You pay for what you use, not for what others view
  • If you share a dashboard with 10 people, each person pays for their own data loads
  • If you have no credits remaining, scripts won’t execute and you’ll see an error

​
Refreshing Data

Data scripts run each time you open the artifact. If the HTML includes a refresh button or auto-refresh timer, each refresh triggers a new script execution. Keep in mind:
  • Each execution costs credits
  • Each execution creates a fresh sandbox (no state carried between refreshes)
  • Scripts have a 5-minute timeout for long-running queries

​
Error Handling

If a data script fails (the integration is disconnected, the API returns an error, or the script times out), the HTML receives an error response. Well-built artifacts will 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

All your files are accessible from a dedicated Files page at gumloop.com/personal/files. This page provides a centralized view of every artifact you’ve created or received across all your agent conversations. The Files page has three tabs for filtering your view:
Files page showing the Shared with me tab with file cards grouped by date
You can search files by name, filter by media type, and sort by date. Each file card shows a thumbnail preview, filename, file type, and version number.

​
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 are not tied to a single conversation — they persist and are available in future conversations with the same agent.

​
How Workspace Scope Works

  • Project members share a common workspace. Files saved to .workspace/ by one member are visible to other members of the same project.
  • Non-members get an isolated workspace. Their .workspace/ files are private and only accessible to them.
This is useful for agents that maintain ongoing project files, configuration, or reference data that should carry over between sessions.
Workspace files follow the same artifact system — they are versioned, previewable, and shareable just like conversation-scoped artifacts.

​
Common Questions

​
Files and versions

Artifacts are stored securely in Google Cloud Storage. Files are accessible through the Gumloop viewer or via download. They persist as long as the conversation exists.
Yes. The file’s owner (the person who ran the agent conversation that created it) or anyone with editor access can delete it. Deleting is a soft delete: the file is removed from your files list, search, filters, sharing, and API/SDK reads, but its stored versions are preserved behind the scenes. If the agent later regenerates a file with the same name, the file reappears with its version history intact.

​
Sharing and access

Yes. You can either add them by email in the share dialog, or set General Access to “Anyone” to make the file accessible via link. Enterprise admins can restrict public sharing if needed.

​
Interactive artifacts

A static artifact is a regular file (PDF, image, CSV, or even a plain HTML page) that shows the same content every time you open it. An interactive artifact is an HTML file with attached data scripts that fetch live data from your integrations each time you open it. You can tell by whether you see a consent overlay when you open the file.
Yours. Interactive artifacts always run with the viewer’s connected accounts. The creator’s credentials are never used when you open a shared file. This means you’ll see your own data, and the creator never has access to it.
Both. Agents can build artifacts with forms and buttons that trigger write actions like sending a Slack message or creating a Linear issue. These actions run with your credentials and cost your credits, just like read operations.
No. HTML artifacts run in a strict sandbox that blocks access to your Gumloop session, cookies, localStorage, and all direct network requests. The only way the HTML can reach external services is through Gumloop’s security proxy, which strips sensitive headers and blocks private network access.
Common fixes: (1) Check that all required integrations are connected in Settings > Integrations. (2) If a token has expired, disconnect and reconnect the integration. (3) Make sure you have credits remaining. (4) For very large queries, the script may have timed out (5-minute limit). Try asking the agent to reduce the data scope.

​
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. A Restricted artifact stays restricted 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

Share Permissions

Understand roles, access levels, and sharing