Tenki Sandbox MCP

Return the identity and workspaces for the current API key. Cheap credential test.

Takes no parameters.

Boot a throwaway microVM, run a snippet (shell/python/javascript), return its stdout/stderr/exit code, and tear the sandbox down. Cost-guarded and self-terminating. Use this for one-shot execution when you don't need a persistent sandbox. Output over ~64KB per stream is truncated head+tail — and the sandbox is gone, so for large output use tenki_create_sandbox + tenki_exec and page through the retained file.

Create a persistent sandbox microVM, optionally from a snapshot or template image. Returns the session (id, state) and its data-plane endpoint. Boots in ~2s. Use tenki_exec / tenki_read_file / tenki_write_file against the returned session_id.

Fetch a sandbox's current state and metadata.

List sandboxes for the workspace.

Terminate (destroy) a sandbox. The microVM and its filesystem are gone after this.

Pause a sandbox (snapshot + suspend) so it can be resumed later.

Resume a previously paused sandbox.

Extend a running sandbox's wall-clock lifetime by N seconds so it isn't auto-terminated at its max-duration cap.

Update mutable fields on an existing sandbox — its name, tags, idle timeout, or max duration.

Terminate MULTIPLE sandboxes in one call (bulk). IRREVERSIBLE — every listed sandbox and its filesystem is destroyed. Use tenki_terminate_sandbox for a single one.

Report client-side activity on a sandbox to reset its idle timer and keep it from being reaped as idle (a keep-alive heartbeat).

List every sandbox belonging to a specific workspace (defaults to the API key's workspace) — useful for spotting leaked, still-billing sandboxes across the workspace.

Run a command in an existing sandbox and return stdout, stderr, and exit code inline. Streams over max_output_bytes (default 64KB) come back as a head+tail preview with the full output retained at stdoutPath/stderrPath in the sandbox.

Read a UTF-8 text file from a sandbox (paths under /home/tenki).

Write a UTF-8 text file to a sandbox (paths under /home/tenki).

List a directory in a sandbox, including dotfiles (.git, .env, .gitignore) by default — set include_hidden false to omit them.

Get metadata (size, mode, type, timestamps) for a file or directory in a sandbox. Use to check whether a path exists or inspect it before reading/removing.

Create a directory in a sandbox. Set recursive to also create any missing parent directories (mkdir -p).

Delete a file or directory in a sandbox. Set recursive to remove a non-empty directory and its contents (rm -r).

Move or rename a file or directory within a sandbox. Both paths are under /home/tenki.

Run a git operation in a sandbox. Only clone, checkout, diff, and log are supported by the API — for any other git command (status, add, commit, push, ...) use tenki_exec with `git ...`. clone arg keys: repo (required, the URL), branch?, depth?, directory?. CAVEAT (live-verified): checkout/diff/log run in the session's working directory (/home/tenki), which is not a repository and has no directory arg — so on a repo cloned into a subdirectory they fail with 'not a git repository'. Use tenki_exec with `git -C <directory> ...` instead (e.g. `git -C /home/tenki/hw log -n 2`). For reference, their arg keys are — checkout: ref (required), create? ('true' = -b); diff: range? or base?+head?, path?; log: max_count?, range?, path?.

Expose a port from a sandbox and get a public preview URL. Useful when an agent starts a web server it wants to show.

List the ports currently exposed from a sandbox.

Remove an inbound port exposure from a sandbox, taking its public URL/preview offline. Use this to un-publish a port previously exposed with tenki_expose_port.

Create a shareable public preview URL for a port in a sandbox. The sandbox must have inbound networking enabled (create it with allow_inbound).

Open a viewer-token-gated (AUTHENTICATED-mode) preview. USE tenki_expose_port OR tenki_create_preview_url INSTEAD for an ordinary web server: for any port other than the web terminal (7681) the API deliberately returns a non-regional fallback host that currently has no edge route, so the URL 404s (live-verified). The returned viewerToken does resolve via tenki_resolve_preview_token; only the URL is unreachable. Requires allow_inbound.

List the workspace's preview URLs, newest page first. Pass session_id to keep only the ones bound to that sandbox (filtered here, not server-side — so it applies to the page you fetched; raise page_size or follow next_page_token to widen it). Results are paginated: a nextPageToken in the response means more pages exist.

Fetch a specific preview URL's details by id.

Delete a preview URL by id, taking it permanently offline.

Refresh (keep-alive) a live preview by its preview token so it isn't torn down as idle.

Bind a named preview URL to a sandbox session and port (advanced routing).

Unbind a named preview URL from its current session/port (advanced routing).

Resolve a preview token to the sandbox/port it points at (advanced).

Capture a running sandbox's disk and memory as a reusable snapshot (attached volumes are NOT captured); boot a new sandbox from it later with tenki_create_sandbox + snapshot_id.

Fetch one snapshot's status and metadata by ID.

List the saved snapshots for the workspace (owner inferred from the API key).

List the snapshots captured from a specific sandbox session.

List dangling snapshots — those whose source session no longer exists — for the workspace, useful for cleanup.

Update a snapshot's mutable metadata (name and/or expiry).

Permanently delete a snapshot by ID.

Get a short-lived, pre-signed URL to download a snapshot's raw disk image (requires the snapshot to have been created with store_raw_image).

List all snapshots in a workspace (defaults to the key's first workspace). Supports pagination.

Create a workspace-scoped persistent volume — durable block storage that survives sandbox teardown. Defaults the workspace to the API key's first; override with workspace_id.

Fetch a single volume's metadata and current state by its id.

List persistent volumes in a workspace (defaults to the key's first workspace). Supports pagination.

Rename a volume (update its human-readable name). To change a volume's size use tenki_resize_volume instead.

Permanently delete a volume and destroy its data. Fails with VolumeInUse if the volume is still attached to a session — detach it first.

Grow a volume to a new size in bytes (1 MiB … 100 GiB). Volumes can grow but not shrink.

Mount a volume into a running sandbox at an absolute path. Set read_only to mount without write access.

Unmount a volume from a sandbox session.

Create a custom-image template (a reusable sandbox-image spec: base image + setup script + default resources). Build it into a bootable image later with tenki_build_template. NOTE: only a TYPED template (created with builder_spec, no legacy fields) can build a named, publishable image (image_name) that tenki_create_sandbox boots via its `image` arg.

Retrieve one template by ID.

List templates for the workspace, optionally filtered by tags.

Update mutable fields on a template. Only the fields you provide are changed; pass clear_tags to remove all tags.

Delete a template by ID. Pass force to delete even when builds or dependents exist.

Trigger a build for a template, producing a bootable image. Returns the created build — poll it with tenki_get_template_build until READY; the ready build's imageDigestRef is what tenki_create_sandbox's `image` arg takes.

Cancel an in-progress template build by its build ID.

Retrieve one template build by its build ID (state, progress, and result image). A READY build's imageDigestRef is the reference tenki_create_sandbox's `image` arg takes.

List the currently active (in-progress) builds for a given template.

Get per-second sandbox billing and usage figures for a workspace — use this for cost visibility across all of the workspace's sandboxes.

Read a workspace's sandbox quotas and retention policy: max snapshots/templates/volumes/total bytes, max concurrent and sticky sessions, max preview URLs, and the pause/snapshot retention periods. These are workspace limits — there are no per-session defaults (idle timeout and max duration are set per sandbox at creation).

Update a workspace's sandbox quotas and retention periods. Only the fields you pass change. Each quota has a matching clear_* flag to remove the override and fall back to the platform default; pass the value OR its clear flag, not both. There are no per-session defaults here — idle timeout and max duration are set per sandbox at creation.

Get the workspace's pause- and snapshot-retention periods. DEPRECATED upstream: this RPC is marked deprecated in the API — tenki_get_workspace_settings returns the same retention fields alongside the quotas. An empty response means no retention override, i.e. kept indefinitely.

Update the workspace's snapshot-retention policy: how long snapshots are kept before automatic cleanup. Pass retention_days to set it, or clear_retention to keep snapshots indefinitely (the unset state) — exactly one of the two. DEPRECATED upstream: prefer tenki_update_workspace_settings, which sets the same retention (and pause retention) alongside the quotas.

Get a short-lived signed URL to upload (HTTP PUT) a binary file to a path inside a sandbox. Use for non-text payloads too large or binary for tenki_write_file.

Get a short-lived signed URL to download (HTTP GET) a command artifact from a sandbox by its artifact id (e.g. a command's stdout/stderr artifact). Note: the API supports download-by-artifact-id only, not download-by-path.

Set the SSH authorized public keys on a running sandbox, enabling direct SSH access for the given keys.

Issue a short-lived SSH certificate for a public key, authorizing SSH access to a sandbox via the SSH gateway.

List the currently active SSH gateways for the workspace.

Report whether the server has a usable Tenki credential, which kind (API key vs OAuth session token), and the endpoint it targets — verified with a live identity probe. Call this first when other tools fail with auth errors, or when this is the only tool available (which means no credential is configured). Reports status only; it does not log in and never returns the token.

Takes no parameters.