Skip to main content
The default SSH flow is certificate-backed relay access: 
nullspace ssh sb_123
The CLI creates or reuses a local key under ~/.nullspace/ssh/, asks the API for a short-lived OpenSSH user certificate for that public key, writes the certificate locally, and runs your local ssh client against the Nullspace SSH relay. API credentials can mint access, but relay login still requires private key proof of possession. When the API returns relay host-key metadata, the CLI writes a pinned known_hosts entry under ~/.nullspace/ssh/ and asks OpenSSH to verify that host key. 
nullspace ssh sb_123 -- python --version
nullspace sandbox ssh-access sb_123 --print-command
nullspace sandbox ssh-access sb_123 --json
Treat SSH certificates, access IDs, and generated commands as sensitive. They expire quickly, but they should not be pasted into logs, issue trackers, or browser-visible application state.

​
When to use SSH

Use SSH when a tool expects a real OpenSSH transport, when you want an interactive shell outside the SDK, or when you need multiplexed SSH channels. For programmatic commands and file transfer, prefer sandbox.commands, the Files API, and upload/download URLs. The relay does not expose password login or SFTP.

​
Quickstart

1

Install the CLI and OpenSSH

python -m pip install "nullspace-sdk[cli]==0.1.9"
ssh -V
The CLI handles local key creation, certificate storage, and host-key pinning. You do not need websocat for the default relay flow.
2

Create a sandbox

from nullspace import Sandbox

sandbox = Sandbox.create(template="base", timeout=600)
print(sandbox.id)
Certificate-backed SSH access works with the normal sandbox runtime. You do not need to start an OpenSSH daemon inside the sandbox.
3

Connect with OpenSSH

nullspace ssh sb_123
nullspace ssh sb_123 -- python --version
Remote command exit codes propagate through the local ssh process, so shell scripts can treat the command like any other SSH target.
4

Inspect the generated command

nullspace sandbox ssh-access sb_123 --print-command
nullspace sandbox ssh-access sb_123 --json
Use this when another tool needs the exact ssh command. The command includes a short-lived certificate path and relay endpoint.

​
SDK access

Use the SDK when application code needs to mint access for a caller-supplied public key: 
from pathlib import Path
from nullspace import Sandbox

sandbox = Sandbox.connect("sb_123")
access = sandbox.create_ssh_access(
    public_key=Path("~/.ssh/id_ed25519.pub").expanduser().read_text(),
    expires_in_minutes=10,
)
print(access.command)

​
Supported behavior

CapabilityStatus
Public-key proof of possessionSupported
Short-lived OpenSSH user certificatesSupported
Relay host-key pinningSupported when host-key metadata is returned
Interactive shellsSupported
SSH exec requestsSupported
PTY allocation and resizeSupported
Multiple channels on one SSH connectionSupported
Password authenticationNot supported
SFTP and SSH subsystemsNot supported

​
Troubleshooting

SymptomCheck
nullspace ssh is missingInstall the CLI extra with python -m pip install "nullspace-sdk[cli]==0.1.9".
Permission denied (publickey)Re-run nullspace ssh so the CLI refreshes the certificate, and make sure the matching private key is available locally.
Certificate invalid or expired accessMint a fresh certificate; SSH access is intentionally short-lived.
Host-key verification failsRemove stale relay entries from the CLI-managed known_hosts file shown in the generated command, then retry.
File copy fails through SFTPUse sandbox.files.upload, sandbox.files.download_url, or volume file APIs.
Relay connection is refusedConfirm the sandbox is running and that the deployment has SSH relay enabled.

​
Legacy signed WebSocket fallback

Older deployments may expose SSH through a signed public port-22 websocket_url with websocat in the OpenSSH ProxyCommand. That URL is a bearer credential and is not the default product SSH flow. Prefer nullspace ssh whenever the relay is available.