Artifacts and files

Artifacts are the files your agent produces: reports, scripts, generated images, Word documents, transcripts. The agent writes them; you read, edit, and publish them from Files in the dashboard.

This page covers the dashboard side. For how an agent saves a file in the first place, see Artifact saves.

The Files page

Files in the sidebar has two tabs. Artifacts lists what the agent saved for the active profile. Knowledge base manages the documents the agent searches with knowledge_base_search.

The Files page, with a markdown artifact open in the preview panel

The artifact list gives you:

Search by filename
Type filters: All types, Documents, HTML, Images, Markdown, Text, Video, Other
Folders for nested paths such as coding-agent-runs/, so you open a directory instead of scanning a flat list
List or grid view, remembered across visits
Endless scroll, so a profile with hundreds of files does not need paging

The Files page grouping nested coding-agent-runs logs into a folder

Each row shows the resolved MIME type, size, and last modified time. Those come from the {filename}.nakama-meta.json sidecar the agent writes next to the file. Without a sidecar, Nakama infers the type from the extension, and sniffs the bytes for valid UTF-8 when the extension is unknown, so a Dockerfile or a notes.abc still previews as text instead of being written off as binary.

Previews by content type

Clicking a file opens a resizable panel that renders by type, not by extension:

Type	Preview
Markdown	Rendered, with a toggle to the raw source
HTML	Rendered in a sandboxed frame
Images	Inline, with a download action
Video	`<video controls>` for MP4, WebM, MOV, OGV
Code	Syntax highlighted by extension
Text, CSV, logs	Plain, unhighlighted
Word (`.docx`)	Converted to Markdown for reading

Legacy .doc (Word 97-2003) is refused with a message asking you to convert it. There is no dependable JS parser for the OLE format, and emitting mojibake would be worse than saying no.

Table of contents for markdown

A markdown artifact with two or more headings gets a collapsible Contents list above the rendered body, built from its h1 to h3 headings. Clicking an entry scrolls to that heading.

Clicking a Contents entry scrolls the preview to that section

Entries are matched back to their heading by text plus occurrence, so a script that repeats "Hook" jumps to the right one rather than the first. Clicking the second Hook below lands on the 8:40 beat, not the 0:18 one.

Clicking the second Hook entry lands on the 8:40 beat rather than the first Hook

Below two headings nothing renders, so a one-paragraph note keeps the preview it has today.

A one-heading note previews with no Contents list

The list lives in the shared artifact body, so the chat panel, the Files preview, and the public share page all show it.

Editing a markdown artifact

The artifact actions menu carries Download, Edit artifact, and Share artifact.

Edit artifact opens the markdown source in a textarea with Save and Cancel, so fixing one heading does not need another agent turn.

Editing the markdown source in place

Saving returns to the rendered preview, and the row in the list picks up the new timestamp.

The saved artifact back in rendered preview, with an updated timestamp in the list

Three things to know:

Markdown only. The write path refuses anything whose resolved type is not text/markdown with a 400, so a .docx cannot be replaced by the markdown its own preview was converted into.
A failed save keeps your buffer and shows the error, rather than dropping what you typed.
The sidecar is refreshed, so the Files list does not show a stale size and timestamp.

A failed save looks like this. The error is shown, the buffer is still there, and Save is still available:

A failed save keeps the edited buffer and shows the error

Editing requires a non-viewer role in the active org. Viewers can read and download.

Share artifact publishes the file at a tokenized URL that needs no login, and gives you a link to copy.

A published share serves a snapshot taken at publish time, not the live file. That is deliberate: a public URL should not change under a reader because an agent turn rewrote the file. Two consequences:

Saving a hand edit refreshes the snapshot, so the public link keeps up with what you just changed.
An agent rewrite does not. Use Update snapshot when you want the published copy to catch up.

HTML and SVG artifacts are never served inline on the app origin, so a published page cannot run script against your session.

Where the files live

~/.nakama/orgs/{orgId}/profiles/{profileId}/artifacts/

See Profiles for the rest of the workspace layout, and Backup and restore for what an export carries.

API

Method	Path
`GET`	`/v1/profiles/:profileId/artifacts`
`GET`	`/v1/profiles/:profileId/artifacts/content?path=`
`PUT`	`/v1/profiles/:profileId/artifacts/content?path=`
`POST`	`/v1/profiles/:profileId/artifacts/shares`
`GET`	`/v1/profiles/:profileId/artifacts/shares/status`
`DELETE`	`/v1/profiles/:profileId/artifacts/shares/:shareId`

Deleting every artifact for a profile is a platform-admin action. Deleting one file is available from its row menu to any non-viewer.

Artifacts on channels

Telegram, Discord, and WhatsApp post a share link after the reply when the agent saves a file. On Discord and WhatsApp you can also ask for the file itself and get a native attachment (WhatsApp also supports /attach). See Telegram, Discord, and WhatsApp.

Artifacts and files

On this page