Files and Git

Read, write and watch files in a sandbox, and read and change a git repository in it, over the HTTP API or the TypeScript SDK.

The files API lets a client work with the file system of a sandbox without a shell. Use it to build an editor, a file tree or a change view next to an agent. By default, every operation runs in the sandbox as the image user, the same user as tektona ssh and processes. A file that you write has the same owner as a file that the agent writes. To work on files that the image user cannot change, see Edit files as root.

All endpoints are under /v1/sandboxes/{sandboxId} at the access endpoint of the sandbox, not at the API host. A path is absolute, or relative to the sandbox working directory. ~ and ~/… name the home directory of the user that the operation runs as, for example path=~/.bashrc. The API refuses ~name with 422. A ~ later in a path, as in a/~/b, is a plain name. Responses always contain absolute paths. The TypeScript SDK wraps every endpoint and finds the access endpoint for you.

Access endpoint

Read the access endpoint of a sandbox from access_endpoint in GET /v1/sandboxes/{sandboxId}, for example https://fr-par-1.access.sandbox.tektona.app. One access endpoint serves every sandbox of a region. The API host answers the files endpoints with 421 use_access_endpoint. In the API reference and in the OpenAPI document, every files and git operation names the access endpoint as its server, with the variable access_endpoint.

ACCESS_ENDPOINT=$(curl -sf -H "Authorization: Bearer $TEKTONA_API_KEY" \
  "$TEKTONA_API_URL/v1/sandboxes/$SANDBOX" | jq -r .access_endpoint)

Send the same API key to the access endpoint. access_credentials in GET /v1/sandboxes/{sandboxId} lists the credentials that the access endpoint takes. A client that holds none of them, such as a browser with a session cookie, gets a scoped access token from the API host:

POST /v1/sandboxes/{sandboxId}/access-tokens   {"actions": ["sandbox.files.list", "sandbox.files.get"]}
{ "token": "tsat_…", "access_endpoint": "https://fr-par-1.access.sandbox.tektona.app", "actions": ["sandbox.files.get", "sandbox.files.list"], "expires_at": "2026-10-06T08:15:00Z" }

The token works on this sandbox only, for the listed actions (all files and git actions when you omit them), for 15 minutes. It still needs your permissions on the sandbox, and a change to your roles or API keys ends it. The access endpoint reads no cookie.

Access

OperationWho can do it
List, read, watchEveryone who can observe the sandbox
Write, delete, move, create a directory, set a mode or an owner, upload an archiveEveryone who can operate the sandbox
Create a signed URLDownload: everyone who can observe the sandbox. Upload: everyone who can operate it
Any file operation with userEveryone who can operate the sandbox
All git operationsEveryone who can operate the sandbox

Git needs permission to operate the sandbox because git runs the configuration and the filters of the repository. See Sharing sandboxes for who can observe and who can operate a sandbox.

A paused sandbox returns 409. Add resume=true to the query to wake it. A sandbox that started before the files API existed returns 409 sandbox_update_required. Restart the sandbox to use the files API. A sandbox runs at most 8 file and git operations at once, plus 2 git operations with a remote (clone, fetch, pull, push). A call that waits more than 10 s for its turn returns 409 busy; retry it.

A refused call returns an application/problem+json body. Its type holds the error code, for example not_found, precondition_failed or too_many_transfers, and detail holds a message. The API reference lists the codes of each status.

Read files

List a directory. depth sets how many levels to return (default 1, at most 32). depth=0 returns only the entry at the path:

GET /v1/sandboxes/{sandboxId}/files?path=src&depth=2
{
  "entry": { "path": "/workspace/src", "name": "src", "type": "directory", "size": 4096, "mode": 493, "uid": 1000, "gid": 1000, "owner": "dev", "group": "dev", "modified_at": "2026-10-01T09:00:00Z" },
  "entries": [ { "path": "/workspace/src/main.go", "name": "main.go", "type": "file", "size": 812, "mode": 420, "uid": 1000, "gid": 1000, "owner": "dev", "group": "dev", "modified_at": "2026-10-01T09:00:00Z" } ],
  "truncated": false
}

A listing never follows a symlink below path. A symlink is listed with its symlink_target, also when the target is missing. When path itself is a symlink to a directory, the listing shows the entries of that directory, as ls link/ does.

To skip folders in one call, repeat exclude (64 at most). A name without / matches at any depth, and a name with / matches a path below path:

GET /v1/sandboxes/{sandboxId}/files?path=.&depth=5&exclude=node_modules&exclude=web/dist

gitignore=true skips what git ignores in the repository, and the .git folder. It needs write access to the sandbox, because git runs the repository's configuration. Outside a repository it returns 422 not_a_git_repository. A skipped entry does not count against limit.

A listing returns 5000 entries by default (limit, at most 20000). It lists level by level, in name order inside each folder. It stops at limit or at about 6 MiB of reply, and sets truncated: true. per_dir_limit keeps the first entries of each folder in name order, so that one large folder such as node_modules does not use up limit:

GET /v1/sandboxes/{sandboxId}/files?path=.&depth=3&per_dir_limit=200

A cut listing names, in truncated_paths, each folder that it did not fully list. The order is the order of the listing. A folder in entries above depth that is not in truncated_paths is complete, unless you cannot read it. To get the rest of a folder from truncated_paths, list it again without per_dir_limit, with the depth that remains below it. That listing can be cut too. truncated_paths can name path itself: a folder with more entries than limit (at most 20000) cannot be listed in full, so skip a part of it with exclude. A folder of more than 100,000 entries returns 413 (see Transfer limits). A folder that the listing did not read can turn out to be empty:

{
  "entry": { "path": "/workspace", "type": "directory" /* … */ },
  "entries": [ /* … */ ],
  "truncated": true,
  "truncated_paths": ["/workspace/node_modules", "/workspace/web"]
}

mode holds the permission bits as a decimal integer: 493 is 0o755. owner and group are the names of uid and gid in the sandbox's /etc/passwd and /etc/group. They are absent when those files have no name for the id.

Read a file of any size. The response body contains the raw bytes:

GET /v1/sandboxes/{sandboxId}/files/content?path=src/main.go

An unconditioned read of a file up to 1 MiB has a strong SHA-256 ETag. Larger reads stream without an ETag. Use HEAD to get the size and an ETag for a file up to 1 GiB. Send If-None-Match on GET to get 304 when a file up to 1 GiB has not changed. Files above 1 GiB do not support conditional reads or saves. A Range read has no ETag. With Range and If-None-Match, a matching ETag returns 304 before the range runs. HEAD ignores Range. A range outside the file returns 416 with Content-Range: bytes */<size>.

To resume a download, send Range: bytes=<offset>- with If-Range: <ETag>. When the file still has that strong ETag, the reply is 206 with the rest and the ETag. When the file changed, the reply is 200 with the whole file. If-Range with a date or a weak ETag, or for a file above 1 GiB, always gets the whole file.

Write files

Send the raw bytes as the request body, with no file size limit. Missing parent directories are created:

PUT /v1/sandboxes/{sandboxId}/files/content?path=src/main.go
If-Match: "9f86d08…"
  • If-Match writes only when the file still has this ETag. Otherwise the API returns 412 with the code precondition_failed.
  • If-Match accepts a current file up to 1 GiB. Above that size, the API returns 422 invalid_argument before the upload starts.
  • If-None-Match: * writes only a new file.
  • mode sets the permission bits as a decimal integer from 0 to 4095, for example mode=493 for 0o755. The file gets the mode before it replaces the target, so a script never appears without its execute bit.

When a write returns, the bytes of the file are on disk: the API syncs the temporary file before it replaces the target, and then tries to sync the folder. If the file sync fails, the write fails with 500 internal and the old file stays. A crash of the sandbox in the first seconds after a write can bring back the old file, complete, but never a half-written one.

The API uploads to a temporary file before it replaces the target. A cut upload leaves the old file. The new file has a new inode, so reload it in an editor. Hard links keep the old bytes. The API follows a symlink and keeps the old mode without setuid and setgid. An upload as root keeps the old owner. Guest processes do not share the API path locks.

Delete and move:

DELETE /v1/sandboxes/{sandboxId}/files?path=build&recursive=true
PUT    /v1/sandboxes/{sandboxId}/files/move   {"from": "a.txt", "to": "b.txt", "overwrite": false}

A directory that is not empty needs recursive=true. A recursive delete removes a directory symlink, but not the directory that it points to. A move to an existing path needs "overwrite": true.

Create a directory, set a mode, and set an owner:

PUT /v1/sandboxes/{sandboxId}/files/directory   {"path": "build/out", "mode": 448}
PUT /v1/sandboxes/{sandboxId}/files/mode        {"path": "run.sh", "mode": 493}
PUT /v1/sandboxes/{sandboxId}/files/owner       {"path": "run.sh", "owner": "dev", "group": "dev", "user": "root"}

files/directory creates the missing parents too, like mkdir -p. mode applies only to the last directory, and only when the call creates it. The reply has "created": false when the directory was there already. Another entry at the path returns 409 already_exists. files/mode follows a symlink and is not recursive. Only the owner of a file, or root, can change its mode.

files/owner works like chown. owner and group take a name from the sandbox's /etc/passwd and /etc/group, or a number. Omit one to keep it. It follows a symlink and is not recursive. Only root can change the owner, and the owner of a file can change its group only to one of its own groups. Anything else returns 403 permission_denied.

Download a folder

Download a file or a folder as one tar or tar.gz archive. Repeat exclude to skip build output: a name without / matches at any depth, and a name with / matches a path relative to path.

curl -sf -H "Authorization: Bearer $TEKTONA_API_KEY" \
  "$ACCESS_ENDPOINT/v1/sandboxes/$SANDBOX/files/archive?path=/workspace/app&format=tar.gz&exclude=node_modules&exclude=.git" \
  -o app.tar.gz

Names in the archive are relative to path. To download several files or folders in one archive, repeat path, up to 64 times. Each one then goes in under its base name, in the order given, and two paths with the same base name return 422. An exclude with / then matches a name in the archive, such as app/build:

curl -sf -H "Authorization: Bearer $TEKTONA_API_KEY" \
  "$ACCESS_ENDPOINT/v1/sandboxes/$SANDBOX/files/archive?path=/workspace/app/README.md&path=/workspace/app/src&path=/var/log/app.log" \
  -o files.tar

Symlinks stay links, and the archive keeps modes, owners and modification times. Fifos, sockets and devices are skipped. A download that fails partway breaks the response, so a short archive never looks complete: check the exit code of your client. An archive takes one transfer slot.

Upload a folder

Upload a tar or tar.gz archive to extract it into a directory. The directory and its parents are created:

tar -C ./site -czf - . | curl -sf -X PUT --data-binary @- \
  -H "Authorization: Bearer $TEKTONA_API_KEY" \
  "$ACCESS_ENDPOINT/v1/sandboxes/$SANDBOX/files/archive?path=/workspace/site&format=tar.gz"
{ "root": "/workspace/site", "files": 42, "directories": 7, "symlinks": 1, "bytes": 183920 }

Each file is written to a temporary file and renamed over the old one, with the mode and modification time from the archive. An entry with the PAX record TEKTONA.keep_mode=1 keeps the mode of the file that it replaces, without setuid and setgid; a new file gets the mode of the entry. A cut upload never leaves a half-written file. The archive as a whole is not atomic: a failure keeps the entries before it, and the error detail names the failed entry and how many entries were written. For all or nothing, upload into a new directory, then move it with files/move.

An absolute name, a .. component, a name below a symlink from the same archive, a file over such a symlink, a device or a fifo fails with 422 invalid_argument. A hard link must point to an earlier file of the archive.

Share a file with a signed URL

A signed URL lets a client without Tektona credentials, such as a CI job or a browser, download or upload one file, or download a folder. Create it on the API host with your own credentials. The URL points at the access endpoint:

POST /v1/sandboxes/{sandboxId}/files/signed-url   {"path": "dist/app.zip", "method": "GET", "expires_in": 300}
{ "url": "https://fr-par-1.access.sandbox.tektona.app/v1/files/signed?token=…", "method": "GET", "expires_at": "2026-10-06T08:05:00Z", "single_use": false }

Then use the URL with no other header:

curl -sf "$URL" -o app.zip
curl -sf -X PUT --data-binary @report.pdf "$UPLOAD_URL"
  • Add "format": "tar" or "format": "tar.gz" to a GET URL to download the folder at path as one archive, as files/archive does. An archive URL takes GET only.
  • A URL expires after expires_in seconds, 300 by default and 900 at most.
  • A GET URL also takes HEAD, Range and If-None-Match. A PUT URL uploads once. An upload that starts uses the URL up, also when it fails. A refusal before the upload starts (409 for a paused sandbox, 429, 503 when the sandbox cannot be reached) keeps the URL, so you can retry with it. A signed URL does not resume a paused sandbox: resume it with the API first. A PUT URL takes If-Match, If-None-Match: * and mode. On a signed URL, mode takes the permission bits only (0 to 511); setuid, setgid and sticky return 422.
  • Creating a GET URL needs permission to observe the sandbox. A PUT URL or a user needs permission to operate it. A change to the permissions of its creator, or to the sharing of the sandbox, ends the URL with 403.
  • The URL is the credential: share it only with the client that needs it. A refused URL returns 401 signed_url_invalid, 410 signed_url_expired or 410 signed_url_used.
  • Any web origin can use a signed URL; the browser sends no cookies with it.

Transfer limits

The access endpoint allows 32 transfers per sandbox. Additional requests return 429 too_many_transfers. A transfer stops when it moves less than 256 KiB in a minute. A failed download can end before its declared Content-Length. Check the byte count before you use the file.

A download is application/octet-stream, or application/x-tar or application/gzip for an archive, with Content-Disposition: attachment and the last part of the path as the file name. A browser saves it and never shows it as a page.

A recursive delete, a folder download or a list fails with 413 too_large for a folder of more than 100,000 entries or a tree of more than 256 levels. A list instead skips the entries of such a subfolder, sets truncated and names the subfolder in truncated_paths. A list of that subfolder itself returns 413 too_large; skip it with exclude. A folder download stops after one hour.

Edit files as root

Every file operation takes an optional user, a user name or a uid. The operation then runs as that user, the same as tektona ssh --user and tektona sandbox cp --user. Set user on list, read, write and delete as a query parameter, and on move and watch in the JSON body:

GET /v1/sandboxes/{sandboxId}/files/content?path=/etc/hosts&user=root
PUT /v1/sandboxes/{sandboxId}/files/content?path=/etc/hosts&user=root

Any operation with user needs permission to operate the sandbox, also a read. A relative path resolves against the working directory of that user, as it does for tektona sandbox cp --user. ~ names the home directory of that user, so path=~/notes.txt&user=root names /root/notes.txt. Git operations always run as the image user.

Git

EndpointReturns
GET git/status?path=Branch, upstream, ahead and behind counts, and the changed, untracked and conflicted files
GET git/diff?path=&base=Per-file changes against base (default HEAD), staged and unstaged, plus untracked files
GET git/diff/summary?path=&base=Counts of changed, added, deleted, and unknown-line files, plus changed lines
GET git/patch?path=&base=&file=&context=One unified patch of the staged, unstaged and untracked changes against base, as text/x-diff
GET git/blob?path=&oid=The raw bytes of a blob, 4 MiB at most
GET git/files?path=The tracked and untracked, not ignored paths, for a file picker
GET git/ignored?path=The paths that git ignores; a folder that git ignores as a whole is one path that ends in /

path is a directory in the repository. To show a diff of one file, read the current file with files/content and the base side with git/blob and the old_oid from git/diff.

Each diff file has a lines object with additions and deletions. The counts describe changed lines, not the total length of a file. The lines value is null for binary files and files without a known line count. The summary counts those files in files.binary and excludes them from lines.

git/patch returns a patch that git apply -p1 takes in the work tree root. It includes binary files and untracked files that git does not ignore. Repeat file to limit it to some paths, relative to the root. The Tektona-Git-Root header holds the root, and Tektona-Git-Base holds the commit that the patch compares with. A patch above 6 MiB stops after its last complete file and has Tektona-Git-Truncated: true.

curl -s -H "Authorization: Bearer $TEKTONA_API_KEY" \
  "$ACCESS_ENDPOINT/v1/sandboxes/$SANDBOX/git/patch?path=/workspace/app" -o changes.diff
git apply -p1 changes.diff

A very large work tree, for example a build folder that git does not ignore, does not fail git/status, git/diff or git/diff/summary. The reply then has truncated: true. git/status lists only the first files, but the branch fields stay correct. git/diff misses the files after the cut, or has lines: null for them. The summary counts are lower bounds.

To keep a change view current, read git/status again 300 ms after the last changes frame of a watch, once more a second later, and every 30 seconds while the view is visible. Calls for the same repository within one second share one result, so many viewers cost the sandbox one git status. That is why a read right after a change can still show the state before it.

Change a repository

EndpointDoes
POST git/cloneClone url into path; returns the root of the new work tree
GET git/log?path=&ref=&limit=&skip=Commits of ref (default HEAD), newest first; limit is 50 by default and 500 at most
GET git/branches?path=The local branches with upstream and ahead and behind counts, and the current branch
POST git/branchesCreate the branch name at start_point; checkout switches to it
DELETE git/branches?path=&name=&force=Delete a branch; an unmerged branch needs force=true
PUT git/checkoutSwitch to the local branch ref, or detach HEAD at any other revision
PUT git/stageStage files, or the whole work tree when files is empty
PUT git/unstageUnstage files, or the whole work tree when files is empty
PUT git/discardRestore the tracked files to their staged content; the changes are lost
POST git/commitsCommit the staged changes; returns the oid
PUT git/fetch, git/pull, git/pushFetch from, pull from or push to remote and branch
POST git/initCreate a repository at path, with initial_branch as the first branch; returns the root
PUT git/resetMove the branch to ref (default HEAD). mode is soft, mixed (default) or hard. files reset index entries only and need mixed
PUT git/restoreRestore files in the work tree (default), the index (staged), or both, from source; the work tree changes are lost
GET git/remotes?path=The remotes with their fetch and push URLs. The URLs never hold credentials
POST git/remotes, DELETE git/remotes?name=Add the remote name with an HTTPS url that has no credentials, or remove it
GET git/config?key=, PUT git/configRead or write key in the repository config. Allowed keys: user.name, user.email, core.autocrlf, pull.rebase, init.defaultBranch
POST /v1/sandboxes/{sandboxId}/git/commits
Content-Type: application/json

{ "path": "/workspace/app", "message": "Fix the login form", "all": true }

files are paths relative to the repository root. Git reads them literally, so * is a file name, not a pattern.

A commit takes the author from author_name and author_email. Without them, the git configuration in the sandbox must set user.name and user.email, else the API returns 422 git_identity_missing. A commit with nothing to commit returns 409 nothing_to_commit, unless you set allow_empty. all commits the changes to tracked files, as git commit --all does. It does not add new files: stage them first. A commit runs the hooks of the repository as the image user.

Clone, fetch, pull and push connect to the remote. An HTTPS remote signs in with the git credentials of the project, which the egress gateway adds. The sandbox never holds the credentials. Clone takes an https:// URL only: plain http:// and SSH remotes are not supported, and a URL with credentials returns 422 invalid_argument. remote and branch of fetch, pull and push are names: a refspec with : or a leading + returns 422 invalid_argument. Use force_with_lease to force a push.

Changes to one repository run one at a time. Fetch and push do not wait, and neither do writes through the files endpoints. A command that git refuses returns 422 git_failed with the message of git. A command with a remote stops after 4 minutes, any other command after 2 minutes. When a request times out, the command can still have run: read git/status or git/log to see the result. A 502 unknown_outcome response means the connection ended after a git write request was sent. The command can have completed. Check the repository before you retry.

The image must contain git. Otherwise the API returns 422 with the code git_not_installed.

Watch for changes

A watch streams changes under a directory over a WebSocket at the access endpoint:

GET /v1/sandboxes/{sandboxId}/files/watch?path=src&recursive=true&exclude=node_modules&exclude=.git

Send the credential in Authorization. A browser cannot set that header on a WebSocket, so it offers the protocols tektona.files.v1 and Bearer-<credential>, for example with a scoped access token. The server selects tektona.files.v1. An exclude entry without / matches a directory name at any depth. An entry with / matches a path relative to the watched directory. A watch sends no change for an excluded directory or for anything in it.

Many clients can watch the same directory. Watches with the same path, recursive, exclude, include_entry and user share one watch in the sandbox. A sandbox has at most 16 different watches and 512 open watches. A watch past either limit ends with too_many_watches. A client that falls 256 frames or 8 MiB behind the others ends with slow_consumer and does not slow the others down. A watch expires after 15 minutes. The server closes it without end. A watch ends within 15 seconds when the caller loses access to the sandbox or the user is deactivated, with end reason forbidden and close code 1008. A revoked API key does not end an open watch; the watch still expires.

The server sends JSON text frames:

{ "type": "ready", "seq": 1, "path": "/workspace/src" }
{ "type": "changes", "seq": 2, "changes": [ { "path": "/workspace/src/a.go", "op": "modified", "type": "file" } ] }
{ "type": "resync", "seq": 3, "reason": "overflow" }
{ "type": "end", "reason": "sandbox_paused" }

op is created, modified, removed, renamed or chmod:

  • renamed moves old_path to path. A renamed directory is followed by created for each entry under it. A move into or out of the watched directory is a created or a removed.
  • chmod means that the mode, the owner or a time of the entry changed.

A write through the files API shows as one created or modified of the file. The temporary file of the write does not show.

Set include_entry=true to get the entry, in the shape that the list returns, in entry on each change except removed.

end is the last frame. Its reason tells why the watch stopped, for example sandbox_paused, not_found, too_many_watches, or forbidden when you lost access to the sandbox. A watch does not follow a symlink at path: it ends with not_a_directory. Watch the target directory instead.

To keep a correct view of the directory, follow these rules:

  1. Open the WebSocket and wait for ready.
  2. List or read what you need. Keep the frames that arrive meanwhile.
  3. Apply the kept frames, then each new frame.
  4. On resync, drop the kept frames and list again.
  5. If seq skips a number, a frame is not valid, or the socket closes without end, you lost changes. Open a new watch and start again at step 1.

The TypeScript SDK checks rule 5 for you and throws FilesWatchLostError.

On this page