Troubleshooting

If something isn't working as expected, walk through the relevant section below before reaching out. Most issues come down to one of: auth, validation limits, attached resources not re-attached after restore, or the guest application itself.

Session creation hangs or never becomes RUNNING

Check, in order:

1. Endpoint: is TENKI_API_URL (or WithBaseURL) pointing at the right environment?
2. Auth token: is TENKI_API_KEY set, valid, and not expired?
3. Resource limits: is --cpu between 1 and 16 and --memory-mb between 512 and 65536?
4. Snapshot: if you passed --snapshot, does it have a READY state?

Inspect the session record directly:

tenki sandbox get --session <session-id> --json

Snapshot restore works but data from a prior volume is missing

That is expected unless you re-attach the volume. Snapshots do not automatically restore prior volume attachments.

Re-attach explicitly:

tenki sandbox create --snapshot <snapshot-id> --volume <volume-id>:/workspace/cache

Or after the session is up:

tenki sandbox volume attach <session-id> <volume-id> --mount /workspace/cache

SSH fails

Check:

• the session still exists and is RUNNING (tenki sandbox get --session <session-id>)
• your keys were added at create time (--authorized-key / --authorized-keys-file) or via ssh-keys set
• if you're using the managed SSH config, run tenki sandbox ssh config status to verify the assets are installed
• the session was created with inbound enabled if your environment requires it

Reset the authorized keys to a known-good set:

tenki sandbox ssh-keys set --session <session-id> --keys-file ~/.ssh/authorized_keys

Port exposure fails

Check:

1. The app is actually listening inside the guest. Verify with tenki sandbox exec ... -c 'ss -tlnp'.
2. The right port is exposed. tenki sandbox ports --session <session-id> lists the active set.
3. Inbound is allowed. Inbound is enabled by default; exposure is rejected only if the session was created with --allow-inbound=false (allowInbound: false). tenki sandbox get --session <session-id> reports allow_inbound — as do the SDKs, via the accessors listed here — and you cannot toggle it after create.

Don't hard-code preview hostnames in client code. Always use the preview_url returned by expose.

npm install, pip install, or git clone fails inside the guest

Every SDK and the CLI enable outbound networking at create time, so a fresh session reaches the internet without any extra flag or option. Check what the guest itself sees before digging into the tool:

tenki sandbox exec --session <session-id> -c 'curl -sS -o /dev/null -w "%{http_code}\n" https://registry.npmjs.org'

A 200 means egress is working and the failure is in the package manager, not the network. Then check:

• proxy and registry variables the session inherited from --env (HTTP_PROXY, HTTPS_PROXY, NPM_CONFIG_REGISTRY, PIP_INDEX_URL)
• the tool's own verbose output (npm install --verbose, pip install -v, GIT_TRACE=1 git clone ...)
• for private registries and private repos, whether the session has the credentials it needs (--env, or githubToken / github_token alongside cloneRepoUrl in the SDKs)

tenki sandbox get --session <session-id> reports the allow_outbound value the session was created with, and the SDKs expose the same value — see Port exposure and networking.

Command execution times out

Increase the timeout:

tenki sandbox exec --session <session-id> --timeout 5m -c 'long-running-command'

result, err := session.Exec(
  ctx,
  "bash",
  tenkisandbox.WithArgs("-lc", "long-running-command"),
  tenkisandbox.WithTimeout(5*time.Minute),
)

If you need to keep running an unbounded process, start it from a template start command (--start-cmd) and poll for completion with subsequent exec calls. Backgrounding it over exec works for ad-hoc runs, but does not survive a guest-agent restart — see exec hangs when starting a background server.

exec reports flag provided but not defined: -lc

exec parses its own flags first, so -lc is read as a CLI flag rather than a shell argument. To run a shell one-liner, use -c (tenki sandbox exec -c '...'). To pass flags straight to a specific program, put them after -- so the CLI stops parsing its own flags (tenki sandbox exec -- bash -lc '...').

exec hangs when starting a background server

exec streams the command's stdout and stderr until they close. A process backgrounded with a bare & still holds those streams open, so exec waits for it forever (for example python3 -m http.server 3000 & never returns).

Redirect the background process's output and detach its stdin so it no longer holds the stream:

tenki sandbox exec -c 'python3 -m http.server 3000 >/home/tenki/server.log 2>&1 </dev/null &'

exec returns as soon as the foreground shell exits, and the server keeps running. Then tenki sandbox expose --port 3000. Use /home/tenki or an attached volume for logs that must survive a pause. /tmp is cleared when a session pauses.

A process started this way is not durable. It runs inside the guest-agent's own cgroup, so a guest-agent restart kills it, and nohup does not change that — it blocks SIGHUP, which is not the signal involved. Pause and resume restore VM memory, so such a process does survive a pause with the same PID, which makes it look more durable than it is. For anything load-bearing, use a template start command (--start-cmd) with a readiness probe.

Auth errors

Volume errors

CLI rejects bare numeric sizes:

# rejected
tenki sandbox volume create ... --size 1024

# accepted
tenki sandbox volume create ... --size 10GB
tenki sandbox volume create ... --size 10GiB

Still stuck?

Email us at hello@tenki.cloud with:

• the session or snapshot ID
• the CLI command or SDK call you ran
• the full error message
• the time of the failure