Tektona Docs

tektona ssh opens an interactive shell in the sandbox through the platform. You need no public IP or firewall change.

Interactive shell

tektona ssh <sandbox-id>

The CLI launches your local ssh binary with the right host and short-lived access token. Exit with Ctrl-D or exit.

The shell lands in the image's WORKDIR if set (matching docker exec), otherwise in $HOME (matching a normal SSH login). tektona sandbox cp resolves relative remote paths against the same directory.

For your own image, make that directory the session user's home. A remote tool that uploads files assumes the two are the same. See where a session starts.

Connect with a registered public key

Use a registered account key when an editor must reconnect without a new token. The SSH username contains the sandbox ID, which is not a credential.

Then name the matching private key once:

tektona ctx identity set ~/.ssh/id_ed25519
tektona ctx identity show
tektona ctx identity clear

tektona ctx id is a shorter name for the same command.

tektona ssh, tektona sandbox cp, tektona sandbox port-forward, tektona sandbox vscode, and tektona sandbox zed then authenticate with that key. Without an identity they mint a short-lived token, which is the behaviour of every earlier version. clear returns to it.

The editor commands are a special case. VS Code and Zed run their own ssh, and neither accepts a key path from the CLI, so the key must be one ssh already chooses for that host: a default name in ~/.ssh, a key in your agent, or an IdentityFile entry in ~/.ssh/config.

If ssh does not offer the key, the command stops and names the ways to fix it. It does not open with a token instead: the editor keeps the address it opened, and a token there is a credential in a file you do not expect to hold one. Add the key with ssh-add, or name it in ~/.ssh/config, or run tektona ctx identity clear to go back to tokens.

--identity (short -i) overrides the setting for one command, and TEKTONA_SSH_IDENTITY overrides the stored path:

tektona ssh <sandbox-id> -i ~/.ssh/id_work

The setting holds a path. Key material never enters the configuration file.

Name the private key. A public key signs nothing, so the CLI refuses a .pub path when the private key sits beside it. A key that lives only in an agent has no private file to name, and the CLI accepts the .pub path for it.

You can also connect with ssh directly:

ssh -i ~/.ssh/id_ed25519 <sandbox-id>@ssh.tektona.ai -p 2222
ssh -i ~/.ssh/id_ed25519 dev+<sandbox-id>@ssh.tektona.ai -p 2222

The first command uses the image user. The second command uses dev inside the sandbox.

Add a host entry for VS Code, Zed, JetBrains, scp, or rsync:

Host tektona-sandbox
    HostName ssh.tektona.ai
    Port 2222
    User dev+<sandbox-id>
    IdentityFile ~/.ssh/id_ed25519

Tektona accepts Ed25519, FIDO2 (sk-), ECDSA, and RSA keys. An RSA key needs 2048 bits or more.

If your client supports FIDO2, use a FIDO2 security key. It needs a touch for every connection. OpenSSH creates one with this command:

ssh-keygen -t ed25519-sk

Key removal blocks the next connection. It does not end an active SSH connection.

Run a single command

Anything after -- becomes the remote command:

tektona ssh <sandbox-id> -- whoami
tektona ssh <sandbox-id> -- cat /etc/os-release
tektona ssh <sandbox-id> -- bash -lc 'cd repo && pnpm test'

Stdout and stderr stream live, and the exit code propagates.

Resuming a sleeping sandbox

If the sandbox is hibernated or suspended, tektona ssh resumes it for you and connects once it's running. While it wakes you'll see Resuming sandbox… — an animated spinner in an interactive terminal, or a plain one-line message when the output is piped or you're running a -- <command>. A slow resume is waited out (up to a few minutes); genuine SSH auth or host errors are surfaced as usual.

Print without connecting

To inspect or reuse the resolved ssh invocation (for example, to plug it into another tool), pass --print:

tektona ssh <sandbox-id> --print

The CLI prints the full ssh command and exits without connecting. With an identity configured, the printed command uses the key and does not expire. With no identity it carries a token, which expires after one hour.

Port forwarding

Use tektona sandbox port-forward to tunnel TCP ports from your machine into a sandbox. It uses the same brokered connection as tektona ssh: no public IP, no key management, no firewall changes required.

For HTTP-only ports a shareable URL is usually simpler. See tektona sandbox preview.

File transfer over SFTP

Use tektona sandbox cp to upload and download files between your local machine and a sandbox. It uses a native Go SFTP client and does not require OpenSSH or openssh-sftp-server in the image. No public IP, no key management, no firewall changes required.

See tektona sandbox cp --help for the full reference.

Combine with `sandbox create`

Create a sandbox and SSH into it in one step:

tektona sandbox create tektona/desktop --egress-network-policy tektona/open --ssh

Same flag works for tektona sandbox fork --ssh.

SSH access