Skip to content

DocsGuides

Artifacts

A Computer's artifacts are the files it keeps beyond its sessions. They are stored outside the Computer, so they stay through Stop and Start, and you can list, upload and download them with the project key while the Computer is stopped. Session files are temporary (Persistence): keep in artifacts what a later session or your application will need.

  • The agent saves its outputs there and reads the inputs you put there. Every session of the Computer sees the same files.
  • A Computer holds up to 100 GiB of artifacts. A single file is limited only by the disk of whatever saves or reads it (Limits).
  • Artifacts stay until they are deleted. Deleting the Computer deletes its artifacts too: they can't be reached once the storage tokens issued before the delete lapse, within 30 minutes, and Pine deletes them 25 hours later.

Files are named by paths such as reports/q3.pdf. Folders are part of the path, so there is nothing to create first. A path is up to 900 bytes, without control characters, and no part of it between slashes may be empty, . or ..; spaces and other characters are fine. Saving to a path that already holds a file replaces it. Pine keeps one version of each file: to keep earlier versions, save each under its own name, such as reports/q3-v2.pdf.

A turn returns its deliverables in turn.result.artifacts. Each entry's root tells you how to download it:

  • workdir: read relative_path through the session file API. These files last until the Computer stops; their size, hash and other metadata describe the file when the turn returned it.
  • artifact_store: use computer_id and relative_path with the artifact SDK. Downloads go directly from storage, including large files and files read after the Computer stops. These references may have no file metadata.

Downloads return the current contents at the path: replacing a file changes what you download, and a missing or deleted file returns a not-found error. Only files returned as deliverables appear in the result; other saved files remain available through the artifact SDK. The same references appear in result events.

To download a returned saved file:

ref = turn.result.artifacts.find { |file| file.fetch("root") == "artifact_store" }
client.artifacts(ref.fetch("computer_id")).download(ref.fetch("relative_path"), "report.pdf")

The artifact client's open method streams bytes instead of saving to disk. Workdir files continue to use the existing session file methods.

Playground shows all returned files together. Downloading a saved file there requires a running Computer with public artifact links available. SDK downloads work while the Computer is stopped and do not need public links.

In a session

A session's agent reaches the artifacts only if you allow it when you create the session. Its artifact_access is fixed for the session's life:

artifact_access The session's agent can
none (default) Cannot read, save or return Computer artifacts.
read_only List, find and read files.
read_write Also save and remove files, and make public links.

Your own access with the project key doesn't depend on it. The default none preserves worktree-only results. Before opting into artifact access, update your SDK and handle artifact_store entries in the result. Older integrations that assume every result file is in the workdir must be updated before enabling artifact access. Downloading a saved reference requires your project key, not a session token or a public link.

session = computer.create_session(name: "researcher", artifact_access: "read_write")
session.artifact_access  # => "read_write"

On the Computer, the agent uses its pine-artifact command. Commands you run in the session's shell don't have it: your application reaches the artifacts through the SDK, as below.

Command What it does
pine-artifact save <file|folder> [<path>] Saves a file as <path> (by default, its name), or a folder's files under <path>/. --note TEXT adds a description shown in listings. --move deletes the local file once it is saved.
pine-artifact get <path> [<dest>] Copies a file into the session, or a whole folder when the path ends in /. The copies are read-only.
pine-artifact ls [<folder>] [-R] Lists a folder, or everything below it with -R.
pine-artifact find <text> Finds files whose path or note contains the text.
pine-artifact cat <path> Writes a file to standard output, to stream it into another program.
pine-artifact rm <path>... Removes files, for every session and for you. There is no undo.
pine-artifact link <path> [--expires 24h] Prints a public link to the file.

With artifacts on, the agent learns that pine-artifact keeps files beyond the session. It saves what your task asks it to keep, or what a later session will need, and leaves scratch files out. Say in your task what to keep, for example: "Save the final report as an artifact at reports/q3.pdf, with a one-line note."

From your application

client.artifacts(computer_id) returns the artifacts of one of the project's Computers, running or stopped. The handle gets a short-lived storage token from Pine, then sends every request, file bytes included, directly to the storage service the token names, Google Cloud Storage (storage.googleapis.com). Your application needs to reach that host. Reuse one handle for a run of calls; it renews its token before the token lapses.

list returns one folder level: its files, with path, size, updated_at, content_type and note, and its folders. Set recursive to list every file below the prefix instead. A long listing comes in pages: pass the page's next token back until it is empty, as below. upload and download resume a dropped connection where it stopped; download writes to a temporary file beside the destination and renames it when complete. open streams a file without keeping a local copy.

require "pathname"

artifacts = client.artifacts(computer.id)

# A String is the file's bytes; a Pathname or an IO is read from the local disk.
artifacts.upload("inputs/brief.pdf", Pathname("brief.pdf"), note: "Client brief")

page_token = nil
loop do
  page = artifacts.list(prefix: "reports/", page_token: page_token) # recursive: true lists every file below
  page.files.each { |file| puts "#{file.path} #{file.size} #{file.note}" }
  page_token = page.next_page_token
  break if page_token.nil? || page_token.empty?
end

artifacts.download("reports/q3.pdf", "q3.pdf")

# A large file, streamed in chunks:
artifacts.open("data/events.csv") { |chunk| process(chunk) }

Copy and delete

copy copies a file from another of the project's Computers, or from elsewhere in this one, inside storage. Nothing passes through your application, whatever the file's size. It returns the new file. delete removes one file.

# Start a new Computer with the files a previous one kept.
artifacts.copy(previous.id, "reports/q3.pdf", "inputs/q3.pdf")
artifacts.delete("reports/q3-draft.pdf")

A running Computer can make a link to one of its artifacts that anyone can open to download the file, without a Pine credential. The link always serves the file's current version. It stops working when the Computer stops or its services restart, or at the expiry you set, up to 30 days; without an expiry, it works until the Computer stops. Make a new link after a Start.

The agent makes one with pine-artifact link. Your application uses the running Computer:

link = computer.artifact_link("reports/q3.pdf", expires_in_seconds: 86_400)
link["url"]  # share this

Anyone who has the link can download the file until it stops working, so share it only with the people the file is for.

Errors

Error When What to do
ArtifactNotFoundError No file at the path, for open, download, delete, or the source of copy. Its path names it. Check the path with list.
ArtifactStorageFullError The Computer's artifacts have reached their limit. upload and copy save nothing. It reports used_bytes and limit_bytes. Delete files the Computer no longer needs, then save again.
A 404 from Pine, COMPUTER_NOT_FOUND The Computer, or the source Computer of a copy, is unknown, deleted, or in another project. Check the Computer ID. A deleted Computer's artifacts can't be reached.
A retryable error from Pine Pine couldn't issue a storage token. Try again.
By approval Approved developers get the integration guides, the API reference and the SDKs.