Tektonactl

tektonactl — in-sandbox control tool

Overview

tektonactl runs inside a Tektona sandbox. It is on PATH for any shell created through tektona ssh. From outside the sandbox, wrap calls:

tektona ssh <sandbox-id> -- tektonactl <command> [args]

RELATED SKILL: Use tektona-cli for getting into the sandbox in the first place — installing the CLI, authenticating, creating sandboxes, SSH/VNC, preview URLs, env vars, secrets, and egress network policy / egress proxy profiles.

When to use

• An agent or human is already inside a sandbox shell and wants to drive

the GUI, capture a screenshot, or manage a long-running process.

• A driver script is calling tektona ssh <id> -- tektonactl ... to

perform computer use remotely.

Sandbox image requirement

tektonactl and its desktop subcommands rely on an X session, the tektonactl binary itself, and a few system libraries. Recommend the official desktop image unless the user specifies their own:

tektona sandbox create -i ghcr.io/tektona-ai/desktop-x11:<tag> --vnc --browser

Look up the newest tag at <https://github.com/tektona-ai/desktop-x11/pkgs/container/desktop-x11> before suggesting a command — the registry may have rolled forward since this skill was last published. As of the most recent skill release the newest tag is 0.3.2. The image ref must be deterministic — a real tag, a @sha256:... digest, or both. Bare :latest (no digest) is rejected because it floats; bare image@sha256:... digests are accepted.

When NOT to use

• You haven't created a sandbox yet — start with the tektona-cli skill.
• You want the sandbox itself paused/forked/deleted — that's `tektona

sandbox … from outside, in tektona-cli`.

• You're capturing a screenshot for a one-off look — `tektona sandbox

screenshot <id>` from outside is one command and does not require the desktop to be already started in the same way.

Top level

tektonactl info                       # identity, uptime, image digest
tektonactl desktop <subcommand>       # GUI: screenshot, mouse, keyboard, clipboard
tektonactl ca cert                    # print Tektona's egress CA as PEM

Bare tektonactl or --help prints usage and exits 0.

Injected secrets are NOT visible in the sandbox

Credentials Tektona injects (API keys, tokens — see the egress proxy profile / secrets flow in the tektona-cli skill) are attached to outbound requests at the egress boundary, outside the sandbox. They are not present in the box: not in the environment, not on disk, not readable by anything you run via tektonactl or tektona ssh. A request to a matched host (e.g. api.anthropic.com) leaves carrying the credential, but nothing inside can read it. Don't go hunting for an injected key in env vars or files — it isn't there by design. (Non-secret config passed with tektona sandbox create --env KEY=VAL is visible in-box; that's the intended split.)

tektonactl ca cert — egress CA for tools with their own trust store

When an egress proxy profile injects into a host, the proxy terminates TLS for that host, so the sandbox must trust Tektona's egress CA. Tektona stages this automatically at boot for the common tools (curl, Node, Python requests, Go, git) via the system trust store and the standard CA-bundle env vars — those work with no setup.

Some runtimes ship their own trust store and ignore the system one — Java is the usual example. tektonactl ca cert prints the current CA as PEM to stdout, so it pipes straight into such an importer and stays correct across CA rotation:

tektonactl ca cert | keytool -importcert -alias tektona \
  -cacerts -storepass changeit -noprompt

Read the live cert at boot — never bake the CA into your image: it rotates, and a baked copy goes stale.

tektonactl desktop

Drives the sandbox's desktop session. The desktop must be started before screenshot/input commands work:

tektonactl desktop start [resolution]   # default 1280x720
tektonactl desktop stop
tektonactl desktop status               # active | inactive
tektonactl desktop display              # current resolution

You can also start the desktop from outside via tektona sandbox desktop start <id> (see the tektona-cli skill).

Screenshot

tektonactl desktop screenshot                    # PNG to stdout
tektonactl desktop screenshot -o /tmp/shot.png   # write to file
tektonactl desktop screenshot --format jpeg      # JPEG

Mouse

tektonactl desktop click <x> <y>
tektonactl desktop click <x> <y> --button left|middle|right
tektonactl desktop click <x> <y> --double
tektonactl desktop click <x> <y> --triple
tektonactl desktop click <x> <y> --modifier shift|ctrl|alt
tektonactl desktop move <x> <y>
tektonactl desktop drag <x1> <y1> <x2> <y2>
tektonactl desktop scroll <x> <y> --delta-y N      # negative = scroll down
tektonactl desktop cursor                          # print current position

Keyboard

tektonactl desktop type "hello world" [--delay 12]
# Bump --delay (e.g. 150) for GTK widgets that drop fast repeats
tektonactl desktop key Return | Tab | Escape | BackSpace | ...
tektonactl desktop hotkey ctrl+s
tektonactl desktop hotkey ctrl+shift+t

Windows / clipboard

tektonactl desktop windows     # list open windows
tektonactl desktop clipboard   # current clipboard contents

--screenshot modifier

Every input action (click, move, drag, scroll, type, key, hotkey) accepts --screenshot to return a PNG of the post-action screen on stdout. Useful for closing the perception loop in one round trip:

tektonactl desktop click 600 400 --screenshot > after.png

Common mistakes

• Calling `tektonactl` from your laptop. It only exists inside the

sandbox. Wrap with tektona ssh <id> -- tektonactl ... (see the tektona-cli skill for SSH usage).

• Calling input commands before `desktop start`. They fail until the X

session is running. Run tektonactl desktop status first if unsure.

• Coordinates outside the current resolution. Check

tektonactl desktop display.