Files and one-off tasks for agents

Operate a deployed Service's filesystem and run bounded commands through the API. This page is written for an AI agent. It extends the deployment protocol at https://app.tokay.io/llms.txt and assumes you hold a working credential and use the Relay node IDs GraphQL returns. Everything here is an escape hatch. The happy path needs none of it, so act on an explicit user request or a named readiness action, not on your own initiative.

Last updated July 14, 2026

The file model

• Every Service has two file scopes. SAVED is durable app owned storage. It survives deploys and restarts, mounts into live containers and one-off tasks, and is the only place durable data belongs. CURRENT is the filesystem of the live container right now. It is read only evidence and disappears when the instance is replaced.
• service.fileRoots is the map. Each root is an absolute container path such as /tokay/data or /app/uploads. Every path you pass on this page must be an absolute path inside one of these roots. /tokay/data always exists.
• SAVED roots come from declared storage paths. Tokay detects natural write directories such as ./uploads during analysis and declares them for you (author TOKAY, state STICKY). You can declare more.
• Listings validate paths immediately. Ticket minting validates nothing. A wrong path in a download or upload ticket fails at redemption, not at mint, so verify paths against a listing first.
• A one-off task is the only exec path. There is no SSH. runServiceTask runs your command in the Service's current image with its full runtime environment and SAVED storage mounted, and records the output durably.

What to call

Find the roots, then list inside them

query Files($id: ID!) {
  service(id: $id) {
    fileRoots { path scope durability taskVisible writable survivesDeploy }
    files(scope: SAVED, path: "/app/uploads", first: 200) {
      entries { name path type sizeBytes updatedAt }
      currentInstanceRef
    }
  }
}

Query fileRoots first and list inside a root. Listing path: "/" fails with "Path is not inside Saved service files" unless / is itself a root, which is true only for CURRENT. Entry type is FILE, DIRECTORY, or SYMLINK. A CURRENT listing needs a running container and returns currentInstanceRef. Save that ref when you plan to rescue.

Download files

mutation DownloadTicket($service: ID!, $paths: [String!]!) {
  createServiceFileDownloadTicket(input: {
    service: $service,
    serviceFileScope: SAVED,
    paths: $paths,
    serviceFileArchiveFormat: RAW
  }) {
    serviceFileDownloadTicket { downloadUrl expiresAt }
  }
}

Then GET {API_ORIGIN}{downloadUrl} with no Authorization header. The ticket is the authorization. Tickets expire quickly and work once. Use RAW for one file and TAR_GZ for several paths or a directory. Minting succeeds even for paths outside SAVED. The GET then returns HTTP 400 with {"error": ..., "code": "SERVICE_FILE_PATH_NOT_SAVED"}. For a CURRENT download pass serviceFileScope: CURRENT plus expectedCurrentInstanceRef from a listing.

Upload into durable storage

mutation UploadTicket($service: ID!) {
  createServiceFileUploadTicket(input: {
    service: $service,
    destinationPath: "/app/uploads/report.csv",
    overwrite: true,
    expectedSizeBytes: "1024"
  }) {
    serviceFileUploadTicket { uploadUrl maxBytes expiresAt }
  }
}

Then PUT {API_ORIGIN}{uploadUrl} with the raw bytes as the body. Success returns {"ok": true, "bytesReceived": N}. expectedSizeBytes is a BigInt scalar, so send it as a string in JSON variables. destinationPath must be absolute inside a SAVED root. A wrong destination fails at PUT with code SERVICE_FILE_DESTINATION_NOT_SAVED. The running app sees the file immediately, with no restart. Respect the returned maxBytes.

Rescue a live file

If the app wrote something important outside durable storage, copy it into SAVED before the instance changes.

mutation Rescue($service: ID!, $ref: String!) {
  copyCurrentFileToSaved(input: {
    service: $service,
    sourcePath: "/app/report.json",
    destinationPath: "/app/uploads/report.json",
    expectedCurrentInstanceRef: $ref,
    overwrite: true
  }) {
    currentFileCopy { id currentFileCopyStatus errorCode errorMessage }
  }
}

The copy is asynchronous. Poll currentFileCopy(id:) until currentFileCopyStatus reaches SUCCEEDED or FAILED (PENDING and RUNNING come first). expectedCurrentInstanceRef must come from a CURRENT listing. If the container was replaced between your read and the copy, the guard fails the copy instead of copying a different instance's file. Re-list and retry. After a rescue, declare the source directory durable so future writes survive on their own.

Run a one-off task

mutation Task($service: ID!, $command: [String!]!) {
  runServiceTask(input: { service: $service, command: $command }) {
    releaseExecution { id }
  }
}

command is argv, not a shell string. Wrap pipes and chains in ["sh", "-c", "..."]. The working directory defaults to the service root, so relative paths like uploads resolve against /app. Pass workingDirectory to change it. Poll the returned row:

query TaskResult($id: ID!) {
  releaseExecution(id: $id) { releaseExecutionState exitCode logTail }
}

releaseExecutionState reaches SUCCEEDED or FAILED. Simple commands finish in a few seconds. The task runs the Service's current image with its full runtime environment (secrets, database URLs) and SAVED storage mounted, and the run is attributed to your identity and credential. The command must exit. A server or a watch loop belongs in a Service.

Tasks are the right tool for data fixes. The managed database query endpoint is read only, but a task's framework client holds real credentials from the environment. Schema changes should still ship as migrations with a deploy, which adds rehearsal, snapshots, and confirmation for destructive changes.

Durable directories

query StoragePaths($id: ID!) {
  service(id: $id) {
    serviceStoragePaths(first: 20) {
      nodes { id storagePath serviceStoragePathState serviceStoragePathAuthor }
    }
  }
}

storagePath is relative to the service root, so uploads mounts at /app/uploads. States are PENDING (recorded, mounts after clean build evidence or user confirmation), STICKY (mounted and durable), and DETACHED (intentionally unmounted, row kept as a tombstone, data preserved). Check the existing list before declaring anything. Tokay usually detected the app's write directories already, so add one only when the user asks or the app demonstrably writes somewhere undeclared, with addServiceStoragePath(input: { service: $service, storagePath: "data" }). Detach and delete only when the user asks. detachServiceStoragePath stops mounting but keeps the stored data, reattachServiceStoragePath reverses it, and destroying data is the separate deleteServiceStoragePathData. New code should skip all of this and write under TOKAY_DATA_DIR.

Error shapes